ComplyCube React Native SDK

The official React Native SDK for integrating ComplyCube's Identity Verification UI into your mobile app.

ComplyCube enables you to automate your AML/KYC workflows effortlessly.

Documentation and minimum requirements can be found at https://docs.complycube.com/documentation/guides/mobile-sdk-guide.

Installation

Install the SDK

Install the React Native library by running:

npm install --save @complycube/react-native

CocoaPods

The minimum supported iOS version is 14.0.

1. Before using the ComplyCube SDK, install the CocoaPods plugin by running the following command in your terminal:

   sudo gem install cocoapods

2. Open your ios/Podfile and add the following configuration:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :iOS, '14.0'
   
   target 'YourApp' do
       use_frameworks!
       use_modular_headers!
   
       # Other existing pod configurations
   
       post_install do |installer|
           installer.pods_project.targets.each do |target|
               target.build_configurations.each do |build_configuration|
                   build_configuration.build_settings['ENABLE_BITCODE'] = 'NO'
                   build_configuration.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
                   build_configuration.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '14.0'
                   build_configuration.build_settings['ARCHS'] = ['$(ARCHS_STANDARD)', 'x86_64']
                   build_configuration.build_settings['GENERATE_INFOPLIST_FILE'] = 'YES'
               end
           end
       end
   
       $static_frameworks = [
           'react-native-blurhash',
           'RNScreens',
           'RNScreen',
           'RNCMaskedView',
           'RNReactNativeHapticFeedback',
           'RNReanimated'
       ]
   
       pre_install do |installer|
           Pod::Installer::Xcode::TargetValidator.send(:define_method, :verify_no_static_framework_transitive_dependencies) {}
   
           installer.pod_targets.each do |target|
               if $static_frameworks.include?(target.name)
                   puts "Overriding the static_framework method for #{target.name}"
                   def target.build_type;
                       Pod::BuildType.static_library
                   end
               end
           end
       end
   end

3. Save the Podfile.

4. Run pod install in your ios directory to install the pods and apply the configurations.

Application Permissions

Our SDK uses the device camera and microphone for capture. You must add the following keys to your application's ios/Info.plist file.

1. NSCameraUsageDescription

   <key>NSCameraUsageDescription</key>
   <string>Used to capture facial biometrics and documents</string>

2. NSMicrophoneUsageDescription

   <key>NSMicrophoneUsageDescription</key>
   <string>Used to capture video biometrics</string>

Android

React Native autolinking pulls in this package's Gradle configuration, which already declares the correct, version-pinned native ComplyCube SDK (com.complycube:complycube-sdk) from Maven Central transitively. You do not need to add that dependency manually.

However, the mapping layer ships as a bundled AAR (complycube-mapping-android) inside this package rather than from Maven (this is temporary — see note below). Because of that, your app must add a flatDir repository pointing at the AAR so Gradle can resolve it. Where this goes depends on your project's repository configuration:

RN 0.71+ / projects using centralized dependencyResolutionManagement — add the flatDir to android/settings.gradle. (On RN 0.71+ the default repositoriesMode is FAIL_ON_PROJECT_REPOS, so a repo declared in android/build.gradle is rejected — it must live here.)

// android/settings.gradle
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        flatDir {
            dirs "$rootDir/../node_modules/@complycube/react-native/android/libs"
        }
    }
}

Older projects that declare repositories in allprojects — add it to android/build.gradle:

// android/build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        flatDir {
            dirs "$rootDir/../node_modules/@complycube/react-native/android/libs"
        }
    }
}

Note on transitive dependencies: a flatDir AAR carries no POM, so its transitive dependencies are not resolved automatically. This package declares the dependencies the mapping AAR needs (com.complycube:complycube-sdk and kotlinx-serialization-json) on your behalf, so a standard integration works today. Publishing this AAR to Maven (which would let autolinking resolve it normally and drop the flatDir requirement) is tracked as a follow-up.

Getting Started

Visit our step-by-step guide to quickly get started with our SDK.

Appearance customization

Use lookAndFeel for cross-platform appearance customization.

The designTokens option is currently Android-only: the iOS native framework does not yet expose design tokens, so the key is ignored on iOS (the bridge logs a warning when it is supplied). Until iOS gains support, tokens passed via designTokens will apply on Android and no-op on iOS.

Compatibility

We continuously validate this SDK against a moving React Native matrix:

• Latest stable version
• Two previous stable minors
• Two prerelease tags (future)

Both old and new architectures are covered using legacy interop. Details and local commands are in COMPATIBILITY.md.

Expo (prebuild)

This package ships an Expo config plugin to configure iOS/Android permissions and Podfile settings required by the SDK.

Add the plugin to your app config:

{
  "expo": {
    "plugins": [
      [
        "@complycube/react-native",
        {
          "cameraPermission": "Used to capture facial biometrics and documents",
          "microphonePermission": "Used to capture video biometrics",
          "enableNfc": false
        }
      ]
    ]
  }
}

Then run:

npx expo prebuild --clean

Telemetry Events

You can subscribe to telemetry/custom events emitted by the SDK:

import { subscribe } from '@complycube/react-native';

const unsubscribe = subscribe((message) => {
  // message can be a string or a JSON string depending on platform
  console.log('ComplyCube event:', message);
});

// later, when you no longer need events
unsubscribe();

More Documentation

Our Mobile SDK integration documentation and code examples can be found at https://docs.complycube.com/documentation/guides/mobile-sdk-guide.

Our sample React Native Mobile SDK project can be found at https://github.com/complycube/complycube-react-native-sdk.

Further information on ComplyCube can be found at https://www.complycube.com.

Reviewer Guide

This section summarizes the code architecture, native bridge, CI/CD, and the example app to help with reviews. For a full maintainer-oriented deep-dive and handover notes, see ARCHITECTURE.md.

Architecture Overview

• React Native/TypeScript source lives in src/. The public JS API and legacy wrapper are in src/ComplyCube.ts and src/ComplyCubeSDK.ts.
• The TurboModule spec used by the JS layer is defined in src/NativeComplyCubeModule.ts.
• Android native implementation is Kotlin under android/src/main/java/ (entry module: android/src/main/java/com/complycubereactnative/ComplyCubeModule.kt).
• iOS native implementation is Swift under ios/Sources/, with the RN bridge in ios/Sources/Bridge/ComplyCubeRN.swift and Objective‑C shim in ios/Sources/Bridge/ObjCShims/ComplyCubeRNSDKBridge.m.

React Native ↔ Native Bridge

• JS resolves the native module from both the TurboModule registry (src/NativeComplyCubeModule.ts) and legacy NativeModules, picking the first available in a platform-specific order (src/ComplyCube.ts): on iOS it prefers the legacy ComplyCubeRNSDK module, then the TurboModule, then the Android module; on Android/other it prefers the TurboModule, then the Android module, then iOS. This keeps the SDK working across both the old and new RN architectures.
• Events are emitted from native to JS using NativeEventEmitter (iOS) and DeviceEventEmitter (Android).
• The unified API surface in src/ComplyCube.ts normalizes success, error, and cancel events and exposes a subscribe helper for telemetry/custom events.

CI/CD (GitHub Actions)

• .github/workflows/compat.yml runs a React Native compatibility matrix (old/new architecture) for Android, iOS, and Expo, on pushes to main and new-arch-support.
• .github/workflows/npm_jfrog_develop.yml runs on pushes to develop: npm ci, tests, Codecov upload, npm run build, then publishes the dev build to ComplyCube's jFrog Artifactory npm registry.
• .github/workflows/npm_jfrog_main.yml runs on pushes to main: npm ci, tests, Codecov upload, npm run build, then publishes the public package to the npm registry (npm publish --access public).
• .github/workflows/npm_jfrog_coverage.yml runs on pull requests: npm ci, tests, and a Codecov upload. It is a CI gate only and does not publish (publishing is handled by the develop/main workflows above).

Example App

• The example project is in example/ with its own example/README.md.
• It contains iOS and Android native projects under example/ios and example/android for validating the SDK integration end‑to‑end.