MetaMask Embedded Wallets Flutter SDK Examples

This repository contains comprehensive Flutter examples demonstrating the integration of MetaMask Embedded Wallets (formerly Web3Auth Plug and Play) SDK. These examples showcase seamless authentication experiences with social logins, custom authentication, and blockchain interactions for both iOS and Android platforms.

🌟 Key Features

• Social Authentication: Google, Facebook, Twitter, Discord, Apple, and more
• Custom Authentication: Firebase, Auth0, and JWT-based authentication
• Grouped Connections: Same wallet across multiple authentication methods
• Multi-Factor Authentication (MFA): Enhanced security options
• Blockchain Agnostic: Full support for EVM chains, Solana, and others
• Cross-Platform: Unified codebase for iOS and Android
• Non-Custodial: Fully decentralized key management using Shamir Secret Sharing

📱 Available Examples

Plug and Play (PnP) SDK Examples

These examples use the latest MetaMask Embedded Wallets SDK (web3auth_flutter ^8.0.0):

Example	Description	Features
flutter-quick-start	Basic integration with social logins	EVM chains, social authentication
flutter-firebase-example	Custom auth with Firebase	Firebase Auth, JWT verification
flutter-auth0-example	Custom auth with Auth0	Auth0 integration, OAuth 2.0
flutter-aggregate-verifier-example	Grouped connections	Same wallet across multiple providers
flutter-solana-example	Solana blockchain integration	Solana wallet, SPL tokens
flutter-playground	Advanced features showcase	MFA, wallet services, multi-chain

What's new in v8

All examples target web3auth_flutter ^8.0.0 (Auth v11, Wallet Services v6, Android native 11.0.0, iOS native Web3Auth 13 via Swift Package Manager).

• iOS deployment target is 15.0. Native Web3Auth is linked by the plugin's Swift package, not a CocoaPods Web3Auth pod.
• MFALevel.DEFAULT is removed. Use OPTIONAL, MANDATORY, or NONE.
• Leave sessionTime unset so the SDK reads it from the dashboard.
• enableMFA() and manageMFA() take no arguments.
• init() sets sdkVersion and Flutter analytics. Do not set them in app code.
• Quick start and playground call getAccessToken() and refreshSession() after login.
• Custom JWT (Firebase) stays on the SFA path: LoginParams(authConnection: AuthConnection.custom, authConnectionId: ..., idToken: ...).

🚀 Quick Start

Prerequisites

• Flutter SDK 3.0.0 or higher
• Dart 2.18.0 or higher
• iOS: iOS 15+, Xcode 15+, Swift 5.x (Swift Package Manager resolves native Web3Auth)
• Android: API level 26+, compileSdkVersion 34
• MetaMask Embedded Wallets Dashboard account

Installation Steps

1. Clone the repository:

   git clone https://github.com/Web3Auth/web3auth-flutter-examples.git
   cd web3auth-flutter-examples

2. Choose an example:

   cd flutter-quick-start  # or any other example

3. Install dependencies:

   flutter pub get

4. iOS setup (if targeting iOS):

   cd ios && pod install && cd ..

5. Configure your project:

   • Create a project on the Embedded Wallets Dashboard
   • Get your Client ID
   • Choose network: Sapphire Devnet (for testing) or Sapphire Mainnet (for production)
   • Configure allowlisted URLs and bundle IDs
   • Update the Client ID in the example code

6. Run the app:

   flutter run

🔑 Key Concepts

Network Selection

• Sapphire Devnet: For development and testing (allows localhost)
• Sapphire Mainnet: For production (does NOT allow localhost)

⚠️ Critical: Never change your Client ID or Sapphire network in production - this will change all user wallet addresses permanently.

Authentication Types

• Social Logins: Pre-configured Google, Facebook, Discord, Twitter, Apple, etc.
• Custom Authentication: Bring your own JWT provider (Firebase, Auth0, AWS Cognito, etc.)
• Grouped Connections: Link multiple login methods to the same wallet address

Private Key Management

• Uses Shamir Secret Sharing (SSS) for non-custodial key management
• Same user + same config = same wallet address (deterministic)
• Keys are reconstructed from distributed shares - no single party holds the full key

📚 Documentation & Resources

Official Documentation

• MetaMask Embedded Wallets Docs
• Flutter SDK Reference
• Dashboard Setup Guide
• Migration Guides

SDK & Package

• Flutter Package on pub.dev
• GitHub Repository
• Release Notes

Community & Support

• MetaMask Builder Hub
• GitHub Issues
• Discord Community
• Twitter/X

🔧 Platform-Specific Configuration

Android Configuration

1. Set compileSdkVersion 34 in your app's build.gradle
2. Add JitPack repository to your project-level build.gradle
3. Configure deep link intent filter in AndroidManifest.xml
4. Add Internet permission to manifest

See individual example READMEs for detailed configuration.

iOS Configuration

1. Set minimum iOS platform to 14.0 in Podfile
2. Configure URL scheme in Info.plist
3. Allowlist {bundleId}://auth in the dashboard
4. Handle URL scheme in app delegate

See individual example READMEs for detailed configuration.

🛠️ Troubleshooting

Common Issues

Build errors: Update Flutter and dependencies with flutter upgrade and flutter pub upgrade

OAuth issues: Verify your dashboard configuration, allowlisted URLs, and bundle IDs

iOS deep linking: Check URL scheme configuration in Info.plist and dashboard allowlist

Android deep linking: Verify intent filter in AndroidManifest.xml and package name in dashboard

Network errors: Ensure you're using the correct Sapphire network (devnet for localhost testing)

For more help, check the troubleshooting docs or ask in our community.

🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ by the Web3Auth team