Skip to main content
Expo support and dependencies were introduced in V2. This latest release applies to V2 and newer versions. For V1 instructions, see React Native SDK V1 (Legacy).
The Circle React Native SDK enables your mobile application to provide user-controlled wallets. The SDK supports multiple authentication methods: social login (Google, Facebook, Apple), email OTP, and PIN with security questions. Sensitive inputs, such as PINs and security answers, are encrypted by the SDK and never exposed to your app or backend. The SDK enforces end-to-end security and supports UX customization for your end-users. See the React Native SDK UI customization API for details.

SDK architecture

You must use Web, iOS, Android or React Native SDKs to access the user-controlled Programmable Wallet product. The SDK secures, manages, and communicates with your server to ensure your user keys are not exposed.
The Web and Mobile SDKs ensure that the user keyshare remains with the individual, so the user stays in full control. These SDKs only work with user-controlled wallets.
To learn more, see How it works.

Installation and Setup

Follow the installation guide on GitHub to install and configure the React Native SDK for your Expo or React Native project. The guide also includes migration instructions if you need to upgrade from a previous version.

Social Login Configuration

To use social login with the React Native SDK, additional platform-specific configuration is required. It’s not necessary to configure all providers. Follow only the sections relevant to the providers you plan to support.
For Expo projects, if you haven’t generated the native android and ios folders yet, run npx expo prebuild first before configuring social login or other native settings.

Prerequisites

  1. Follow the instructions to obtain IDs from social providers:
    1. Google
      1. Visit the Firebase console to create a Firebase project. For detailed steps, see View instructions to create a Firebase project.
      2. Add an Android app to your project:
        1. Go to Project Settings → Your apps
        2. Click Add app → Select Android
        3. Download the google-services.json (required for Google Sign-In on Android) For detailed steps, see Register your app with Firebase.
      3. Add an iOS app to your project:
        1. Go to Project Settings → Your apps
        2. Click Add app → Select iOS
        3. Download the GoogleService-Info.plist
        4. Open the file and copy the following values:
          1. CLIENT_ID: used in app.json (Expo) or Info.plist (React Native)
          2. REVERSED_CLIENT_ID: used in Info.plist URL schemes (React Native only, auto-generated for Expo)
      4. Enable Google Sign-In:
        1. Under Product categories, navigate to
          Build → Authentication → Sign-in method tab
        2. Select Google, enable it, and click Save.
      5. Get your Web client ID:
        1. Open the Google provider again
        2. In the Web SDK configuration panel, copy the Web client ID
    2. Facebook
      1. Go to the Meta for Developers Site and create a new Facebook app.
      2. In the app settings, add both iOS and Android platforms.
      3. Note down the following values:
        1. Facebook App ID
        2. Facebook Client Token (Settings → Advanced)
        3. Facebook Display Name
    3. Apple
      1. Follow Register a Services ID and note down the Service ID for Sign in with Apple on Android.
  2. Configure Social Logins in Circle Developer Console with the social provider IDs.

iOS

Social login can be configured using one of the following approaches:
  • Expo config plugin (recommended): Uses config plugins to automatically configure iOS native settings during npx expo prebuild; requires custom AppDelegate modification for Facebook SDK initialization.
  • Manual native configuration: You can manually update the native iOS project by following the steps in the React Native tab. Keep in mind that Expo prebuild regenerates native files, so manual changes must be reapplied after each run.

Step 1: Configure plugins in app.json

Add the following configuration to your app.json or app.config.js file.
This assumes you have already configured the basic SDK plugins (podfile-modifier, withCopyFiles) during the Installation and Setup section.
Complete plugins configuration example:
What each plugin does:
  • podfile-modifier: Configures iOS Podfile (required for SDK, set up during installation)
  • withCopyFiles: Copies files from prebuild-sync-src (required for SDK, set up during installation)
  • apple-signin-entitlements: Enables Sign in with Apple capability
  • infoplist-config: Configures Info.plist for social login (Facebook App ID, Google Client ID, URL schemes, Face ID description)

Step 2: Modify AppDelegate for Facebook SDK

After running npx expo prebuild, modify the generated ios/YourAppName/AppDelegate.swift to add Facebook SDK initialization.2.1 Add FBSDKCoreKit import
Your imports section should now look like:
2.2 Initialize Facebook SDK in didFinishLaunchingWithOptionsIn the application(_:didFinishLaunchingWithOptions:) method, add Facebook SDK initialization before the existing code:
2.3 Handle Facebook URL schemesAdd (or modify if it exists) the URL opening handler to process Facebook callbacks:
2.4 (Optional) Handle Universal LinksIf your app supports Universal Links, add this method:

Step 3: Copy modified AppDelegate to prebuild-sync-src

Copy the modified AppDelegate.swift to prebuild-sync-src so it persists across future prebuild runs:
The withCopyFiles plugin (configured in Step 1) will automatically restore this file from prebuild-sync-src whenever you run npx expo prebuild --clean in the future.

Android

For Expo projects: After making the changes below, place the modified files in the prebuild-sync-src folder you set up during installation, since npx expo prebuild regenerates the native files. Otherwise, those manual changes must be reapplied after each npx expo prebuild --clean.

Apple

Add manifestPlaceholders.appAuthRedirectScheme for Apple Sign-In in your app-level Gradle file (android/app/build.gradle or android/app/build.gradle.kts) under defaultConfig.

Facebook

Add the following values to android/app/src/main/res/values/strings.xml:
Where:
  • YOUR_FACEBOOK_APP_ID is your Facebook app ID
  • YOUR_FACEBOOK_CLIENT_TOKEN is your Facebook client token

Google

  1. Add the following values to android/app/src/main/res/values/strings.xml:
Where YOUR_GOOGLE_WEB_CLIENT_ID is your Google sign-in client ID.
  1. Place your google-services.json in the android/app/ directory (or prebuild-sync-src/android/app for Expo projects).
  2. Add Google Services Gradle Plugin to make the values in your google-services.json config file accessible to Firebase SDKs:
    1. Ensure the following classpath is added to your project-level Gradle file (android/build.gradle or android/build.gradle.kts):
  1. Add the following to your app-level Gradle file (android/app/build.gradle or android/app/build.gradle.kts):

SDK API references

WalletSdk

implements IWallet

IWalletSdk

interface IWalletSdk

SdkVersion

interface SdkVersion

Configuration

interface Configuration

SettingsManagement

interface SettingsManagement

SecurityQuestion

class SecurityQuestion

SocialProvider

To specify a social provider to operate on. See WalletSdk.performLogin(), WalletSdk.performLogout().
JavaScript

InputType

Enumerates the types of security questions.
JavaScript

LoginResult

Interface LoginResult

OauthInfo

Interface OauthInfo

SocialUserInfo

Interface SocialUserInfo

SuccessResult

interface SuccessResult

Error

interface Error

LoginSuccessCallback

type SuccessCallback

SuccessCallback

type SuccessCallback

ErrorCallback

type ErrorCallback

ExecuteResult

interface ExecuteResult

ExecuteResultData

interface ExecuteResultData

ExecuteResultType

Enumerates the types of challenges supported
JavaScript

ExecuteResultStatus

Enumerates the possible statuses for a challenge
JavaScript

EventListener

type EventListener

CIRCLE_PW_ON_EVENT

Constant event name for use with Expo’s NativeModule.addListener(). This event is emitted by the native SDK when certain actions occur, such as “forgot PIN” and “resend OTP” flow triggered by the user. The event payload conforms to the CirclePwEventPayload interface, containing a name property of type ExecuteEvent.

CirclePwEventPayload

Interface for the payload received when a CIRCLE_PW_ON_EVENT is triggered.

ExecuteEvent

Enumerates the possible event
JavaScript

ErrorCode

Enumerates the types of error code
JavaScript

TextConfig

Data-only class for text customization.
class TextConfig

TextConfig

Data-only class for icon text list item customization.
class IconTextConfig

TextsKey

Enum for setTextConfigsMap().
See A Index Table.

IconTextsKey

Enum for setIconTextConfigsMap().
See B Index Table.

TextKey

Enum for setTextConfigMap().
See C Index Table.

ImageKey

Enum for setImageMap().
See D Index Table.

DateFormat

Enum for setDateFormat().
JavaScript

SampleCode

JavaScript
JavaScript