> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native SDK

> Set up the client-side React Native SDK for user-controlled wallets in your mobile application.

<Note>
  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)](/wallets/user-controlled/react-native-sdk-v1).
</Note>

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](/sdks/user-controlled/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.

<Info>
  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.
</Info>

To learn more, see [How it works](/sdks/user-controlled/overview#how-it-works).

## Installation and Setup

Follow the
[installation guide](https://github.com/circlefin/w3s-react-native-sdk) 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.

<Note>
  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.
</Note>

### Prerequisites

1. Follow the instructions to obtain IDs from social providers:
   1. **Google**
      1. Visit the [Firebase console](https://console.firebase.google.com/) to
         create a Firebase project. For detailed steps, see
         [View instructions to create a Firebase project](https://firebase.google.com/docs/android/setup#create-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](https://firebase.google.com/docs/android/setup#register-app).
      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](https://developers.facebook.com/)
         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](https://developer.apple.com/help/account/identifiers/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](https://console.circle.com/wallets/user/configurator/authentication-methods/social-logins)
   with the social provider IDs.

### iOS

<Note>
  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.
</Note>

<Tabs>
  <Tab title="Expo">
    #### Step 1: Configure plugins in app.json

    Add the following configuration to your `app.json` or `app.config.js` file.

    <Note>
      This assumes you have already configured the basic SDK plugins
      (`podfile-modifier`, `withCopyFiles`) during the [Installation and
      Setup](/sdks/user-controlled/react-native-sdk#installation-and-setup) section.
    </Note>

    Complete plugins configuration example:

    ```json theme={null}
    {
      "expo": {
        "plugins": [
          "@circle-fin/w3s-pw-react-native-sdk/plugins/podfile-modifier",
          [
            "@circle-fin/w3s-pw-react-native-sdk/plugins/withCopyFiles",
            {
              "sourceDir": "prebuild-sync-src",
              "targetDir": ".",
              "overwrite": true
            }
          ],
          "@circle-fin/w3s-pw-react-native-sdk/plugins/apple-signin-entitlements",
          [
            "@circle-fin/w3s-pw-react-native-sdk/plugins/infoplist-config",
            {
              "facebookAppId": "YOUR_FACEBOOK_APP_ID",
              "facebookClientToken": "YOUR_FACEBOOK_CLIENT_TOKEN",
              "facebookDisplayName": "YOUR_FACEBOOK_DISPLAY_NAME",
              "googleClientId": "YOUR_GOOGLE_IOS_CLIENT_ID"
            }
          ]
        ]
      }
    }
    ```

    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**

    ```swift theme={null}
    import FBSDKCoreKit
    ```

    Your imports section should now look like:

    ```swift theme={null}
    import Expo
    import React
    import ReactAppDependencyProvider
    import FBSDKCoreKit  // Add this line
    ```

    **2.2 Initialize Facebook SDK in didFinishLaunchingWithOptions**

    In the `application(_:didFinishLaunchingWithOptions:)` method, add Facebook SDK
    initialization **before** the existing code:

    ```swift theme={null}
    public override func application(
      _ application: UIApplication,
      didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
      // Add Facebook SDK initialization
      ApplicationDelegate.shared.application(
        application,
        didFinishLaunchingWithOptions: launchOptions
      )

      // ... rest of the existing code (don't modify)
      let delegate = ReactNativeDelegate()
      let factory = ExpoReactNativeFactory(delegate: delegate)
      // ... etc
    ```

    **2.3 Handle Facebook URL schemes**

    Add (or modify if it exists) the URL opening handler to process Facebook
    callbacks:

    ```swift theme={null}
    // Handle URL schemes for social login
    public override func application(
      _ app: UIApplication,
      open url: URL,
      options: [UIApplication.OpenURLOptionsKey: Any] = [:]
    ) -> Bool {
      // Handle Facebook SDK URL
      let facebookHandled = ApplicationDelegate.shared.application(
        app,
        open: url,
        sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String,
        annotation: options[UIApplication.OpenURLOptionsKey.annotation]
      )

      return facebookHandled
        || super.application(app, open: url, options: options)
        || RCTLinkingManager.application(app, open: url, options: options)
    }
    ```

    **2.4 (Optional) Handle Universal Links**

    If your app supports Universal Links, add this method:

    ```swift theme={null}
    // Handle Universal Links
    public override func application(
      _ application: UIApplication,
      continue userActivity: NSUserActivity,
      restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
      let result = RCTLinkingManager.application(application, continue: userActivity, restorationHandler: restorationHandler)
      return super.application(application, continue: userActivity, restorationHandler: restorationHandler) || result
    }
    ```

    #### 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:

    ```bash theme={null}
    mkdir -p prebuild-sync-src/ios/YourAppName
    cp ios/YourAppName/AppDelegate.swift prebuild-sync-src/ios/YourAppName/
    ```

    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.
  </Tab>

  <Tab title="React Native">
    #### Step 1: Enable Sign in with Apple capability

    Enable the **Sign in with Apple** capability in your Xcode project target. For
    detailed steps, see
    [Enable Sign in with Apple](https://help.apple.com/xcode/mac/current/#/dev50571b902).

    #### Step 2: Configure Info.plist

    Add the following keys to your `ios/YourApp/Info.plist` file:

    ```xml theme={null}
    <!-- Facebook configuration -->
    <key>FacebookAppID</key>
    <string>YOUR_FACEBOOK_APP_ID</string>
    <key>FacebookClientToken</key>
    <string>YOUR_FACEBOOK_CLIENT_TOKEN</string>
    <key>FacebookDisplayName</key>
    <string>YOUR_FACEBOOK_DISPLAY_NAME</string>

    <!-- Google configuration -->
    <key>GIDClientID</key>
    <string>YOUR_GOOGLE_IOS_CLIENT_ID</string>

    <!-- Face ID (required if biometric authentication is used) -->
    <key>NSFaceIDUsageDescription</key>
    <string>Enable Biometrics PIN</string>

    <!-- URL Schemes -->
    <key>CFBundleURLTypes</key>
    <array>
      <!-- Facebook URL Scheme -->
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>fbYOUR_FACEBOOK_APP_ID</string>
        </array>
      </dict>
      <!-- Google Reversed Client ID URL Scheme -->
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>YOUR_REVERSED_IOS_CLIENT_ID</string>
        </array>
      </dict>
    </array>
    ```

    Where:

    * `YOUR_FACEBOOK_APP_ID` is your Facebook app ID
    * `YOUR_FACEBOOK_CLIENT_TOKEN` is your Facebook client token
    * `YOUR_FACEBOOK_DISPLAY_NAME` is your Facebook app display name
    * `YOUR_GOOGLE_IOS_CLIENT_ID` is the value of the `CLIENT_ID` key from
      `GoogleService-Info.plist`
    * `YOUR_REVERSED_IOS_CLIENT_ID` is the value of the `REVERSED_CLIENT_ID` key
      from `GoogleService-Info.plist`

    #### Step 3: Modify AppDelegate

    Update your AppDelegate.m (or AppDelegate.mm) to initialize Facebook SDK and
    handle URL schemes.

    **3.1 Add required imports**

    ```objectivec theme={null}
    #import "AppDelegate.h"
    #import <FBSDKCoreKit/FBSDKCoreKit.h>  // Add this
    #import <React/RCTLinkingManager.h>    // Add this if not present
    ```

    **3.2 Initialize Facebook SDK in didFinishLaunchingWithOptions**

    In the `application:didFinishLaunchingWithOptions:` method, add Facebook SDK
    initialization at the beginning of the method:

    ```objectivec theme={null}
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
      // Add Facebook SDK initialization
      [[FBSDKApplicationDelegate sharedInstance] application:application
                               didFinishLaunchingWithOptions:launchOptions];

      // ... rest of your existing code (don't modify) ...

      return YES;
    }
    ```

    **3.3 Handle URL schemes**

    Add (or modify if it exists) the URL opening handler:

    ```objectivec theme={null}
    // Handle URL schemes
    - (BOOL)application:(UIApplication *)app
                openURL:(NSURL *)url
                options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
    {
      // Handle Facebook URL
      BOOL facebookHandled = [[FBSDKApplicationDelegate sharedInstance] application:app
                                                                            openURL:url
                                                                  sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                                                                         annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];

      return facebookHandled
          || [super application:app openURL:url options:options]
          || [RCTLinkingManager application:app openURL:url options:options];
    }
    ```

    **3.4 (Optional) Handle Universal Links**

    If your app supports Universal Links, add this method:

    ```objectivec theme={null}
    // Handle Universal Links
    - (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
     restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
    {
      return [RCTLinkingManager application:application
                       continueUserActivity:userActivity
                         restorationHandler:restorationHandler];
    }
    ```
  </Tab>
</Tabs>

### Android

<Note>
  **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`.
</Note>

#### 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`.

<CodeGroup>
  ```groovy Groovy (build.gradle) theme={null}
  android {
    defaultConfig {
      manifestPlaceholders = [appAuthRedirectScheme: 'YOUR_APPLE_SERVICE_ID']
    }
  }
  ```

  ```kotlin Kotlin (build.gradle.kts) theme={null}
  android {
    defaultConfig {
      manifestPlaceholders["appAuthRedirectScheme"] = "YOUR_APPLE_SERVICE_ID"
    }
  }
  ```
</CodeGroup>

#### Facebook

Add the following values to `android/app/src/main/res/values/strings.xml`:

```xml theme={null}
<!-- Facebook -->
<string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
<string name="fb_login_protocol_scheme">fbYOUR_FACEBOOK_APP_ID</string>
<string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>
```

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`:

```xml theme={null}
<!-- Google -->
<string name="google_web_client_id" translatable="false">YOUR_GOOGLE_WEB_CLIENT_ID</string>
```

Where `YOUR_GOOGLE_WEB_CLIENT_ID` is your Google sign-in client ID.

2. Place your `google-services.json` in the `android/app/` directory (or
   `prebuild-sync-src/android/app` for Expo projects).

3. Add
   [Google Services Gradle Plugin](https://developers.google.com/android/guides/google-services-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`):

<CodeGroup>
  ```groovy Groovy (build.gradle) theme={null}
  buildscript {
      dependencies {
          classpath "com.google.gms:google-services:4.4.4"
      }
  }
  ```

  ```kotlin Kotlin (build.gradle.kts) theme={null}
  buildscript {
      dependencies {
          classpath("com.google.gms:google-services:4.4.4")
      }
  }
  ```
</CodeGroup>

4. Add the following to your app-level Gradle file (`android/app/build.gradle`
   or `android/app/build.gradle.kts`):

<CodeGroup>
  ```groovy Groovy (build.gradle) theme={null}
  apply plugin: "com.google.gms.google-services"
  ```

  ```kotlin Kotlin (build.gradle.kts) theme={null}
  plugins {
      id("com.google.gms.google-services")
  }
  ```
</CodeGroup>

## SDK API references

### WalletSdk

implements IWallet

### IWalletSdk

interface IWalletSdk

| Properties                                 |
| ------------------------------------------ |
| `sdkVersion: SdkVersion` <br />SDK version |

| Methods                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init: (configuration: Configuration) => Promise<void>` <br />Configure the Circle endpoint for SDK to connect, reject Promise if the endpoint and appId's format are invalid.                                                                                                                                                                                                                                                                                 |
| `setSecurityQuestions: (securityQuestions: SecurityQuestion[]) => void` <br />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` <br />Register an EventListener for the app to handle events, e.g. forgot PIN. <br />**Deprecated.**                                                                                                                                                                                                                                                                                                          |
| `removeAllListeners: () => void` <br />Unregister all EventListener. <br />**Deprecated.**                                                                                                                                                                                                                                                                                                                                                                     |
| `execute: ( userToken: string, encryptionKey: string, challengeIds: string[], successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void` <br />Execute the operations by challengeId and trigger the SuccessCallback with SuccessResult after sending the request to Circle endpoint successfully. <br />ErrorCallback will be triggered when parameters are null or invalid.                                                                   |
| `executeWithKeyShare: ( userToken: string, encryptionKey: string, pinCodeDeviceShare: string, challengeIds: string[], successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void` <br />Execute the operations by challengeId and PIN code device share and trigger the SuccessCallback with SuccessResult after sending the request to Circle endpoint successfully. <br />ErrorCallback will be triggered when parameters are null or invalid. |
| `getDeviceId: () => string?` <br />Get device ID                                                                                                                                                                                                                                                                                                                                                                                                               |
| `performLogin: ( provider: SocialProvider, deviceToken: string, deviceEncryptionKey: string, successCallback: LoginSuccessCallback, errorCallback: ErrorCallback) ) => void` <br />Execute social provider login flow to get userToken, encryptionKey, refreshToken and OAuthInfo object. <br />ErrorCallback will be triggered when parameters are null or invalid.                                                                                           |
| `performLogout: ( provider: SocialProvider, successCallback: LoginSuccessCallback, errorCallback: ErrorCallback) ) => void` <br />Clean login data, includes provider's data                                                                                                                                                                                                                                                                                   |
| `setBiometricsPin: ( userToken: string, encryptionKey: string, successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void` <br />Setup BiometricsForPin and trigger the SuccessCallback with SuccessResult after finishing the operation successfully. <br />ErrorCallback will be triggered when parameters are null or invalid.                                                                                                                |
| `setDismissOnCallbackMap: (map: Map<ErrorCode, boolean>) => void` <br />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` <br />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` <br />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` <br />Define strings with specific configurations for special text customization. <br />All keys are listed in A Index Table.                                                                                                                                                                                                                                                                  |
| `setIconTextConfigsMap: ( map: Map<IconTextsKey, Array<IconTextConfig>> ) => void` <br />Define icon and string sets with specific configurations for icon text list item customization. <br />All keys are listed in B Index Table.                                                                                                                                                                                                                           |
| `setTextConfigMap: (map: Map<TextKey, TextConfig>) => void` <br />Define strings with specific configurations for general string customization. It will replace values. <br />All keys are listed in C Index Table.                                                                                                                                                                                                                                            |
| `setImageMap: (map: Map<ImageKey, ImageSourcePropType>) => void` <br />Define image resource for image customization. <br />All keys are listed in D Index Table.                                                                                                                                                                                                                                                                                              |
| `setDateFormat: (format: DateFormat) => void` <br />Set display date format, e.g. the answer of a security question in which inputType is datePicker. <br />All supported formats are listed in DateFormat. <br />The default format is “YYYY-MM-DD”.                                                                                                                                                                                                          |
| `setDebugging: (debugging: boolean) => void` <br />Android only. <br />true: default value, check customization map value and print warn level log. <br />false: skip checking and turn off the log.                                                                                                                                                                                                                                                           |
| `setCustomUserAgent: (userAgent: string) => void` <br />Set custom user agent value.                                                                                                                                                                                                                                                                                                                                                                           |
| `setErrorStringMap: (map: Map<ErrorCode, string) => void` <br />Define error message for customization.                                                                                                                                                                                                                                                                                                                                                        |

### SdkVersion

interface SdkVersion

| Properties                                                       |
| ---------------------------------------------------------------- |
| `rn: string` <br />Programmable Wallet React Native SDK version. |
| `native: string` <br />Programmable Wallet Native SDK version.   |

### Configuration

interface Configuration

| Properties                                                                              |
| --------------------------------------------------------------------------------------- |
| `endpoint: string` <br />The endpoint SDK connects.                                     |
| `appId: string` <br />Application ID, retrieved from Circle Developer Services Console. |
| `settingsManagement?: SettingsManagement` <br />Extra settings for SDK                  |

### SettingsManagement

interface SettingsManagement

| Properties                                                                  |
| --------------------------------------------------------------------------- |
| `enableBiometricsPin: boolean` <br />Enable biometrics to protect PIN code. |

### SecurityQuestion

class SecurityQuestion

| Properties                                                                                      |
| ----------------------------------------------------------------------------------------------- |
| `title: string` <br />The question string.                                                      |
| `inputType: InputType` <br />The input type of the question. Support text input and timePicker. |

| Constructor                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------- |
| `constructor(title: string, inputType?: InputType)` <br />Initialize a SecurityQuestion, use InputType.text as default value. |

### SocialProvider

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

```javascript JavaScript theme={null}
enum InputType {
  Google = 'Google',
  Facebook = 'Facebook',
  Apple = 'Apple',
}
```

### InputType

Enumerates the types of security questions.

```Text JavaScript theme={null}
enum InputType {
  text = 'text',
  datePicker = 'datePicker',
}
```

### LoginResult

Interface LoginResult

| Properties                                               |
| -------------------------------------------------------- |
| `userToken?: string` <br />User token                    |
| `encryptionKey?: string` <br />Encryption key            |
| `refreshToken?: string` <br />Refresh token              |
| `oauthInfo?: OauthInfo` <br />OauthInfo for social login |

### OauthInfo

Interface OauthInfo

| Properties                                                                               |
| ---------------------------------------------------------------------------------------- |
| `provider?: string` <br />Provider                                                       |
| `scope?: string[]` <br />Scope                                                           |
| `socialUserUUID?: string` <br />Social user UUID                                         |
| `socialUserInfo?: SocialUserInfo` <br />SocialUserInfo for Social login for social login |

### SocialUserInfo

Interface SocialUserInfo

| Properties                   |
| ---------------------------- |
| `name?: string` <br />Name   |
| `email?: string` <br />Email |
| `phone?: string` <br />Phone |

### SuccessResult

interface SuccessResult

| Properties                                        |
| ------------------------------------------------- |
| `result: ExecuteResult` <br />Execute result.     |
| `warning?: ExecuteWarning` <br />Execute warning. |

### Error

interface Error

| Properties                             |
| -------------------------------------- |
| `code: string` <br />Error code.       |
| `message: string` <br />Error message. |

### LoginSuccessCallback

type SuccessCallback

| Type declaration                                                                            |
| ------------------------------------------------------------------------------------------- |
| `(result: LoginResult) => void` <br />Callback when the operation is executed successfully. |

### SuccessCallback

type SuccessCallback

| Type declaration                                                                              |
| --------------------------------------------------------------------------------------------- |
| `(result: SuccessResult) => void` <br />Callback when the operation is executed successfully. |

### ErrorCallback

type ErrorCallback

| Type declaration                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------- |
| `(error: Error) => void` <br />The callback is triggered when a failure occurs in operation or is canceled by the user. |

### ExecuteResult

interface ExecuteResult

| Properties                                                                                     |
| ---------------------------------------------------------------------------------------------- |
| `resultType: ExecuteResultType` <br />The type of the operation that the challenge represents. |
| `status: ExecuteResultStatus` <br />The status of the execution.                               |
| `data?: ExecuteResultData` <br />The data of the execution.                                    |

### ExecuteResultData

interface ExecuteResultData

| Properties                                                                      |
| ------------------------------------------------------------------------------- |
| `signature?: string` <br />The signature for SIGN\_MESSAGE and SIGN\_TYPEDDATA. |

### ExecuteResultType

Enumerates the types of challenges supported

```coffeescript JavaScript theme={null}
enum ExecuteResultType {
  UNKNOWN = 'UNKNOWN',
  SET_PIN = 'SET_PIN',
  RESTORE_PIN = 'RESTORE_PIN',
  SET_SECURITY_QUESTIONS = 'SET_SECURITY_QUESTIONS',
  CREATE_WALLET = 'CREATE_WALLET',
  CREATE_TRANSACTION = 'CREATE_TRANSACTION',
  ACCELERATE_TRANSACTION = 'ACCELERATE_TRANSACTION',
  CANCEL_TRANSACTION = 'CANCEL_TRANSACTION',
  CONTRACT_EXECUTION = 'CONTRACT_EXECUTION',
  SIGN_MESSAGE = 'SIGN_MESSAGE',
  SIGN_TYPEDDATA = 'SIGN_TYPEDDATA',
  SET_BIOMETRICS_PIN = 'SET_BIOMETRICS_PIN',
}
```

### ExecuteResultStatus

Enumerates the possible statuses for a challenge

```coffeescript JavaScript theme={null}
enum ExecuteResultStatus {
  UNKNOWN = 'UNKNOWN',
  PENDING = 'PENDING',
  IN_PROGRESS = 'IN_PROGRESS',
  COMPLETE = 'COMPLETE',
  FAILED = 'FAILED',
  EXPIRED = 'EXPIRED',
}
```

### EventListener

type EventListener

| Type declaration                                                                                       |
| ------------------------------------------------------------------------------------------------------ |
| `(event: ExecuteEvent) => void` <br />Event listener for receiving ExecuteEvent. <br />**Deprecated.** |

### 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.

```ts theme={null}
const CIRCLE_PW_ON_EVENT = "CirclePwOnEvent";
```

### CirclePwEventPayload

Interface for the payload received when a CIRCLE\_PW\_ON\_EVENT is triggered.

| Properties                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name: ExecuteEvent` <br />The specific event type that was triggered. This value corresponds to one of the defined values in the ExecuteEvent enum. |

### ExecuteEvent

Enumerates the possible event

```coffeescript JavaScript theme={null}
enum ExecuteEvent {
  forgotPin = 'forgotPin',
}
```

### ErrorCode

Enumerates the types of error code

```coffeescript JavaScript theme={null}
enum ErrorCode {
  unknown = '-1',
  success = '0',
  apiParameterMissing = '1',
  apiParameterInvalid = '2',
  forbidden = '3',
  unauthorized = '4',
  retry = '9',
  customerSuspended = '10',
  pending = '11',
  invalidSession = '12',
  invalidPartnerId = '13',
  invalidMessage = '14',
  invalidPhone = '15',
  walletIdNotFound = '156001',
  tokenIdNotFound = '156002',
  transactionIdNotFound = '156003',
  walletSetIdNotFound = '156004',
  notEnoughFounds = '155201',
  notEnoughBalance = '155202',
  exceedWithdrawLimit = '155203',
  minimumFundsRequired = '155204',
  invalidTransactionFee = '155205',
  rejectedOnAmlScreening = '155206',
  tagRequired = '155207',
  gasLimitTooLow = '155208',
  transactionDataNotEncodedProperly = '155209',
  fullNodeReturnedError = '155210',
  walletSetupRequired = '155211',
  lowerThenMinimumAccountBalance = '155212',
  rejectedByBlockchain = '155213',
  droppedAsPartOfReorg = '155214',
  operationNotSupport = '155215',
  amountBelowMinimum = '155216',
  wrongNftTokenIdNumber = '155217',
  invalidDestinationAddress = '155218',
  tokenWalletChainMismatch = '155219',
  wrongAmountsNumber = '155220',
  userAlreadyExisted = '155101',
  userNotFound = '155102',
  userTokenNotFound = '155103',
  userTokenExpired = '155104',
  invalidUserToken = '155105',
  userWasInitialized = '155106',
  userHasSetPin = '155107',
  userHasSetSecurityQuestion = '155108',
  userWasDisabled = '155109',
  userDoesNotSetPinYet = '155110',
  userDoesNotSetSecurityQuestionYet = '155111',
  incorrectUserPin = '155112',
  incorrectDeviceId = '155113',
  incorrectAppId = '155114',
  incorrectSecurityAnswers = '155115',
  invalidChallengeId = '155116',
  invalidApproveContent = '155117',
  invalidEncryptionKey = '155118',
  userPinLocked = '155119',
  securityAnswersLocked = '155120',
  walletIsFrozen = '155501',
  maxWalletLimitReached = '155502',
  walletSetIdMutuallyExclusive = '155503',
  metadataUnmatched = '155504',
  userCanceled = '155701',
  launchUiFailed = '155702',
  pinCodeNotMatched = '155703',
  insecurePinCode = '155704',
  hintsMatchAnswers = '155705',
  networkError = '155706',
  biometricsSettingNotEnabled = '155708',
  deviceNotSupportBiometrics = '155709',
  biometricsKeyPermanentlyInvalidated = '155710',
  biometricsUserSkip = '155711',
  biometricsUserDisableForPin = '155712',
  biometricsUserLockout = '155713',
  biometricsUserLockoutPermanent = '155714',
  biometricsUserNotAllowPermission = '155715',
  biometricsInternalError = '155716',
  userSecretMissing = '155717',
  invalidUserTokenFormat = '155718',
  userTokenMismatch = '155719',
  socialLoginFailed = '155720',
  loginInfoMissing = '155721',
}
```

### TextConfig

Data-only class for text customization.\
class TextConfig

| Properties                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text?: string` <br />Text to display                                                                                                                                                     |
| `gradientColors?: string[]` <br />Array of Gradient text color. Only used by <br />TextsKey.enterPinCodeHeadline, <br />TextsKey.securityIntroHeadline, <br />TextsKey.newPinCodeHeadline |
| `textColor?: string` <br />Text color                                                                                                                                                     |
| `font?: string` <br />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`](https://reactnative.dev/docs/image#source) <br />The image source for customization. |
| `textConfig: TextConfig` <br />Text config for text customization.                                                 |

| Constructor                                                       |
| :---------------------------------------------------------------- |
| `constructor(image: ImageSourcePropType, textConfig: TextConfig)` |

### TextsKey

Enum for setTextConfigsMap().\
See [A Index Table](/sdks/user-controlled/react-native-sdk-ui-customization-api#a-index-table--textskey).

### IconTextsKey

Enum for setIconTextConfigsMap().\
See [B Index Table](/sdks/user-controlled/react-native-sdk-ui-customization-api#b-index-table---icontextskey).

### TextKey

Enum for setTextConfigMap().\
See [C Index Table](/sdks/user-controlled/react-native-sdk-ui-customization-api#c-index-table---resourcekey).

### ImageKey

Enum for setImageMap().\
See [D Index Table](/sdks/user-controlled/react-native-sdk-ui-customization-api#d-index-table).

### DateFormat

Enum for setDateFormat().

```coffeescript JavaScript theme={null}
enum DateFormat {
  YYYYMMDD_HYPHEN = 'yyyy-MM-dd',
  DDMMYYYY_SLASH = 'dd/MM/yyyy',
  MMDDYYYY_SLASH = 'MM/dd/yyyy',
}
```

## SampleCode

```coffeescript JavaScript theme={null}
import * as React from 'react';
import { WalletSdk } from '@circle-fin/w3s-pw-react-native-sdk';

export default function App() {
    const [endpoint, setEndpoint] = React.useState(
    'https://api.circle.com/v1/w3s/'
  );
    const [appId, setAppId] = React.useState('');
    const [enableBiometricsPin, setEnableBiometricsPin] = React.useState(false);
    const [userToken, setUserToken] = React.useState('');
    const [encryptionKey, setEncryptionKey] = React.useState('');
    const [challengeId, setChallengeId] = React.useState('');

    React.useEffect(() => {
        // Regester EventListener
        WalletSdk.addListener((event: any) => {
    if(event == ExecuteEvent.forgotPin){
              WalletSdk.moveRnTaskToFront();
              // forgot PIN flow in React Native UI
           }
        });
  _initSdk();
        _setSecurityQuestions();
        _setDismissOnCallbackMap();
        _setTextConfigsMap();
        _setIconTextConfigsMap();
        _setTextConfigMap();
        _setErrorStringMap();
        _setImageMap();
        _setDateFormat();
        _setDebugging();
        return () => {
           // Removes listeners once unmounted
           WalletSdk.removeAllListeners();
        };
   }, []);
   ...
   return (
       <View>
        <TextInput
          accessibilityLabel={'endpointInput'}
          onChangeText={setEndpoint}
          value={endpoint}
        />
        <TextInput
          accessibilityLabel={'appIdInput'}
          onChangeText={setAppId}
          value={appId}
        />
        <TextInput
          accessibilityLabel={'userTokenInput'}
          onChangeText={setUserToken}
          value={userToken}
        />
        <TextInput
          accessibilityLabel={'encryptionKeyInput'}
          onChangeText={setEncryptionKey}
          value={encryptionKey}
        />
        <TextInput
          onChangeText={setChallengeId}
          value={challengeId}
        />
        <TouchableOpacity
          accessibilityLabel={'executeSdkButton'}
          onPress={() => {
            _executeSdk();
          }}
<Note>

</Note>
          <Text>Execute</Text>
        </TouchableOpacity>
        <TouchableOpacity
          accessibilityLabel={'setBiometricsPinButton'}
          onPress={() => {
            _setBiometricsPin();
          }}
<Note>

</Note>
          <Text>Set Biometrics Pin</Text>
        </TouchableOpacity>
      </View>
   )
}
```

```coffeescript JavaScript theme={null}
 ...
   const _initSdk = async () => {
     try {
            // Set endpoint, app ID and extra settings
   await WalletSdk.init({
     endpoint,
     appId,
     settingsManagement: { enableBiometricsPin: enableBiometricsPin }
    });
     } catch (e: any) {
     toast(e.message);
     return;
     }
   };

  const _setSecurityQuestions = () => {
    WalletSdk.setSecurityQuestions([
      new SecurityQuestion('What was your childhood nickname?', InputType.text),
      new SecurityQuestion('When is your favorite date?', InputType.datePicker),
      new SecurityQuestion('What is the name of your first pet?'),
      new SecurityQuestion('What is your favorite country?'),
    ]);
  };

  const _setDismissOnCallbackMap = () => {
      const map = new Map();
      map.set(ErrorCode.userCanceled, true);
      map.set(ErrorCode.networkError, true);
      WalletSdk.setDismissOnCallbackMap(map);
  };

  const _setTextConfigsMap = () => {
      let gradientColors = ['#05184b', '#21bad5'] as Array<string>;
      const map = new Map();
      map.set(TextsKey.newPinCodeHeadline, [
        new TextConfig('ENTER your new ', '#a6183f'),
        new TextConfig(
          'W3s PIN',
          undefined,
          gradientColors,
          'Roboto'
        ),
      ]);
      map.set(TextsKey.securityIntroLink, [
        new TextConfig('==Learn more=='),
        new TextConfig('https://www.circle.com/en/legal/privacy-policy'),
      ]);
      WalletSdk.setTextConfigsMap(map);
  };

 const _setImageMap = () => {
     const imageMap = new Map();
     imageMap.set(ImageKey.naviBack, require('../../assets/image/ic_back.png'));
     imageMap.set(ImageKey.naviClose, require('../../assets/image/ic_close.png'));
     imageMap.set(
       ImageKey.securityIntroMain,
       require('../../assets/image/grab_confirm_main_icon.png')
     );
     imageMap.set(ImageKey.selectCheckMark, {
       uri: 'https://drive.google.com/uc?id=1UTX1tFnECuj1k3U1bggH0g5YvH_Ens5M',
     });
     imageMap.set(ImageKey.dropdownArrow, {
       uri: 'https://drive.google.com/uc?id=1PR3yYpk4AmsCAlUM8nw6C3y-RAXNjGMv',
     });
     imageMap.set(ImageKey.errorInfo, {
       uri: 'https://drive.google.com/uc?id=1UJjinISU6ZHO0fAoKaZofBMgItaAn9kS',
     });
     imageMap.set(ImageKey.securityConfirmMain, {
       uri: 'https://drive.google.com/uc?id=16OkP3VzEjLICOifNKRQi3FMJntV9F-n-',
     });
     WalletSdk.setImageMap(imageMap);
 };
  const _setIconTextConfigsMap = () => {
      const map = new Map<IconTextsKey, Array<IconTextConfig>>();
      map.set(IconTextsKey.securityConfirmationItems, [
        new IconTextConfig(
          require('../../assets/image/ic_intro_item0_icon.png'),
          new TextConfig('This is the only way to recover my account access. '       )
      ),
        new IconTextConfig(
          require('../../assets/image/ic_intro_item1_icon.png'),
          new TextConfig(
            'Circle won't store my answers so it's my responsibility to remember them.'
          )
      ),
       new IconTextConfig(
         require('../../assets/image/ic_intro_item2_icon.png'),
         new TextConfig(
           'I will lose access to my wallet and my digital assets if I forget my answers. '
         )
       ),
     ]);
     WalletSdk.setIconTextConfigsMap(map);
 };
 const _setTextConfigMap = () => {};
 const _setErrorStringMap = () => {};
 const _setDateFormat = () => {};
 const _setDebugging = () => {};

 // execute
 const _executeSdk = async () => {
     try {
         let { result } = await WalletSdk.execute(userToken, encryptionKey, [
           challengeId,
         ]);
         console.log(`${result.resultType}, ${result.status}, ${result.data?.signature}`);
     } catch (e: any) {
         console.log(e.message);
     }
  };
  // setBiometricsPin
 const _setBiometricsPin = async () => {
    try {
      let { result } = await WalletSdk.setBiometricsPin(
        userToken,
        encryptionKey
      );
      console.log(`${result.resultType}, ${result.status}`);
    } catch (e: any) {
      console.log(e.message);
    }
  };
```