React Native

Alice Onboarding React Native SDK allows the automatic capture of documents and video selfie of the user in real time from the camera of your device. It also simplifies the communication with the onboarding API to facilitate rapid integration and development.

The Alice Onboarding React Native SDK is developed on top of native frameworks for both iOS and Android.

https://img.shields.io/npm/v/aliceonboarding-reactnative.svg?style=flat

See also

Check the our GitHub repo to be aware of our latest releases.

0. Requirements

1. Installation

1.1 General

Add the Alice Onboarding React Native Component:

yarn add aliceonboarding-reactnative

or just add the following code to your package.json

"aliceonboarding-reactnative": "{VERSION}",
                                    ^
                                    |_____ Set the version

Then, install it as usual:

yarn install

1.2 iOS

Our SDK is a dynamic framework. Therefore, before installation you will probably need to make some changes to your Podfile.

In your post_install, set the BUILD_LIBRARY_FOR_DISTRIBUTION flag to YES for both Alamofire and Yams.

post_install do |installer|
    installer.pods_project.targets.each do |target|
        if target.name == "Alamofire" || target.name ==  "Yams"
                target.build_configurations.each do |config|
                config.build_settings[‘BUILD_LIBRARY_FOR_DISTRIBUTION’] = ‘YES’
            end
        end
    end
end

1.2.1 Frameworks

If your app uses frameworks instead of static libraries (i.e. use_frameworks! at the beginning of your Podfile), please ensure that Flipper is disabled.

1.2.1 Static libraries

If your app uses static libraries (i.e. NO use_frameworks!), please add the following. In your pre_install, set AliceOnboarding and its dependencies as BuildType.dynamic_framework.

dynamic_frameworks = ['AliceOnboarding', 'Alamofire', 'Yams', 'Result', 'SwiftyJSON']
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if dynamic_frameworks.include?(pod.name)
      puts "Overriding the build_type to dynamic_framework for #{pod.name}"
      def pod.build_type;
        Pod::BuildType.dynamic_framework
      end
    end
  end
end

Finally, install the dependencies with cocoapods:

yarn cocoapods # equivalent to cd ios; pod install; cd ..

2. Integration

2.1. Setup

2.1.1. iOS Considerations

  • Add camera permission to your app. Find more info Here.

  • We strongly recommended to lock app orientation to portrait.

2.1.2. Android Considerations

  • Add the Alice Biometrics Artifactory repository and the packaging options to your build.gradle.

allprojects {
    repositories {
        mavenCentral{}
        maven {
            url  "https://alicebiometrics.jfrog.io/artifactory/alicebiometrics-maven-pro-local/"
        }
    }
}
android {
   packagingOptions {
     pickFirst '**/libc++_shared.so'
  }
}
  • The SDK requires at least API 21. So remember to set minSdkVersion = 21.

  • We strongly recommended to lock app orientation to portrait.

  • Add camera permision to your app and add AliceActivity.

  • Modify android/app/src/main/AndroidManifest.xml like this:

<manifest>
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera" />
    <uses-feature android:name="android.hardware.camera.autofocus" />

    <application
        <activity android:name="com.rnalice.AliceActivity" />
    </application>
</manifest>

2.2. Import the library

import Onboarding from 'aliceonboarding-reactnative';

2.3. To use NFC (only needed for android)

To make use of the NFC capture functionality on Android, you need to add the following package to your application’s dependencies.

implementation 'com.alicebiometrics.alicenfc:AliceNFC:{version}'
  • To know what version you have to use, take a look at our release notes and query in the version of ‘aliceonboarding-reactnative’ you are using

2.4. Onboarding modes

You can integrate the onboarding process in two different ways: using a pre-configured flow or creating a manual flow.

In the first case, you simply need to indicate to the SDK the flow you want: number and type of documents, order, etc. From this configuration, the SDK takes control and allows you to perform the entire onboarding process autonomously without having to worry about managing Alice Onboarding API calls. This is the fastest and easiest way to integrate AliceOnboarding in your application.

In the second case, no flow is specified. The onboarding process is completely free, allowing your application to manage the beginning and end of it, as well as the capture and upload of the different documents to the API. This case is indicated for an expert level of configuration, allowing you to split the onboarding process into different stages and add other tasks related to your customer flow (e.g. a form to be filled in by the user). If your interested in this mode, skip the following 2.4 and 2.5 sections and go to Onboarding Commands.

2.5. Config your Alice Onboarding

You can configure the Alice Onboarding flow with a simple dictionary:

const ONBOARDING_CONFIG = {
    "stages": [
        {"stage": "addSelfie"},
        {"stage": "addDocument", "type": "idcard"},
    ]
}

You can also specify the issuingCountry, otherwise user can select it with a menu.

const ONBOARDING_CONFIG = {
    "stages": [
        {"stage": "addSelfie"},
        {"stage": "addDocument", "type": "idcard", "issuingCountry": "ESP"},
    ]
}

2.5.1. Available Stages

  • addSelfie: It includes a standard selfie capturer.

  • addSelfieWithChallenge: It includes a selfie with a random document challenge.

  • addDocument: It includes a document capturer. Additionally, you need to configure the document type and the issuingCountry.
    • type (required): Available documents (idcard, driverlicense, passport, residencepermit).

    • issuingCountry (optional): ISO 3166-1 alpha-3 country code from those supported by Alice

  • addOtherTrustedDocument: It includes a other trusted document (OTD) capturer. An OTD is a document that is not necessarily for identification (e. g. proof of address, bill…). Additionally, you can configure two arguments:
    • title: a title for this section during the onboarding process.

    • category: this is required if your flow requires multiple documents. You must use this argument to tag each document, for example if your flow requires an invoice and a payslip you could use “invoice” and “payslip” as categories.

See also

Otherwise, if no issuingCountry is passed, it will be requested from the user via a pop-up menu.

Warning

Please note that the passport type does not require specification of issuingCountry.

2.6. Run Alice Onboarding

You can run our React Native module in your application in two ways: component or function.

import Onboarding from 'aliceonboarding-reactnative';

<Onboarding
    userToken={userToken}
    config={ONBOARDING_CONFIG}
    onSuccess={(result) => console.log("onSuccess:" + result) }
    onFailure={(error) => console.log("onFailure:" + error) }
    onCancel={(value) => console.log("onCancel:" + value) }
/>
import { runOnboarding } from 'aliceonboarding-reactnative';

runOnboarding(userToken, ONBOARDING_CONFIG , (result) => {
     Alert.alert("Result", result)
     console.log(result)
} , (error) => {
     Alert.alert("Error", error)
     console.log(error)
},  (cancel) => {
     Alert.alert("Cancel", cancel)
     console.log(cancel)
})

where:

  • userToken is used to secure requests made by the users on their mobile devices or web clients. You should obtain it from your backend (see Authentication).

  • result is a json with user status information, here you can find the user_id and information about a successful onboarding.

  • error is a json with information about an unexpected failure.

See also

Check our examples here

3. Authentication

  • How can we get the userToken to start testing Alice Onboarding technology?

AliceOnboarding can be used with two different authentication modes:

  • Trial test (Using Alice Onboarding Sandbox): Recommended only in the early stages of integration.
    • Pros: This mode does not need backend integration.

    • Cons: Security compromises. It must be used only for development and testing.

  • Production (Using your Backend): In a production deployment we strongly recommend to use your backend to obtain the required TOKENS.
    • Pros: Full security level. Only your backend is able todo critical operations.

    • Cons: Needs some integration in your backend.

3.1. Trial test

If you want to test the technology without integrate it with your backend, you can use our Sandbox Service. This service associates a user mail with the Alice Onboarding user_id. You can create a user and obtain his userToken already linked with the email.

Get the userToken with:

import { getUserTokenWithSandbox } from 'aliceonboarding-reactnative';

getUserTokenWithSandbox(trialToken, "email@example.com", (userToken) => {
     console.log(userToken);
}

Then run the onboarding with the userToken and the ONBOARDING_CONFIG:

import Onboarding from 'aliceonboarding-reactnative';

<Onboarding
    userToken={userToken}
    config={ONBOARDING_CONFIG}
    onSuccess={(result) => console.log("onSuccess:" + result) }
    onFailure={(error) => console.log("onFailure:" + error) }
    onCancel={(value) => console.log("onCancel:" + value) }
/>
import { runOnboarding } from 'aliceonboarding-reactnative';

runOnboarding(userToken, ONBOARDING_CONFIG , (result) => {
     console.log(result)
} , (error) => {
     console.log(error)
},  (cancel) => {
     console.log(cancel)
})

Where trialToken is a temporary token for testing the technology in a development/testing environment.

An email is required to associate it to an Alice Onboarding user_id. You can also add some additional information from your user as firstName and lastName.

Check our examples here

3.2. Production

On the other hand, for production environments we strongly recommend to use your backend to obtain the required USER_TOKEN.

<Onboarding
    userToken={this.getUserTokenFromMyBackend()}
    config={ONBOARDING_CONFIG}
    onSuccess={(result) => console.log("onSuccess:" + result) }
    onFailure={(error) => console.log("onFailure:" + error) }
    onCancel={(value) => console.log("onCancel:" + value) }
/>
import { runOnboarding } from 'aliceonboarding-reactnative';

runOnboarding(this.getUserTokenFromMyBackend(), ONBOARDING_CONFIG , (result) => {
     console.log(result)
} , (error) => {
     console.log(error)
},  (cancel) => {
     console.log(cancel)
})

4. Customisation

To improve the Onboarding experience into your look and feel, Alice Onboarding allows you to customise the onboarding stages using your own style.

4.1. iOS

iOS customization works overwriting static classes. The customization options are detailed in the native SDK customization doc.

Once you have defined the customization you want, create a class to overwrite the desired properties.

import Foundation
import AliceOnboarding

@objc public class CustomAppearanceExample: NSObject {
  public override init() {
    OnboardingAppearence.statusView.backgroundColor = UIColor.white
    OnboardingAppearence.iconsStyle = .shape
  }
}

Finally, you just need to init this class in your AppDelegate.

#import "AppDelegate.h"
#import "AppOnboardingSample-Swift.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Init custom appearance
  [[CustomAppearanceExample alloc] init];

  return YES;
}

You can check an example of appearance customization in our public react-native example app.

4.2. Android

The android appearance customization is explained in native SDK customization doc. Its implementation is equivalent.

5. Localisation

The Alice Onboarding SDK provides several default translations for some locales. By default, the SDK infers what is the default language to use. If locale does not exist, it uses English.

In addition, you can also provide custom translations (or different texts) to clarify whatever you want in your app.

5.1. iOS

The Alice Onboarding SDK provides several default translations for the following locales:

Locale

Code

Catalan

ca

German

de

English

en

Spanish

es

Basque

eu

French

fra

Italian

it

Galician

gl

Polish

pl

Portuguese

pt

Russian

ru

Turkish

tr

Simplified chinese

zh

If you want to rename some of the texts, you need to add an additional .strings file inside your resource folder for the required locale. Please remember the naming should follow the ISO 639-1 language codes. For example, in the case of Spanish (es), the file name should be es.strings.

Once your .strings file is defined, place it inside the .ios folder. Finally, add the desired localization to your ONBOARDING_CONFIG. Please note only one localization can be specified at the time, so your configured language should change depending or your app’s localization.

const ONBOARDING_CONFIG = {
    "localization": {"language": "es"},
    "stages": [
        {"stage": "addSelfie"},
        {"stage": "addDocument", "type": "idcard"},
    ]
}

You can check an example of text customization in our public react-native example app.

5.2. Android

The android text customization is explained in native SDK customization doc. Its implementation is equivalent.

6. Demo

Check our React-Native demo in Github.