Embedded Wallets SDK for React Native
Overview
MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play/ W3A PnP) provides a seamless authentication experience for React Native applications with social logins, external wallets, and more. Using our React Native SDK, you can easily connect users to their preferred wallets and manage authentication state across both iOS and Android platforms.
Requirements
- React Native Release 0.71 and above (for Bare React Native Workflow)
- Expo SDK 48 and above (for Expo Managed Workflow)
- iOS Platform Target Version 14 and above
- Android Target SDK Version 31 and above
- Basic knowledge of JavaScript/TypeScript and React Native
Selecting your Workflow
In React Native, you have the choice to use one of the following workflows:
Bare React Native Workflow
Your Bare React Native app is entirely built on your machine. In this workflow, the developer has complete control, along with the complexity that comes with that.
Expo Managed Workflow
Your Expo app is built on your Expo's cloud, so you don't have control over the native modules used in the app. Developers build managed workflow apps using expo-cli
on their computers and a development client on their mobile devices.
The Web3Auth React Native PnP SDK is not compatible with "Expo Go" app. It is compatible only with Custom Dev Client and EAS builds.
Please run npx expo prebuild
to generate native code based on the version of expo a project has installed, before moving forward.
Installation
1. Install Web3Auth React Native SDK
- npm
- Yarn
- pnpm
- Bun
npm install --save @web3auth/react-native-sdk
yarn add @web3auth/react-native-sdk
pnpm add @web3auth/react-native-sdk
bun add @web3auth/react-native-sdk
2. Install Helper Modules
Install required helper modules for WebBrowser and Storage:
- A
WebBrowser
implementation is needed to allow our JS-based SDK to interact with the native APIs. - A
Storage
implementation is needed to store the user's session, without storing the private keys of the user in the device.
- Bare React Native Workflow
- Expo Managed Workflow
- npm
- Yarn
- pnpm
- Bun
npm install --save expo-web-browser expo-secure-store
yarn add expo-web-browser expo-secure-store
pnpm add expo-web-browser expo-secure-store
bun add expo-web-browser expo-secure-store
- npm
- Yarn
- pnpm
- Bun
npm install --save @toruslabs/react-native-web-browser react-native-encrypted-storage
yarn add @toruslabs/react-native-web-browser react-native-encrypted-storage
pnpm add @toruslabs/react-native-web-browser react-native-encrypted-storage
bun add @toruslabs/react-native-web-browser react-native-encrypted-storage
Setup
Prerequisites Before you start, make sure you have registered on the Web3Auth Dashboard and have set up your project. You can look into the Dashboard Setup guide to learn more.
Android
-
Make sure that the minimum SDK compile version in build.gradle is 31 or more.
build.gradlebuildToolsVersion = "31.0.0"
minSdkVersion = 21
compileSdkVersion = 31
targetSdkVersion = 31 -
Add the intent filter with scheme defined in your
AndroidManifest.xml
AndroidManifest.xml<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
# replace with your own scheme
<data android:scheme="web3authrnexample" />
</intent-filter> -
SDK version 31 requires you to explicitly define android:exported="true" in AndroidManifest.xml, and check whether it is correctly present or not.
AndroidManifest.xml<activity
android:name=".MainActivity"
android:label="@string/app_name"
android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode"
android:launchMode="singleTask"
android:windowSoftInputMode="adjustResize"
android:exported="true"> -
Your
redirectUrl
is your defined scheme following some identifier or your choice. For example, if your scheme isweb3authrnexample
, you can define yourredirectUrl
as web3authrnexample://auth. Make sure you register this redirectUrl in the Web3Auth Developer Dashboard.const scheme = 'web3authrnexample' // Or your desired app redirection scheme
const resolvedRedirectUrl = `${scheme}://auth`
iOS
-
Make sure that the minimum SDK compile version in Podfile is 14 or more.
Podfileplatform: ios, '14'
-
Install the Cocoa Pods within your project directory.
cd ios
pod install -
In iOS, you don't need to add
redirectUrl
as an iOS Custom URL Scheme, however, you may add it to your Info.plist, but it is not required. Make sure yourredirectUrl
is registered in the Web3Auth Developer Dashboard.
Expo Managed Workflow
-
Update the scheme in your
app.json
file.app.json{
"expo": {
"scheme": "web3authexpoexample" // replace with your own scheme
}
} -
For constructing your
redirectUrl
, you'll need to use theexpo-linking
, which will help you generate aredirectUrl
for your app. Make sure you register that URL in the Web3Auth Developer Dashboard.import Constants, { AppOwnership } from 'expo-constants'
import * as Linking from 'expo-linking'
const resolvedRedirectUrl =
Constants.appOwnership == AppOwnership.Expo || Constants.appOwnership == AppOwnership.Guest
? Linking.createURL('web3auth', {})
: Linking.createURL('web3auth', { scheme: 'web3authexpoexample' }) // replace with your own scheme
Initialize Web3Auth
1. Create a Web3Auth Instance
Create a configuration file for Web3Auth. This file will contain your Web3Auth Client ID and Network details from the Web3Auth Dashboard.
- Bare React Native Workflow
- Expo Managed Workflow
import Web3Auth, { WEB3AUTH_NETWORK, LOGIN_PROVIDER } from '@web3auth/react-native-sdk'
import * as WebBrowser from 'expo-web-browser'
import * as SecureStore from 'expo-secure-store'
const scheme = 'web3authrnexample' // Or your desired app redirection scheme
const resolvedRedirectUrl = `${scheme}://auth`
const web3auth = new Web3Auth(WebBrowser, SecureStore, {
clientId: 'YOUR_CLIENT_ID', // Get your Client ID from Web3Auth Dashboard
network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET, // or WEB3AUTH_NETWORK.SAPPHIRE_DEVNET
redirectUrl: resolvedRedirectUrl,
})
import Web3Auth, { WEB3AUTH_NETWORK, LOGIN_PROVIDER } from '@web3auth/react-native-sdk'
import * as WebBrowser from '@toruslabs/react-native-web-browser'
import EncryptedStorage from 'react-native-encrypted-storage'
const scheme = 'web3authrnexample' // Or your desired app redirection scheme
const resolvedRedirectUrl = `${scheme}://auth`
const web3auth = new Web3Auth(WebBrowser, EncryptedStorage, {
clientId: 'YOUR_CLIENT_ID', // Get your Client ID from Web3Auth Dashboard
network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET, // or WEB3AUTH_NETWORK.SAPPHIRE_DEVNET
redirectUrl: resolvedRedirectUrl,
})
2. Initialize the Web3Auth Instance
Initialize the Web3Auth instance before using any authentication methods:
import { useEffect } from 'react'
useEffect(() => {
const init = async () => {
try {
await web3auth.init()
console.log('Web3Auth initialized successfully')
} catch (error) {
console.error('Error initializing Web3Auth:', error)
}
}
init()
}, [])
Advanced Configuration
The Web3Auth React Native SDK offers a rich set of advanced configuration options:
- Account Abstraction: Configure smart account parameters.
- Custom Authentication: Define authentication methods.
- Whitelabeling & UI Customization: Personalize the modal's appearance.
- Multi-Factor Authentication (MFA): Set up and manage MFA.
- DApp Share: Share DApp sessions across devices.
Head over to the advanced configuration sections to learn more about each configuration option.
- Basic Configuration
- Advanced Configuration
import Web3Auth, { WEB3AUTH_NETWORK } from '@web3auth/react-native-sdk'
const web3auth = new Web3Auth(WebBrowser, SecureStore, {
clientId: 'YOUR_CLIENT_ID',
network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET, // or WEB3AUTH_NETWORK.SAPPHIRE_DEVNET
redirectUrl: resolvedRedirectUrl,
})
import Web3Auth, { WEB3AUTH_NETWORK, MFA_LEVELS } from '@web3auth/react-native-sdk'
const web3auth = new Web3Auth(WebBrowser, SecureStore, {
clientId: 'YOUR_CLIENT_ID',
network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
redirectUrl: resolvedRedirectUrl,
mfaLevel: MFA_LEVELS.MANDATORY,
loginConfig: {
google: {
verifier: 'google-verifier', // Get this from the Web3Auth Dashboard
typeOfLogin: TypeOfLogin.GOOGLE,
clientId: 'GOOGLE_CLIENT_ID', // Google's client id
},
jwt: {
verifier: 'jwt-verifier', // Get this from the Web3Auth Dashboard
typeOfLogin: TypeOfLogin.JWT,
clientId: 'JWT_CLIENT_ID', // Custom JWT client id
},
},
})
Blockchain Integration
Web3Auth is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Web3Auth offers robust support for both Solana and Ethereum.
Ethereum Integration
For Ethereum integration, you can get the provider and use it with ethers or viem:
// Import the required shims
import '@ethersproject/shims'
// Import the ethers library
import { ethers } from 'ethers'
// Import the Web3Auth Ethereum Provider
import { EthereumPrivateKeyProvider } from '@web3auth/ethereum-provider'
// Define the chain config for the EVM network
chainConfig = {
chainNamespace: CHAIN_NAMESPACES.EIP155,
chainId: '0x1',
rpcTarget: 'https://rpc.ethereum.org',
displayName: 'Ethereum Mainnet',
blockExplorer: 'https://etherscan.io',
ticker: 'ETH',
tickerName: 'Ethereum',
}
// Create an instance of the Web3Auth Ethereum Provider
const ethereumPrivateKeyProvider = new EthereumPrivateKeyProvider({
config: {
chainConfig,
},
})
// Setup the provider with the Web3Auth Private Key
await ethereumPrivateKeyProvider.setupProvider(web3auth.privKey)
// Create an instance of the ethers BrowserProvider using the Web3Auth Ethereum Provider
const ethersProvider = new ethers.BrowserProvider(ethereumPrivateKeyProvider)
// Get the signer for ethers
const signer = await ethersProvider.getSigner()
// Get the address of the user
const address = signer.getAddress()
// Get the balance of the user
const balance = ethers.formatEther(
await ethersProvider.getBalance(address) // Balance is in wei
)
Solana Integration
For Solana integration, you can get the private key and use it with Solana libraries:
const getSolanaAccount = async () => {
try {
const privateKey = await web3auth.getPrivKey()
// Use private key with Solana libraries
console.log('Solana private key:', privateKey)
} catch (error) {
console.error('Error getting private key:', error)
}
}
Troubleshooting
Bundler Polyfill Issues
While using Web3Auth in React Native, you may run into issues building. This issue occurs because some core packages like eccrypto
have certain dependencies which are not present within the Metro build environment.
To solve this, please have a look at our troubleshooting page for React Native Metro Bundler Issues