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

  • Package Manager: Use yarn or npm

  • React-Native

  • iOS specific:
    • Cocoapods

    • All versions of iOS are supported since iOS 11.0 (Swift 5.0)

  • Android specific:
    • All versions of Android are supported since Android 5.0 (LOLLIPOP).

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

  • 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

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

Check the native SDKs docs to a rapid customisation both in Android and iOS.

5. Localisation

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.

Please check the native SDKs localisation docs both in Android and iOS.

6. Demo

Check our React-Native demo in Github.