# ComplyCube React Native SDK

[![Version](https://img.shields.io/npm/v/@complycube/react-native)](https://www.npmjs.org/package/@complycube/react-native@0.70.6)

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

[ComplyCube](https://www.complycube.com) 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:

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

    ```sh
    sudo gem install cocoapods
    ```

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

    ```ruby
    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`
    ```xml
    <key>NSCameraUsageDescription</key>
    <string>Used to capture facial biometrics and documents</string>
    ```

2. `NSMicrophoneUsageDescription`
    ```xml
    <key>NSMicrophoneUsageDescription</key>
    <string>Used to capture video biometrics</string>
    ```
### Android

Our SDK is available on Maven Central.

Update your application's `android/build.gradle` file with the ComplyCube SDK repository Maven settings and SDK dependency:

```gradle
repositories {
    mavenCentral()
}
 
dependencies {
    implementation "com.complycube:complycube-sdk:+"
}
```

## Getting Started

Visit our [step-by-step guide](https://docs.complycube.com/documentation/guides/mobile-sdk-guide) to quickly get started with our SDK.

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

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

Then run:

```sh
npx expo prebuild --clean
```

## Telemetry Events

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

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

### 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 calls into native via the TurboModule interface when available, with a fallback to legacy `NativeModules` for older RN setups.
- 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 PRs, main pushes, releases, and a weekly schedule.
- `.github/workflows/native_mapping_coverage.yml` runs Android unit tests with JaCoCo and iOS unit tests with Xcode coverage, then publishes a coverage summary.
- `.github/workflows/npm_jfrog_*` run npm install/test and upload coverage to Codecov on `develop` and `main`. The publish step is currently commented out in the develop workflow.

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