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.

Tip

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

0. Requirements

• Package Manager: Use yarn or npm
• iOS specific:
  • CocoaPods

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://europe-west1-maven.pkg.dev/alice-cloud/maven" }
          maven { url "https://jitpack.io" }
      }
  }
  

  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 permission 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. 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.4.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 Supported documents
• addOtherTrustedDocument: It includes the 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.

Tip

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.5. Run Alice Onboarding

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

ComponentFunction

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.

Tip

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

• Production (Using your Backend): In a production deployment you must use your backend to obtain the required TOKENS.

  • Pros: Full security level. Only your backend is able to do 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:

ComponentFunction

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

ComponentFunction

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

To improve the Onboarding experience into your look and feel, Alice Onboarding allows you to customize 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 initialize 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. Localization

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
Arabic	ar
Catalan	ca
German	de
English	en
Spanish	es
Basque	eu
French	fra
Italian	it
Galician	gl
Japanese	ja
Dutch	nl
Polish	pl
Portuguese	pt
Russian	ru
Turkish	tr
Simplified Chinese	zh

If you want to rename some 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.