React Native SDK
Set up the client-side React Native SDK for user-controlled wallets in your mobile application.
The Circle React Native SDK enables your mobile application to provide user-controlled programmable wallets. By integrating this SDK, your users can securely input sensitive data like PINs or security answers. The SDK encrypts the request body using a secret key, protecting your users' information.
📘 The Web and Mobile SDKs preserve the user keyshare with the individual, giving them complete control. You must use the SDKs with the user-controlled wallet product. Additionally, the Web and Mobile SDKs support only the user-controlled wallet product.
At Circle, we understand the importance of end-to-end security for your application and the need to create a tailored and seamless user experience for your end-users. Hence, Circle’s SDK also exposes functionality for you to customize the description and layout of UI components we serve, including:
-
UI Title and Subtitle Customization: Modify the title and subtitle to reflect your brand identity or provide specific instructions.
-
Custom PIN Code Input Layout: Adjust the layout and styling of the PIN code input field to align with your application's design guidelines.
-
Question List Configuration: Set the list of security questions displayed in the User Wallet UI, allowing users to choose from a predefined set.
-
SDK Initialization: Initialize the Web SDK by setting the endpoint server, ensuring seamless communication between your application and Circle’s services.
-
Predefined Error Messages: Customize the error messages displayed to users, providing a more personalized experience and guidance.
-
ChallengeID Acceptance and Operation Retrieval: Easily accept the
challengeId
and retrieve any relevant operations within the SDK.
💡Tip: See the React Native SDK UI Customization API article to customize the SDK.
Install the SDK
You can set up the React Native SDK by downloading it from GitHub.
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’s keyshare, always stays with them and is not exposed to your servers.
To learn more, see SDK Architecture for User-Controlled Wallets.
SDK API references
WalletSdk
implement IWallet
IWalletSdk
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. |
removeAllListeners: () => void Unregister all EventListener. |
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? |
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 Web3 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. |
InputType
Enumerates the types of security questions.
enum InputType {
text = 'text',
datePicker = 'datePicker',
}
SuccessResult
interface SuccessResult
Properties |
---|
result: ExecuteResult Execute result. |
warning?: ExecuteWarning Execute warning. |
Error
interface Error
Properties |
---|
code: string Error code. |
message: ExecstringuteWarning Error message. |
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 supported
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
enum ExecuteResultStatus {
UNKNOWN = 'UNKNOWN',
PENDING = 'PENDING',
IN_PROGRESS = 'IN_PROGRESS',
COMPLETE = 'COMPLETE',
FAILED = 'FAILED',
EXPIRED = 'EXPIRED',
}
EventListener
type EventListener
Type declaration |
---|
(event: ExecuteEvent) => void Event listener for receiving ExecuteEvent. |
ExecuteEvent
Enumerates the possible event
enum ExecuteEvent {
forgotPin = 'forgotPin',
}
ErrorCode
Enumerates the types of error code
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',
}
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](https://reactnative.dev/docs/image#source) 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.
DateFormet
Enum for setDateFormat().
enum DateFormat {
YYYYMMDD_HYPHEN = 'yyyy-MM-dd',
DDMMYYYY_SLASH = 'dd/MM/yyyy',
MMDDYYYY_SLASH = 'MM/dd/yyyy',
}
SampleCode
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();
}}
>
<Text>Execute</Text>
</TouchableOpacity>
<TouchableOpacity
accessibilityLabel={'setBiometricsPinButton'}
onPress={() => {
_setBiometricsPin();
}}
>
<Text>Set Biometrics Pin</Text>
</TouchableOpacity>
</View>
)
}
...
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);
}
};
Updated 20 days ago