Cordova SDK (WiP)

A native and powerful Cordova SDK with advanced ML features.

Overview

The ComplyCube Cordova SDK enables you to embed a full identity verification flow directly into your iOS application using native, mobile-optimized components.

Designed for easy integration, the SDK handles everything from document capture and biometric liveness checks to proof of address and NFC authentication. It’s optimised for speed and accuracy, with features like auto-capture and real-time feedback.

Benefits

The SDK offers several benefits:

Mobile-native flow: Frictionless user experience using mobile-native UI components. Includes guided flows for capturing selfies, videos, identity documents, and proof of address.
Flexible integration: Use workflows to orchestrate complete verification journeys with minimal code, or configure individual stages (e.g. selfie, document, NFC) for more granular control.
Biometric verification: Supports photo and video-based liveness checks (PAD Level 2 certified) using passive and active techniques to detect spoofing.
Document & NFC verification: Supports OCR and RFID reading from passports, ID cards, and other chip-enabled documents. Cross-checks encrypted chip data for added assurance.
Smart auto-capture: Automatically captures selfies and documents with real-time quality checks, reducing user errors and ensuring optimal input for verification.
Custom branding: Customize accent colors, text, and logos to match your app’s visual identity.
Global-ready: Built-in support for multiple languages and localized UI labels.

To integrate workflows into this SDK, see the Blah Blah Blah.

For a quick copy-paste example, see the Quick Integration Guide.

Requirements

Swift 5.
iOS 13 and above.
Xcode 13 and above.

Overview of flow

The Mobile SDK runs on your mobile application, but relies on your backend to create secure tokens. Here’s how it works:

Create a client

Generate an SDK token

Your backend requests a JWT token tied to that client.

Initialize the SDK in your mobile app

Pass the token and settings to the SDK initializer.

Capture documents, videos, and selfies

The SDK guides your customer through the required steps.

Perform checks

Captured data is securely sent to ComplyCube for verification checks, and results are delivered in real time through the API or webhooks.

Integration guide

Install the SDK

Before using the ComplyCube SDK, install the CocoaPods plugin by running the following command in your terminal:
```
sudo gem install cocoapods
```

Add plugin repos and install the pod using your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
…
platform :iOS, ’13.0’

target ‘YourApp’ do
    …
  pod 'ComplyCubeMobileSDK'
end

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'] = '13.1'
            build_configuration.build_settings['ARCHS'] = ['$(ARCHS_STANDARD)', 'x86_64']
            build_configuration.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = ['arm64', 'arm64e', 'armv7', 'armv7s']
            build_configuration.build_settings['GENERATE_INFOPLIST_FILE'] = 'YES'
        end
    end
end

Application permissions

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

NSCameraUsageDescription

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

NSMicrophoneUsageDescription

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

Create a client

Every verification flow starts with a client (i.e. customer). Use the API to create the client.

This must be done on your mobile app backend server, not the mobile app itself.

Example request

curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "[email protected]",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const client = await complycube.client.create({
  type: "person",
  email: "[email protected]",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

from complycube import ComplyCubeClient
cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

new_client = {
    'type':'person',
    'email':'[email protected]',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe'
    }
}

client = cc_api.clients.create(**new_client)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => '[email protected]',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Clients;

var clientApi = new ClientApi(new ComplyCubeClient("<YOUR_API_KEY>"));
var newClient = new ClientRequest {
  type = "person",
  email = "[email protected]",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newclientRequest);

Example response

The response will contain an id (the Client ID). It is required for the next step.

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "[email protected]",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe",
    },
    "createdAt": "2020-01-04T17:24:29.146Z",
    "updatedAt": "2020-01-04T17:24:29.146Z"
}

See Clients API Reference to learn more.

Generate an SDK token

Your backend must create an SDK token for each new flow. This token enable clients to send personal data securely from your mobile app to ComplyCub.

Tokens are short-lived and must not be reused.

Example request

curl -X POST https://api.complycube.com/v1/tokens \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
           "clientId":"CLIENT_ID",
           "appId": "com.complycube.SampleApp"
         }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const token = await complycube.token.generate("CLIENT_ID", {
    appId: "com.complycube.SampleApp"
});

using ComplyCube.Net;
using ComplyCube.Net.Resources.SDKTokens;

var sdkTokenApi = new SDKTokenApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var sdkTokenRequest = {
  clientId = "CLIENT_ID",
  appId = "com.complycube.SampleApp"
}

var sdkToken = await sdkTokenApi.GenerateToken(sdkTokenRequest);

Example response

{
    "token": "<CLIENT_TOKEN>"
}

See SDK Token API Reference to learn more.

Prepare the stages

Set up the stages you wish to include in your flow.

let documentStage = DocumentStageBuilder()
  .setAllowedDocumentTypes(types: [
    .passport,
    .nationalIdentityCard(),
  ])
  .useLiveCaptureOnly(enable: false)
  .build()

// Kotlin

val complyCubeBuilder = ComplyCubeSdk.Builder(this, callback =  { }).apply {
    withStages(
        Document(
            identityDocumentType = Passport(), DrivingLicence(),
            useLiveCaptureOnly = false
        ),
        SelfiePhoto()
    )
}

// Java

IdentityDocumentType[] identityDocumentTypes;

identityDocumentTypes = new IdentityDocumentType[1];

identityDocumentTypes[0] = new DrivingLicence();

Document document = new Document(
    // documentType
    null,
    // documentTypes
    identityDocumentTypes,
    // isGuidanceEnabled
    true,
    // useLiveCaptureOnly
    false,
    // isMLAssistanceEnabled
    true,
    // retryLimit
    5,
    // isNFCEnabled
    true
);

const stages = [
  {
    name: "intro",
    heading: "Green Bank ID verification",
  },
  {
    name: "documentCapture",
    showGuidance: false,
    useMLAssistance: true,
    retryLimit: 1,
    documentTypes: {
      passport: true,
      driving_license: ["GB", "FR"],
    },
  },
  "faceCapture",
];

final stages = [
  {
    "name": 'intro',
    "heading": 'Green Bank ID verification',
  },
  {
    "name": 'documentCapture',
    "showGuidance": false,
    "useMLAssistance": true,
    "retryLimit": 1,
    "documentTypes": {
      "passport": true,
      "driving_license": ['GB', 'FR'],
    },
  },
  'faceCapture',
];

const stages = [
  {
    name: "intro",
    heading: "Green Bank ID verification",
  },
  {
    name: "documentCapture",
    showGuidance: false,
    useMLAssistance: true,
    retryLimit: 1,
    documentTypes: {
      passport: true,
      driving_license: ["GB", "FR"],
    },
  },
  "faceCapture",
];

Initialize the SDK

You can now initialize a flow. The sequence of stages you specify determines the order in which your client sees those stages.

let sdk = ComplyCubeMobileSDK.FlowBuilder()
  .withSDKToken("SDK_TOKEN")
  .withClientId("CLIENT_ID")
  .withStages([documentStage, selfieStage])
  .start(fromVc: self)

var clientAuth = ClientAuth("SDK_TOKEN", "CLIENT_ID")

// Kotlin

val complyCubeBuilder = ComplyCubeSdk.Builder(this, callback =  { }).apply {
    withStages(
        Document(
            identityDocumentType = Passport(), DrivingLicence(),
            useLiveCaptureOnly = false
        ),
        SelfiePhoto()
    )
}.start(
    ClientAuth(
        token = "SDK_TOKEN",
        clientId = "CLIENT_ID"
    )
)

// Java

ComplyCubeSdk.Builder complycubeFlow =
    new ComplyCubeSdk.Builder(this, result - > {});

complycubeFlow.withStages(
    document,
    new SelfiePhoto()
);

complycubeFlow.start(new ClientAuth(
    "SDK_TOKEN",
    "CLIENT_ID"
));

import { ComplyCube } from "@complycube/react-native";
// ...

const settings = {
  clientID: "<CLIENT_ID>",
  clientToken: "<CLIENT_TOKEN>",
  stages: stages,
  // ... other settings
};

return (
  <View style={styles.container}>
    <ComplyCube settings={settings} />
  </View>
);

import 'package:complycube_flutter/ComplyCubeMobileSDK.dart';
// ...

final settings = {
  "clientID": "<CLIENT_ID>",
  "clientToken": "<CLIENT_TOKEN>",
  "stages": stages,
  // ...
}

return MaterialApp(
  home: Scaffold(
    appBar: AppBar(
      title: Text('ComplyCube Integration'),
    ),
    body: ComplyCubeWidget(settings: settings),
  ),
);

var complycube = cordova.require("complycube-sdk-cordova.ComplyCube");
//...

const settings = {
  clientID: "<CLIENT_ID>",
  clientToken: "<CLIENT_TOKEN>",
  stages: stages,
  // ... other settings
};

complycube.start(
    settings,
        (results) => console.log("Success"), 
        (cancel_event) => console.log("Cancel event fired"), 
        (error_event) => console.log("Error event fired"), 
        (custom_event) => console.log("Custom event fired"), 
        (token_event) => console.log("Token expiry event fired")
);

Perform checks

Using the results returned in the onSuccess callback, you can trigger your mobile backend to run the necessary checks on your client.

For example, use the result of a selfie and document capture as follows:

result.documentId to run a Document Check.
result.documentId and result.livePhotoId to run an Identity Check.

Example request for a Document Check

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
            "clientId":"CLIENT_ID",
            "type": "document_check",
            "documentId":"DOCUMENT_ID"
         }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const check = await complycube.check.create("CLIENT_ID", {
    type: "document_check",
    documentId: "DOCUMENT_ID"
});

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->checks()->create('CLIENT_ID', [
    'type' => 'document_check',
    'documentId' => 'DOCUMENT_ID'
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  type = "document_check",
  documentId = "DOCUMENT_ID"
};

var check = await checkApi.CreateAsync(checkRequest);

If you have set up webhooks as described in our webhooks guide, you will be notified once a check completes.

To retrieve the check results, you can perform a get check request.

Retrieve verification results

Your mobile backend can retrieve all check results using our API.

All our checks are asynchronous. If you have set up webhooks as described in our webhooks guide, you will be notified once a check completes.

To retrieve the check results, you can perform a get check request.

Example request

curl -X GET https://api.complycube.com/v1/checks/{:checkId} \
     -H 'Authorization: <YOUR_API_KEY>'

Stages

Each stage in the flow can be customized to create the ideal journey for your customers.

The snippet below demonstrates how to set up a customized flow using the ComplyCube Mobile SDK.

let sdk = ComplyCubeMobileSDK.FlowBuilder()
  .withSDKToken("SDK_TOKEN")
  .withClientId("CLIENT_ID")
  .withStages([
    WelcomeStageBuilder().build(),
    UserConsentStageBuilder().build(),
    DocumentStageBuilder().build(),
    BiometricStageBuilder().build(),
    AddressCaptureStageBuilder().build(),
    ProofOfAddressBuilder().build(),
  ])
  .withEnableCompleteScreen(...)
  .withLanguage(...)
  .withLookAndFeel(...)
  .withEventHandler(...)
  .withCallbackHandler(...)
  .start(fromVc: self)

// Kotlin

var complycubeFlow = ComplyCubeSdk.Builder(this, callback = ...)
  .withSDKToken("SDK_Token")
  .withClientId("CLIENT_ID")
  .withStages(
    Welcome(...),
    Consent(...),
    Document(...),
    SelfiePhoto(...),
    AddressCapture(...),
    ProofOfAddress(...),
    Complete(...)
  )
  .withLookAndFeel(...)
  .withCustomLanguage(...)

complycubeFlow.start()

// Java

complycubeFlow.withStages(
    new Welcome(...),
    new UserConsent(...),
    new Document(...),
    new SelfiePhoto(...),
    new AddressCapture(...),
    new ProofOfAddress(...),
    new Complete(...)
);

complycubeFlow.withLookAndFeel(...);
complycubeFlow.withCustomLanguage(..);

const stages = [
  {
    name: 'intro',
    // ... other settings
  },
  {
    name: "consent",
    // ... other settings
  },
  {
    name: 'documentCapture',
    // ... other settings
  },
  {
    name: "faceCapture",
    // ... other settings
  },
  {
    name: "poaCapture",
    // ... other settings
  },
  {
    name: "complete",
    // ... other settings
  }
];

const settings = {
  clientID: "CLIENT_ID",
  clientToken: "SDK_TOKEN",
  stages: stages,
  language: "en",
  lookAndFeel: {/*...*/}
}

<ComplyCube
  settings={settings} 
  onSuccess={/*...*/} 
  onCancel={/*...*/}
  onError={/*...*/}
  onEventCallback={/*...*/}
/>

final stages = [
  {
    name: 'intro',
    // ... other settings
  },
  {
    name: "consent",
    // ... other settings
  },
  {
    name: 'documentCapture',
    // ... other settings
  },
  {
    name: "faceCapture",
    // ... other settings
  },
  {
    name: "poaCapture",
    // ... other settings
  },
  {
    name: "complete",
    // ... other settings
  }
];

final settings = {
  "clientID": "<CLIENT_ID>",
  "clientToken": "<CLIENT_TOKEN>",
  "stages": stages,
  "language": "en",
  "lookAndFeel": {/*...*/}
}

return MaterialApp(
  home: Scaffold(
    appBar: AppBar(
      title: Text('ComplyCube Integration'),
    ),
    body: ComplyCubeWidget(settings: settings),
  ),
);

const stages = [
  {
    name: 'intro',
    // ... other settings
  },
  {
    name: "consent",
    // ... other settings
  },
  {
    name: 'documentCapture',
    // ... other settings
  },
  {
    name: "faceCapture",
    // ... other settings
  },
  {
    name: "poaCapture",
    // ... other settings
  },
  {
    name: "complete",
    // ... other settings
  }
];

const settings = {
  clientID: "CLIENT_ID",
  clientToken: "SDK_TOKEN",
  stages: stages,
  language: "en",
  lookAndFeel: {/*...*/}
}

complycube.start(settings);

Welcome

The Welcome screen is always shown first in the verification flow. It displays a welcome message along with a summary of the configured stages the user will complete.

You can customize the screen title to align with your app’s tone and branding.

let welcomeStage = WelcomeStageBuilder()
  .setTitle(title: "Custom Screen Title")
  .setMessage(message: "Custom welcome message.")
  .build()

// Kotlin

var welcomeStage = Welcome(
    title = "Custom Screen Title",
    message = "Custom welcome message."
)

 // Java
 
 Welcome welcome = new Welcome(
     "Custom Screen Title",
     "Custom welcome message",
     null
 );

const settings = {
  // ... other settings
  stages: [
    {
      name: "intro",
      heading: "Custom Screen Title",
      message: "Custom welcome message.",
    },
    // ... other stages
  ],
};

final settings = {
  // ... other settings
  "stages": [
    {
      "name": "intro",
      "heading": "Custom Screen Title",
      "message": "Custom welcome message.",
    },
    // ... other stages
  ],
};

const settings = {
  // ... other settings
  stages: [
    {
      name: "intro",
      heading: "Custom Screen Title",
      message: "Custom welcome message.",
    },
    // ... other stages
  ],
};

This stage is used to collect explicit user consent before proceeding with the verification flow. It helps you meet regulatory and compliance requirements where applicable.

You can customize the screen title and message to match your legal or branding needs.

let consentStage = UserConsentStageBuilder()
     .setTitle(title: "Terms of Service")
     .build()

Selfie photo and video

You can request either a selfie photo (i.e. a Live Photo) or a selfie video (i.e. a Live Video) from the customer as part of the biometric verification process.

Photo: Captures a still image and performs a passive liveness check before allowing submission.
Video: Records a short video where the user completes an on-screen challenge (e.g. head movement or spoken phrase).

If you attempt to add both types of stages, the SDK will throw a ComplyCubeErrorCode.BiometricStageCount error stating multiple conflicting stages.

let selfieStage = BiometricStageBuilder()
  .setType(type: .photo)
  // Enable ML assistance during capture
  .setEnableMLAssistant(enable: false)
  .build()

// Kotlin

var selfiePhoto = SelfiePhoto(
    // Enable ML assistance during capture
    isMLAssistantEnabled = false
)

// Java

SelfiePhoto selfiePhoto = new SelfiePhoto(
    // isGuidanceEnabled
    true,
    // useLiveCaptureOnly
    true,
    // isMLAssistanceEnabled
    false,
    // retryLimit
    5
);

const settings = {
  // ... other settings
  stages: [
    {
      name: "faceCapture",
      mode: "photo",
      // Enable ML assistance during capture
      useMLAssistance: false,
    },
    // ... other stages
  ],
};

final settings = {
  // ... other settings
  "stages": [
    {
      "name": "faceCapture",
      "mode": "photo",
      // Enable ML assistance during capture
      "useMLAssistance": false,
    },
    // ... other stages
  ],
};

const settings = {
  // ... other settings
  stages: [
    {
      name: "faceCapture",
      mode: "photo",
      // Enable ML assistance during capture
      useMLAssistance: false,
    },
    // ... other stages
  ],
};

let videoStage = BiometricStageBuilder()
  .setType(type: .video)
  // Enable ML assistance during capture
  .setEnableMLAssistant(enable: false)
  .build()

// Kotlin

var selfieVideo = SelfieVideo(
    // Enable ML assistance during capture
    isMLAssistantEnabled = false
)

// Java

 SelfieVideo selfieVideo = new SelfieVideo(
     // isGuidanceEnabled
     true,
     // isMLAssistanceEnabled
     false,
     // retryLimit
     5
 );

const settings = {
  // ... other settings
  stages: [
    {
      name: "faceCapture",
      mode: "video",
      // Enable ML assistance during capture
      useMLAssistance: false,
    },
    // ... other stages
  ],
};

final settings = {
  // ... other settings
  "stages": [
    {
      "name": "faceCapture",
      "mode": "video",
      // Enable ML assistance during capture
      "useMLAssistance": false,
    },
    // ... other stages
  ],
};

const settings = {
  // ... other settings
  stages: [
    {
      name: "faceCapture",
      mode: "video",
      // Enable ML assistance during capture
      useMLAssistance: false,
    },
    // ... other stages
  ],
};

Document

The Document stage allows users to select and capture an identity document for verification (e.g. passport, ID card, residence permit). You can customize these screens to:

Limit the scope of document types the client can select, e.g., Passport only.
Set the document issuing countries they are allowed for each document type.
Add or remove automated capture using smart assistance.
Show or hide the instruction screens before capture.
Set a retry limit to allow clients to progress the journey regardless of capture quality.

If you provide only one document type, the document type selection screen will be skipped. The country selection screen will be skipped if you provide only a single country for a given document type.

You can control whether instructional screens are shown before each camera capture by enabling or disabling guidance mode. Only disable guidance if your users are already clearly informed about the capture steps, as these screens help reduce user error and improve capture quality.

Please note the retryLimit you set here will take precedence over the retry limit that has been set globally in your automation settings.

let docStage = DocumentStageBuilder()
  // Set document types and limit the enabled countries
  .setAllowedDocumentTypes(types: [
    .passport,
    .drivingLicence(["GB", "US"]),
    .nationalIdentityCard(),
  ])
  // Set a maximum for quality check attempts before uploading
  .setRetryLimit(count: 3)
  // Enable or disable additional guidance for the user
  .setShowGuidance(enable: true)
  // Enable ML assistance during capture
  .setEnableMLAssistant(enable: true)
  .build()

// Kotlin

var documentStage = Document(
    // Set document types and limit the enabled countries
    Passport(), DrivingLicence((Country.GB, Country.US)),

    // Enable or disable additional guidance for the user
    isGuidanceEnabled = true,

    // Enable or disable the ability to upload an image from file
    useLiveCaptureOnly = true,

    // Enable ML assistance during capture
    isMLAssistantEnabled = true,
    
    // Set a maximum for quality check attempts before uploadingoft checks
    retryLimit = 3
)

// Java

IdentityDocumentType[] identityDocumentTypes;

identityDocumentTypes = new IdentityDocumentType[1];

identityDocumentTypes[0] = new DrivingLicence();

Document document = new Document(
    null,
    identityDocumentTypes, // documentTypes
    true, // isGuidanceEnabled
    false, // useLiveCaptureOnly
    true, // isMLAssistanceEnabled
    5, // retryLimit
    true // isNFCEnabled
);

const settings = {
  // ... other settings
  stages: [
    {
      name: "documentCapture",

      // Enable or disable additional guidance for the user
      showGuidance: false,

      // Enable ML assistance during capture
      useMLAssistance: true,

      // Set a maximum for quality check attempts before uploading
      retryLimit: 1,

      // Enable or disable the ability to upload an image from file
      liveCapture: false,

      // Set document types and limit the enabled countries
      documentTypes: {
        passport: true,
        driving_license: ["GB", "US"],
      },
    },
    // ... other stages
  ],
};

final settings = {
  // ... other settings
  "stages": [
    {
      "name": "documentCapture",

      // Enable or disable additional guidance for the user
      "showGuidance": false,

      // Enable ML assistance during capture
      "useMLAssistance": true,

      // Set a maximum for quality check attempts before uploading
      "retryLimit": 1,

      // Enable or disable the ability to upload an image from file
      "liveCapture": false,

      // Set document types and limit the enabled countries
      "documentTypes": {
        "passport": true,
        "driving_license": ['GB', 'US'],
      },
    },
    // ... other stages
  ],
};

const settings = {
  // ... other settings
  stages: [
    {
      name: "documentCapture",

      // Enable or disable additional guidance for the user
      showGuidance: false,

      // Enable ML assistance during capture
      useMLAssistance: true,

      // Set a maximum for quality check attempts before uploading
      retryLimit: 1,

      // Enable or disable the ability to upload an image from file
      liveCapture: false,

      // Set document types and limit the enabled countries
      documentTypes: {
        passport: true,
        driving_license: ["GB", "US"],
      },
    },
    // ... other stages
  ],
};

NFC capture

The ComplyCube mobile SDK supports NFC-based RFID chip reading for identity documents equipped with embedded chips. This allows for secure data extraction and high-assurance document authentication.

Please get in touch with your Account Manager or support to get access to our NFC-enabled Mobile SDK.

Pre-requisites

To use this feature, your app must have the Near Field Communication Tag Reading capability enabled. To add this capability to your app, refer to Apple's guide here.

Install the CocoaPods Artifactory plugin by running the following command in your terminal:
```
gem install cocoapods-art
```
To add the library, copy your repository credentials into a .netrc file to your home directory and setup the repository:
```
pod repo-art add cc-cocoapods-release-local "https://complycuberepo.jfrog.io/artifactory/api/pods/cc-cocoapods-release-local"
```
Remember to fetch your credentials from JFrog using the Set Me Up button here.

Add plugin repos and install the pod using your Podfile:

 plugin 'cocoapods-art', :sources => [
   'cc-cocoapods-release-local',
   'trunk'
 ]
 ...
 platform :ios, '13.0' # Or above

 target 'YourApp' do
   use_frameworks!
   use_modular_headers!
   ...
   pod 'ComplyCubeMobileSDK', '1.2.6-nfc'
   ...
 en

You must add the following keys to your application Info.plist file:

<key>NFCReaderUsageDescription</key>
<string>Required to read from NFC enabled documents</string>

To read NFC tags correctly, you need to add the following entries to your app target's Info.plist file:

<key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
  <string>12FC</string>
</array>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
  <string>A0000002472001</string>
  <string>00000000000000</string>
  <string>D2760000850101</string>
</array>

Start by adding your access credentials for the ComplyCube NFC-Enabled SDK repository to the gradle.properties file of your mobile app:

USE_NFC=true
artifactory_contextUrl=https://complycuberepo.jfrog.io/artifactory/cc-gradle-release
artifactory_user=<YOUR_USERNAME>
artifactory_password=<YOUR_PASSWORD>

Replace <YOUR_USERNAME> and <YOUR_PASSWORD> with your ComplyCube Artifactory credentials. If you don’t have access, contact ComplyCube Support to request credentials.

Then, update your project level build.gradle or build.gradle.kts file with the ComplyCube SDK repository Maven settings:

repositories {
    google()
    mavenCentral()
    maven {
        url project.findProperty("artifactory_contextUrl")
        credentials {
            username = project.findProperty("artifactory_user")
            password = project.findProperty("artifactory_password")
        }
    }
}

repositories {
    google()
    mavenCentral()
    maven {
        url = uri(project.findProperty("artifactory_contextUrl") as String)
        credentials {
            username = project.findProperty("artifactory_user") as String?
            password = project.findProperty("artifactory_password") as String?
        }
    }
}

Enabling NFC capture

let docStage = DocumentStageBuilder()
  // Add this property to enable NFC
  .setEnableNFC(enable: true)
  .build()

// Kotlin

var documentStage = Document(
    // Add this property to enable NFC
    isNFCEnabled = true,
)

// Java

IdentityDocumentType[] identityDocumentTypes;

identityDocumentTypes = new IdentityDocumentType[1];

identityDocumentTypes[0] = new Passport();

Document document = new Document(
    null,
    // documentTypes
    identityDocumentTypes,
    // isGuidanceEnabled
    true,
    // useLiveCaptureOnly
    false,
    // isMLAssistanceEnabled
    true,
    // retryLimit
    5,
    // isNFCEnabled
    true
);

const settings = {
    // ... other settings
    stages : [
      {
        name: 'documentCapture',
        // Add this property to enable NFC
        nfcCapture: true
        ...
      },
      // ... other stages
    ]
}

final settings = {
    // ... other settings
    "stages" : [
      {
        "name": "documentCapture",
        // Add this property to enable NFC
        "nfcCapture": true
        ...
      },
      // ... other stages
    ]
}

const settings = {
    // ... other settings
    stages : [
      {
        name: 'documentCapture',
        // Add this property to enable NFC
        nfcCapture: true
        ...
      },
      // ... other stages
    ]
}

Address capture

This stage allows users to manually enter their residential address. You can customize it to:

Restrict input to specific countries
Enable or disable the address autocomplete feature for faster and more accurate entry

let addressCaptureStage = AddressCaptureStageBuilder()
  // This enables our address autocomplete feature
  .useAutoComplete(enable: false)
  // A list of acceptable countries for address capture feature
  .setAllowedCountries(["GB", "US"])
  .build()

// Kotlin

var addressCaptureStage = AddressCapture(
    // This enables our address autocomplete
    useAutoComplete = true,
    
    // A list of acceptable countries for address capture feature
    allowedCountries = setOf(Country.GB,Country.US)
)

// Java

Set<Country> countries = new HashSet<> ();

countries.add(Country.GB);
countries.add(Country.US);

AddressCapture addressCapture = new AddressCapture(
    // useAutoComplete
    true,
    // allowedCountries
    countries
);

const settings = {
  // ... other settings
  stages: [
    {
      name: "addressCapture",

      // This enables our address autocomplete feature
      useAutoComplete: false,
      
      // A list of acceptable countries for address capture
      allowedCountries: ['GB','US']
    },
    // ... other stages
  ],
};

final settings = {
  // ... other settings
  stages: [
    {
      "name": "addressCapture",

      // This enables our address autocomplete feature
      "useAutoComplete": false,
      
      // A list of acceptable countries for address capture
      "allowedCountries": ['GB','US']
    },
    // ... other stages
  ],
};

const settings = {
  // ... other settings
  stages: [
    {
      name: "addressCapture",

      // This enables our address autocomplete feature
      useAutoComplete: false,
      
      // A list of acceptable countries for address capture
      allowedCountries: ["GB","US"]
    },
    // ... other stages
  ],
};

Proof of address

This stage allows customers to submit a document verifying their residential address. You can configure which document types are accepted, such as utility bills or bank statements, and choose whether customers can upload a file or must capture the document live using their device camera.

By default, this stage includes the address capture stage with autocomplete enabled to assist users during entry. Autocomplete can be disabled if not required.

let poaStage = AddressStageBuilder()
  .setAllowedDocumentTypes(types: [
    .utilityBill,
    .bankStatement
  ])
  // When disabled, the client will be forced to perform a live capture
  .useLiveCaptureOnly(enable: false)
  // This enables address capture during the proof of address flow
  .setEnableAddressCapture(true)
  .build()

//Kotlin

var poaStage = ProofOfAddress(
    // A list of supported document types that can be submitted
    UtilityBill(), BankStatement(),

    // When disabled, the client will be forced to perform a live capture
    useLiveCaptureOnly = false,

    // This enables address capture during the proof of address flow
    isAddressCaptureEnabled = false
    ...
)

// Java

LinkedHashSet<ProofOfAddressDocumentType> documentTypes =
    new LinkedHashSet<ProofOfAddressDocumentType> ();

documentTypes.add(new UtilityBill());
documentTypes.add(new BankStatement());

ProofOfAddress poaStage = new ProofOfAddress(
    documentTypes,
    // isGuidanceEnabled
    true,
    // useLiveCaptureOnly
    false,
    // isMLAssistanceEnabled
    true,
    // retryLimit
    5,
    // isAddressCaptureEnabled
    false
);

const settings = {
  // ... other settings
  stages: [
    {
      name: "poaCapture",

      // When disabled, the client will be forced to perform a live capture
      liveCapture: false,
    },
    // ... other stages
  ],
};

final settings = {
  // ... other settings
  stages: [
    {
      "name": "poaCapture",

      // When disabled, the client will be forced to perform a live capture
      "liveCapture": false,
    },
    // ... other stages
  ],
};

const settings = {
  // ... other settings
  stages: [
    {
      name: "poaCapture",

      // When disabled, the client will be forced to perform a live capture
      liveCapture: false,
    },
    // ... other stages
  ],
};

Completion

You can include a completion stage at the end of the flow to confirm that the process has been successfully finished. This screen provides a clear end point for the user and can be customized to display a confirmation message or next steps.

var completionStage = Complete(
    title: "Thank you!",
    message: "Your KYC submission has been completed"
)

// Kotlin

val completionStage = Complete(
    title = "Thank you!",
    message = "Your KYC submission has been completed"
)

// Java

Complete complete = new Complete(
    "Custom Complete Title",
    "Custom Complete Message",
    null
);

const settings = {
  // ... other settings
  stages: [
    {
      name: "complete",
      heading: "Thank you!",
      message: "Your KYC submission has been completed.",
    },
    // ... other stages
  ],
};

final settings = {
  // ... other settings
  "stages": [
    {
      "name": "complete",
      "heading": "Thank you!",
      "message": "Your KYC submission has been completed.",
    },
    // ... other stages
  ],
};

const settings = {
  // ... other settings
  stages: [
    {
      name: "complete",
      heading: "Thank you!",
      message: "Your KYC submission has been completed.",
    },
    // ... other stages
  ],
};

Branding

The SDK allows you to customize the UI to match your application’s visual identity. You can define primary and accent colors during configuration to align the verification flow with your brand guidelines. Learn more about our appearance properties (see below).

Creating a custom appearance

Before initiating the flow, create your own custom design and integrate it into your Flow Builder.

let ccLookAndFeel = LookAndFeel()
ccLookAndFeel.primaryButtonBgColor = .green
ccLookAndFeel.uiInterfaceStyle = .dark //can also be .light or .inherited

Applying your custom appearance

Set the custom appearance that you have created using the Flow Builder.

let sdk = ComplyCubeMobileSDK.FlowBuilder()
  .withLookAndFeel(ccLookAndFeel)
  .start(fromVc: self)

// Kotlin

complycubeFlow.withLookAndFeel(
    lookAndFeel = LookAndFeel(
        primaryButtonBgColor = Color.RED,
        /* Can also be set to UIInterfaceStyle.LIGHT 
        or UIInterfaceStyle.INHERITED */
        uiInterfaceStyle = UIInterfaceStyle.DARK
    )
)

// Java

complycubeFlow.withLookAndFeel(new LookAndFeel(
    // primaryButtonBGColor
    Color.parseColor("#FF0000"),
    // uiInterfaceStyle
    UIInterfaceStyle.DARK,
    ...
));

const settings = {
  // ...
  lookAndFeel: {
    // Primary action button background color
    primaryButtonBgColor: "#FFFFFF",

    // Force SDK to 'dark', 'light', or 'inherit' mode
    uiInterfaceStyle: "dark",
  },
};

final settings = {
  // ...
  "lookAndFeel": {
    // Primary action button background color
    "primaryButtonBgColor": '#FFFFFF',
    
    // Force SDK to 'dark', 'light', or 'inherit' mode
    "uiInterfaceStyle": "dark"
  }
}

To disable the header display in the ComplyCube SDK Widget on Android, please insert the following line into styles.xml:

<style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar">
  ...
  <item name="windowActionBar">false</item>
  <item name="windowNoTitle">true</item>
  ...
</style>
...

const settings = {
  // ...
  lookAndFeel: {
    // Primary action button background color
    primaryButtonBgColor: "#FFFFFF",

    // Force SDK to 'dark', 'light', or 'inherit' mode
    uiInterfaceStyle: "dark",
  },
};

Localization

The SDK supports several languages, including those listed below.

Arabic - ar 🇦🇪
Chinese (Simplified) - zh 🇨🇳
Chinese (Traditional) - hk 🇨🇳
Dutch - nl 🇳🇱
English - en 🇺🇸
French - fr 🇫🇷
German - de 🇩🇪
Hindi - hi 🇮🇳
Indonesian - id 🇮🇩
Italian - it 🇮🇹

Japanese - ja 🇯🇵
Korean - ko 🇰🇷
Norwegian - no 🇳🇴
Polish - po 🇵🇱
Portuguese - pt 🇵🇹
Spanish - es 🇪🇸
Swedish - sv 🇸🇪
Thai - th 🇹🇭
Vietnamese - vi 🇻🇳
and more...

Result handling

To run verification checks, you must implement the success, cancelled, and error callbacks.

On a successful completion (onSuccess), you can trigger check requests from your backend using the resource IDs returned in the result object. These IDs correspond to the uploaded assets (e.g. documents, selfies) and can be used to initiate verification checks via the ComplyCube API.

If the user exits the flow before completion, the onCancelled callback is invoked with a descriptive reason indicating why the session was cancelled (e.g. user exit, timeout, permission denied)

In some cases, the customer may cancel the flow after completing one or more capture stages. If this occurs, any data captured prior to cancellation, such as documents or biometric media, may have already been uploaded to their client record.

If the SDK encounters an issue, the onError callback is triggered with a ComplyCubeError object containing the error type and message. Refer to the error codes (see below), for a full list of possible error cases.

extension ViewController: ComplyCubeMobileSDKDelegate {
  func onSuccess(_ result: ComplyCubeResult) {
   /*
    Handling successful results:
    Our default flow includes three components: an Identity Document,
    a Selfie (Live Photo), and a Proof of Address. Upon successful 
    completion, the 'result' parameter will contain `documentIds`and `livePhotoId`
    */
    print("The flow has completed - here are the ID's returned")
  }
  
  func onError(_ error: ComplyCubeError) {
    // Handle errors
    print("An error has occurred")
  }

  func onCancelled(_ error: ComplyCubeError) {
    // Handle cancellations
    print("The user has cancelled the flow or not accepted the terms")
  }  
}

//Kotlin

//Register a result handler to process the outcome of the flow.
var complycubeFlow =
    ComplyCubeSdk.Builder(
        this,
        callback = { result ->
            when (result) {
                is Result.Success -> { 
                /*
                Handling successful results:
                Our default flow includes three components: an Identity Document,
                a Selfie (Live Photo), and a Proof of Address. Upon successful 
                completion, the 'Result' will contain an array of stage results.
                Each stage result provides the ID of the uploaded item:
                  - 'StageResult.Document.Id': the uploaded Document ID.
                  - 'StageResult.LivePhoto.Id': the uploaded Live Photo ID.
                  - 'StageResult.ProofOfAddress.Id': the uploaded PA Document ID.
                */
                }
                is Result.Cancelled -> { /* Handle Cancelled result */ }
                is Result.Error -> {
                    // Handle errors
                    when (result.errorCode) {
                        ComplyCubeErrorCode.UploadError -> {
                            // Handle Upload error
                        }
                        ComplyCubeErrorCode.BiometricStageCount -> {
                            // Handle BiometricStageCount error
                        }
                        // ...other error handlers
                    }
                }
                else -> {}
            }
        }
    )

complycubeFlow.start(clientAuth)

// Java

//Register a result handler to process the outcome of the flow.
ComplyCubeSdk.Builder complycubeFlow = new ComplyCubeSdk.Builder(this, result - > {
    if (result instanceof Result.Success) {
        /*
        Handling successful results:
        Our default flow includes three components: an Identity Document,
        a Selfie (Live Photo), and a Proof of Address. Upon successful 
        completion, the 'Result' will contain an array of stage results.
        Each stage result provides the ID of the uploaded item:
          - 'StageResult.Document.Id': the uploaded Document ID.
          - 'StageResult.LivePhoto.Id': the uploaded Live Photo ID.
          - 'StageResult.ProofOfAddress.Id': the uploaded PA Document ID.
        */
    } else if (result instanceof Result.Error) {
        switch (((Result.Error) result).getErrorCode()) {
            case ComplyCubeErrorCode.UploadError.INSTANCE:
                // Handle upload error
                break;
            case ComplyCubeErrorCode.BiometricStageCount.INSTANCE:
                // Handle BiometricStageCountError
                break;
                // ... other error handlers
            default:
        }
    } else if (result instanceof Result.Canceled) {
        // Handle Cancelled result
    }
    return null;
});

function onSuccess(results){
  /*
    Handling successful results:
    Our default flow includes three components: an Identity Document,
    a Selfie (Live Photo), and a Proof of Address. Upon successful 
    completion, the 'results' parameter will contain: 
      - "documentIds": ["xxxxx"]
      - "livePhotoIds": ["xxxxx"]
      - "poaIds": ["xxxxxx"]
  */
  console.log(results);
}

function onCancelled(){
  console.log("The user cancelled");
}

function onError(error){
  console.log(error);
}

return(<View>
    <ComplyCube 
      settings={settings}
      onSuccess={onSuccess}
      onCancel={onCancelled}
      onError={onError}
       />
  </View>
)

void onSuccess(Map<String, dynamic> results) {
 /*
    Handling successful results:
    Our default flow includes three components: an Identity Document,
    a Selfie (Live Photo), and a Proof of Address. Upon successful 
    completion, the 'results' parameter will contain: 
      - "documentIds": ["xxxxx"]
      - "livePhotoIds": ["xxxxx"]
      - "poaIds": ["xxxxxx"]
  */
}

void onCancelled() {
  // Handle cancellations
}

void onError(ComplyCubeError error) {
  // Handle errors
}

ComplyCubeWidget(
  settings: settings,
  onSuccess: onSuccess,
  onCancelled: onCancelled,
  onError: onError,
)

function onSuccess(results){
  /*
    Handling successful results:
    Our default flow includes three components: an Identity Document,
    a Selfie (Live Photo), and a Proof of Address. Upon successful 
    completion, the 'results' parameter will contain: 
      - "documentIds": ["xxxxx"]
      - "livePhotoIds": ["xxxxx"]
      - "poaIds": ["xxxxxx"]
  */
  console.log(results);
}

function onCancelled(){
  console.log("The user cancelled");
}

function onError(error){
  console.log(error);
}

complycube.start(
    settings,
        (results) => console.log("Success"), 
        (cancel_event) => console.log("Cancel event fired"), 
        (error_event) => console.log("Error event fired"), 
        (custom_event) => console.log("Custom event fired"), 
        (token_event) => console.log("Token expiry event fired")
);

Events tracking

The SDK tracks a range of events throughout the verification flow, covering all key user interactions across stages. See below for the list of events.

If you need to implement custom analytics, you can hook into these events and trigger your own tracking logic accordingly.

To incorporate your own tracking, define a function and apply it using withEventHandler when initializing the FlowBuilder:

let sdk = ComplyCubeMobileSDK.FlowBuilder()
  .withEventHandler({ (event: Event) -> Void in
    // Insert custom user tracking code here
  })

To incorporate your own tracking, define a function and apply it using withEventHandler when initializing the Builder:

// Kotlin

complycubeBuilder.withEventHandler(true) { event ->
    // Insert custom user tracking here
}

// Java

complycubeFlow.withEventHandler(true, analyticsEvent - >
    // Insert custom user tracking here
);

To incorporate your own tracking, define a function and apply it using the eventHandler property in your settings:

function myCustomEventHandler(event){
  // Insert custom user tracking code here
  console.log(event.code);
  console.log(event.message);
}

const settings = {
  eventHandler: {myCustomEventHandler}
  // ... other settings
}

To incorporate your own tracking, define a function and apply it using the onCustomEvent property when initializing the Flutter widget:

void onCustomEvent(ComplyCubeCustomEvent event){
  switch(event.name){
    case 'BIOMETRICS_STAGE_SELFIE_CAMERA':
      print("The client reached capture camera for a selfie")
      break;
  }
}

ComplyCubeWidget(
  settings: settings,
  onCustomEvent: onCustomEvent,
  // ...
),

To incorporate your own tracking, define a function and apply it using the eventHandler property in your settings:

function myCustomEventHandler(event){
  // Insert custom user tracking code here
  console.log(event.code);
  console.log(event.message);
}

complycube.start(
    settings,
        (results) => console.log("Success"), 
        (cancel_event) => console.log("Cancel event fired"), 
        (error_event) => console.log("Error event fired"), 
        myCustomEventHandler, 
        (token_event) => console.log("Token expiry event fired")
);

Token expiry handling

To handle token expiration gracefully, you can provide a callback function that generates a new SDK token when needed. This allows the flow to continue seamlessly without requiring the user to restart the session manually.

let sdk = ComplyCubeMobileSDK.FlowBuilder()
  .withTokenExpiryHandler({ () -> String in
    // Insert custom token renewal code here
  })

// Kotlin

var complyCubeBuilder = ComplyCubeSdk.Builder(this,
    callback = { result ->
        if (result is Result.Error) {
            if (result.errorCode is ComplyCubeErrorCode.ExpiredToken) {
                // Insert custom token renewal code here
            }
        }
    }
)

// Java

ComplyCubeSdk.Builder complyCubeBuilder =
    new ComplyCubeSdk.Builder(this, result - > {
        if (result instanceof Result.Error) {
            if (((Result.Error) result).getErrorCode() == ComplyCubeErrorCode.ExpiredToken.INSTANCE) {
                // Insert custom token renewal code here
            }
        }
        return null;
    });

function myCustomExpiryHandler(){
  // Insert custom token renewal code here
}

complycube.start(
    settings,
        (results) => console.log("Success"), 
        (cancel_event) => console.log("Cancel event fired"), 
        (error_event) => console.log("Error event fired"), 
        (custom_event) => console.log("Custom event fired"),
        myCustomExpiryHandler
);

Good afternoon

hashtagOverview

hashtagBenefits

hashtagRequirements

hashtagOverview of flow

hashtagCreate a client

hashtagGenerate an SDK token

hashtagInitialize the SDK in your mobile app

hashtagCapture documents, videos, and selfies

hashtagPerform checks

hashtagIntegration guide

hashtagInstall the SDK

hashtagExample request

hashtagExample response

hashtagGenerate an SDK token

hashtagExample request

hashtagExample response

hashtagPrepare the stages

hashtagInitialize the SDK

hashtagPerform checks

hashtagExample request for a Document Check

hashtagRetrieve verification results

hashtagExample request

hashtagStages

hashtagWelcome

hashtagConsent

hashtagSelfie photo and video

hashtagDocument

hashtagNFC capture

hashtagPre-requisites

hashtagEnabling NFC capture

hashtagAddress capture

hashtagProof of address

hashtagCompletion

hashtagBranding

hashtagApplying your custom appearance

hashtagLocalization

hashtagResult handling

hashtagEvents tracking

hashtagToken expiry handling

Overview

Benefits

Requirements

Overview of flow

Create a client

Generate an SDK token

Initialize the SDK in your mobile app

Capture documents, videos, and selfies

Perform checks

Integration guide

Install the SDK

Example request

Example response

Generate an SDK token

Example request

Example response

Prepare the stages

Initialize the SDK

Perform checks

Example request for a Document Check

Retrieve verification results

Example request

Stages

Welcome

Consent

Selfie photo and video

Document

NFC capture

Pre-requisites

Enabling NFC capture

Address capture

Proof of address

Completion

Branding

Applying your custom appearance

Localization

Result handling

Events tracking

Token expiry handling