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).
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.
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
-
Follow the instructions to obtain IDs from social providers:
- Google
- Visit the Firebase console to create a Firebase project. For detailed steps, see View instructions to create a Firebase project.
- Add an Android app to your project:
- Go to Project Settings → Your apps
- Click Add app → Select Android
- Download the
google-services.json(required for Google Sign-In on Android) For detailed steps, see Register your app with Firebase.
- Add an iOS app to your project:
- Go to Project Settings → Your apps
- Click Add app → Select iOS
- Download the
GoogleService-Info.plist - Open the file and copy the following values:
CLIENT_ID: used inapp.json(Expo) orInfo.plist(React Native)REVERSED_CLIENT_ID: used inInfo.plistURL schemes (React Native only, auto-generated for Expo)
- Enable Google Sign-In:
- Under Product categories, navigate to
Build → Authentication → Sign-in method tab - Select Google, enable it, and click Save.
- Under Product categories, navigate to
- Get your Web client ID:
- Open the Google provider again
- In the Web SDK configuration panel, copy the Web client ID
- Facebook
- Go to the Meta for Developers Site and create a new Facebook app.
- In the app settings, add both iOS and Android platforms.
- Note down the following values:
- Facebook App ID
- Facebook Client Token (Settings → Advanced)
- Facebook Display Name
- Apple
- Follow Register a Services ID and note down the Service ID for Sign in with Apple on Android.
- Google
- 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.
- Expo
- React Native
Step 1: Configure plugins in app.json
Add the following configuration to yourapp.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.podfile-modifier: Configures iOS Podfile (required for SDK, set up during installation)withCopyFiles: Copies files fromprebuild-sync-src(required for SDK, set up during installation)apple-signin-entitlements: Enables Sign in with Apple capabilityinfoplist-config: ConfiguresInfo.plistfor social login (Facebook App ID, Google Client ID, URL schemes, Face ID description)
Step 2: Modify AppDelegate for Facebook SDK
After runningnpx expo prebuild, modify the generated
ios/YourAppName/AppDelegate.swift to add Facebook SDK initialization.2.1 Add FBSDKCoreKit importapplication(_:didFinishLaunchingWithOptions:) method, add Facebook SDK
initialization before the existing code:Step 3: Copy modified AppDelegate to prebuild-sync-src
Copy the modifiedAppDelegate.swift to prebuild-sync-src so it persists
across future prebuild runs: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
AddmanifestPlaceholders.appAuthRedirectScheme for Apple Sign-In in your
app-level Gradle file (android/app/build.gradle or
android/app/build.gradle.kts) under defaultConfig.
android/app/src/main/res/values/strings.xml:
YOUR_FACEBOOK_APP_IDis your Facebook app IDYOUR_FACEBOOK_CLIENT_TOKENis your Facebook client token
- Add the following values to
android/app/src/main/res/values/strings.xml:
YOUR_GOOGLE_WEB_CLIENT_ID is your Google sign-in client ID.
-
Place your
google-services.jsonin theandroid/app/directory (orprebuild-sync-src/android/appfor Expo projects). -
Add
Google Services Gradle Plugin
to make the values in your
google-services.jsonconfig file accessible to Firebase SDKs:- Ensure the following classpath is added to your project-level Gradle file
(
android/build.gradleorandroid/build.gradle.kts):
- Ensure the following classpath is added to your project-level Gradle file
(
- Add the following to your app-level Gradle file (
android/app/build.gradleorandroid/app/build.gradle.kts):
SDK API references
WalletSdk
implements IWalletIWalletSdk
interface IWalletSdk| Properties |
|---|
sdkVersion: SdkVersion SDK version |
| Methods |
|---|
init: (configuration: Configuration) => Promise<void> Configure the Circle endpoint for SDK to connect, reject Promise if the endpoint and appId’s format are invalid. |
setSecurityQuestions: (securityQuestions: SecurityQuestion[]) => void Set the security question list, throw Throwable when the SecurityQuestion array is empty or contains any question whose title length is not 2~512. |
addListener: (listener: EventListener) => void Register an EventListener for the app to handle events, e.g. forgot PIN. Deprecated. |
removeAllListeners: () => void Unregister all EventListener. Deprecated. |
execute: ( userToken: string, encryptionKey: string, challengeIds: string[], successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void Execute the operations by challengeId and trigger the SuccessCallback with SuccessResult after sending the request to Circle endpoint successfully. ErrorCallback will be triggered when parameters are null or invalid. |
executeWithKeyShare: ( userToken: string, encryptionKey: string, pinCodeDeviceShare: string, challengeIds: string[], successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void Execute the operations by challengeId and PIN code device share and trigger the SuccessCallback with SuccessResult after sending the request to Circle endpoint successfully. ErrorCallback will be triggered when parameters are null or invalid. |
getDeviceId: () => string? Get device ID |
performLogin: ( provider: SocialProvider, deviceToken: string, deviceEncryptionKey: string, successCallback: LoginSuccessCallback, errorCallback: ErrorCallback) ) => void Execute social provider login flow to get userToken, encryptionKey, refreshToken and OAuthInfo object. ErrorCallback will be triggered when parameters are null or invalid. |
performLogout: ( provider: SocialProvider, successCallback: LoginSuccessCallback, errorCallback: ErrorCallback) ) => void Clean login data, includes provider’s data |
setBiometricsPin: ( userToken: string, encryptionKey: string, successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void Setup BiometricsForPin and trigger the SuccessCallback with SuccessResult after finishing the operation successfully. ErrorCallback will be triggered when parameters are null or invalid. |
setDismissOnCallbackMap: (map: Map<ErrorCode, boolean>) => void The SDK UI can be dismissed if there’s an error or warning during execute() and setBiometricsPin(). App can specify ErrorCode as true in the map to dismiss. |
moveTaskToFront: () => void Bring the SDK UI to foreground. After calling moveRnTaskToFront() and finishing the flow on React Native UI, e.g. forgot PIN flow, apps can back to SDK UI by calling moveTaskToFront() and continue the SDK task. |
moveRnTaskToFront: () => void Bring the React Native Activity / ViewController to front. In some cases, apps may need to go back to React Native UI during execute() or setBiometricsPin, e.g., receive an error, warning or event like forgotPin. |
setTextConfigsMap: (map: Map<TextsKey, TextConfig[]>) => void Define strings with specific configurations for special text customization. All keys are listed in A Index Table. |
setIconTextConfigsMap: ( map: Map<IconTextsKey, Array<IconTextConfig>> ) => void Define icon and string sets with specific configurations for icon text list item customization. All keys are listed in B Index Table. |
setTextConfigMap: (map: Map<TextKey, TextConfig>) => void Define strings with specific configurations for general string customization. It will replace values. All keys are listed in C Index Table. |
setImageMap: (map: Map<ImageKey, ImageSourcePropType>) => void Define image resource for image customization. All keys are listed in D Index Table. |
setDateFormat: (format: DateFormat) => void Set display date format, e.g. the answer of a security question in which inputType is datePicker. All supported formats are listed in DateFormat. The default format is “YYYY-MM-DD”. |
setDebugging: (debugging: boolean) => void Android only. true: default value, check customization map value and print warn level log. false: skip checking and turn off the log. |
setCustomUserAgent: (userAgent: string) => void Set custom user agent value. |
setErrorStringMap: (map: Map<ErrorCode, string) => void Define error message for customization. |
SdkVersion
interface SdkVersion| Properties |
|---|
rn: string Programmable Wallet React Native SDK version. |
native: string Programmable Wallet Native SDK version. |
Configuration
interface Configuration| Properties |
|---|
endpoint: string The endpoint SDK connects. |
appId: string Application ID, retrieved from Circle Developer Services Console. |
settingsManagement?: SettingsManagement Extra settings for SDK |
SettingsManagement
interface SettingsManagement| Properties |
|---|
enableBiometricsPin: boolean Enable biometrics to protect PIN code. |
SecurityQuestion
class SecurityQuestion| Properties |
|---|
title: string The question string. |
inputType: InputType The input type of the question. Support text input and timePicker. |
| Constructor |
|---|
constructor(title: string, inputType?: InputType) Initialize a SecurityQuestion, use InputType.text as default value. |
SocialProvider
To specify a social provider to operate on. SeeWalletSdk.performLogin(),
WalletSdk.performLogout().
JavaScript
InputType
Enumerates the types of security questions.JavaScript
LoginResult
Interface LoginResult| Properties |
|---|
userToken?: string User token |
encryptionKey?: string Encryption key |
refreshToken?: string Refresh token |
oauthInfo?: OauthInfo OauthInfo for social login |
OauthInfo
Interface OauthInfo| Properties |
|---|
provider?: string Provider |
scope?: string[] Scope |
socialUserUUID?: string Social user UUID |
socialUserInfo?: SocialUserInfo SocialUserInfo for Social login for social login |
SocialUserInfo
Interface SocialUserInfo| Properties |
|---|
name?: string Name |
email?: string |
phone?: string Phone |
SuccessResult
interface SuccessResult| Properties |
|---|
result: ExecuteResult Execute result. |
warning?: ExecuteWarning Execute warning. |
Error
interface Error| Properties |
|---|
code: string Error code. |
message: string Error message. |
LoginSuccessCallback
type SuccessCallback| Type declaration |
|---|
(result: LoginResult) => void Callback when the operation is executed successfully. |
SuccessCallback
type SuccessCallback| Type declaration |
|---|
(result: SuccessResult) => void Callback when the operation is executed successfully. |
ErrorCallback
type ErrorCallback| Type declaration |
|---|
(error: Error) => void The callback is triggered when a failure occurs in operation or is canceled by the user. |
ExecuteResult
interface ExecuteResult| Properties |
|---|
resultType: ExecuteResultType The type of the operation that the challenge represents. |
status: ExecuteResultStatus The status of the execution. |
data?: ExecuteResultData The data of the execution. |
ExecuteResultData
interface ExecuteResultData| Properties |
|---|
signature?: string The signature for SIGN_MESSAGE and SIGN_TYPEDDATA. |
ExecuteResultType
Enumerates the types of challenges supportedJavaScript
ExecuteResultStatus
Enumerates the possible statuses for a challengeJavaScript
EventListener
type EventListener| Type declaration |
|---|
(event: ExecuteEvent) => void Event listener for receiving ExecuteEvent. Deprecated. |
CIRCLE_PW_ON_EVENT
Constant event name for use with Expo’sNativeModule.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.| Properties |
|---|
name: ExecuteEvent The specific event type that was triggered. This value corresponds to one of the defined values in the ExecuteEvent enum. |
ExecuteEvent
Enumerates the possible eventJavaScript
ErrorCode
Enumerates the types of error codeJavaScript
TextConfig
Data-only class for text customization.class TextConfig
| Properties |
|---|
text?: string Text to display |
gradientColors?: string[] Array of Gradient text color. Only used by TextsKey.enterPinCodeHeadline, TextsKey.securityIntroHeadline, TextsKey.newPinCodeHeadline |
textColor?: string Text color |
font?: string Font |
| Constructor |
|---|
constructor( text?: string, gradientColorsOrTextColor: string[] | string, font?: string ) |
TextConfig
Data-only class for icon text list item customization.class IconTextConfig
| Properties |
|---|
image:ImageSourcePropType The image source for customization. |
textConfig: TextConfig Text config for text customization. |
| Constructor |
|---|
constructor(image: ImageSourcePropType, textConfig: TextConfig) |
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