Install Fordefi's React Native SDK

• A React Native project using React Native 0.81 or later with the New Architecture enabled.
• Node.js 20.19.4, or later and npm.
• JDK 17 (required by React Native 0.73+ and by the Fordefi Android modules).
• Your Android project must use Kotlin 2.x — the SDK modules resolve kotlinVersion from your root build.gradle.
• npm read access (via an npm access token or organization invitation) provided by Fordefi support.
• Platform minimums:
  • Android 7.0 (API level 24) or later;
  • iOS 13 or later, or your React Native version's minimum, if higher.

Use either of the following:

• An npm access token configured in your user level ~/.npmrc (recommended, so credentials are never committed to source control):

  //registry.npmjs.org/:_authToken=${FORDEFI_NPM_TOKEN}

• npm login using an npm account that has been granted access to the package.

From the root of your React Native project, run:

npm i @fordefi/wallet-sdk-react-native

If you intend to use Cloud backup, you must also install:

npm i @fordefi/backup-provider-react-native

The SDK ships as an Android library module that resolves its build versions from your project. Add these to the root android/build.gradle:

buildscript {
    ext {
        minSdkVersion = 24          // required floor — declared by the SDK itself
        compileSdkVersion = 36
        targetSdkVersion = 36
        buildToolsVersion = "36.0.0"
        kotlinVersion = "2.2.20"
    }
}

In android/app/build.gradle, set the Java toolchain to 17 and resolve the native library conflict:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = '17' }

    packagingOptions {
        pickFirst '**/libc++_shared.so'
        pickFirst '**/libfbjni.so'
    }
}

In android/gradle.properties, enable the New Architecture and restrict the ABI list:

newArchEnabled=true
reactNativeArchitectures=armeabi-v7a,arm64-v8a,x86_64

Finally, in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

<application android:allowBackup="false" ...>

The SDK declares no permissions of its own, so your app must declare INTERNET — without it, failures surface as network or auth errors. Setting allowBackup="false" is strongly recommended: end-user key material lives in secure device storage and should not be captured in device backups.

You do not need to register anything in MainApplication or MainActivity — autolinking handles it. You also do not need R8/ProGuard keep rules for the SDK; it ships its own consumer ProGuard rules.

Install the pods:

cd ios && pod install && cd ..

Requirements:

• Deployment target iOS 13.0 or later, or your React Native version's minimum, if higher.
• New Architecture enabled (RCTNewArchEnabled set to true in Info.plist; unconditional on React Native 0.82+).

No changes to AppDelegate are needed — the native module is registered by autolinking.

Skip this step unless you installed @fordefi/backup-provider-react-native. These requirements come from the cloud provider SDK, not the wallet SDK.

In android/app/build.gradle:

dependencies {
    implementation 'com.google.android.gms:play-services-auth:20.7.0'
    implementation('com.google.api-client:google-api-client-android:2.2.0') {
        exclude group: 'org.apache.httpcomponents'
        exclude module: 'guava-jdk5'
    }
    implementation('com.google.apis:google-api-services-drive:v3-rev20230822-2.0.0') {
        exclude group: 'org.apache.httpcomponents'
        exclude module: 'guava-jdk5'
    }
    implementation('com.google.http-client:google-http-client-gson:1.43.3') {
        exclude group: 'org.apache.httpcomponents', module: 'httpclient'
        exclude group: 'org.apache.httpcomponents', module: 'httpcore'
    }
}

The exclusions are mandatory — without them the build fails on duplicate classes. The dependencies themselves are required by the backup SDK's Google Drive integration but are not bundled with it; omitting them fails at backup time with NoClassDefFoundError, not at build time.

These Google libraries also require extra packaging rules, so extend the packagingOptions block from Step 3:

packagingOptions {
    pickFirst '**/libc++_shared.so'
    pickFirst '**/libfbjni.so'
    exclude 'META-INF/DEPENDENCIES'
    exclude 'META-INF/LICENSE'
    exclude 'META-INF/LICENSE.txt'
    exclude 'META-INF/NOTICE'
    exclude 'META-INF/NOTICE.txt'
    exclude 'META-INF/ASL2.0'
}

Set the launch mode on your main activity so the Google sign-in redirect returns to the running activity:

<activity android:name=".MainActivity" android:launchMode="singleTask" ... />

In the Google Cloud console: enable the Drive API, then create an Android OAuth client with your package name and the SHA-1 fingerprint of every signing key you use.

Install the CocoaPods plugin that allows per-pod build types (it is required because these two pods must be dynamic frameworks while the rest of the project stays static — stock CocoaPods cannot express per-pod build types):

sudo gem install cocoapods-user-defined-build-types

Then in ios/Podfile:

plugin 'cocoapods-user-defined-build-types'

enable_user_defined_build_types!

target 'YourApp' do
  pod 'GoogleSignIn', '7.0.0', :build_type => :dynamic_framework
  pod 'GoogleAPIClientForREST/Drive', '3.1.0', :build_type => :dynamic_framework
  # ...
end

Rerun pod install --repo-update. If the installation fails, remove ios/Pods and node_modules and try again.

Create an iOS OAuth client in the Google Cloud console, then register its reversed client ID as a URL scheme in ios/YourApp/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key><string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array><string>com.googleusercontent.apps.YOUR-IOS-CLIENT-ID</string></array>
  </dict>
</array>

Pass the same client ID to initBackupProvider as googleDriveClientID — the native URL scheme and the JS API must agree on this value.

This option is relevant for iOS only.

Enable the iCloud capability (key-value storage) for your target in Xcode, regenerate the provisioning profile, and confirm your entitlements file contains:

<key>com.apple.developer.icloud-container-identifiers</key><array/>
<key>com.apple.developer.icloud-services</key><array/>
<key>com.apple.developer.ubiquity-kvstore-identifier</key>
<string>$(TeamIdentifierPrefix)$(CFBundleIdentifier)</string>

See Cloud backup for the runtime flow.

Confirm the package resolved from the npm registry:

npm view @fordefi/wallet-sdk-react-native dist.tarball

(or check the resolved URL for the package in your lockfile).

Then run a native build — this is the real success criterion, since it exercises Steps 3–5:

npx react-native run-android
npx react-native run-ios

Continue to Initialization to set up the SDK in your app.