Incode Welcome SDK Usage

1. Initialize Welcome SDK

Add the following line of code to your class that extends the Application class.

@Override
public void onCreate() {
    super.onCreate();
    ...
    new IncodeWelcome.Builder(this, WELCOME_API_URL, WELCOME_API_KEY)
            .setSSLConfig(sslConfig) // optional SSL config for on-premise servers
            .setLoggingEnabled(loggingEnabled) // enable/disable logcat logs. logs are enabled by default
            .build();
    ...
}

WELCOME_API_URL and WELCOME_API_KEY will be provided to you by Incode.
Create an IncodeWelcome object using the Builder class and build() method.
Optionally specify SSL Config for your own on-premise servers.
Optionally disable logs.

Call the build() method to create the IncodeWelcome singleton object.
You can use the following API calls only after the SDK has been initialized using the build().

Review the API Javadocs for complete specification of IncodeWelcome.Builder and SSLConfig classes.

2. Create Session Configuration

You can optionally customize the onboarding session by creating custom SessionConfig. Use the following SessionConfig.Builder APIs to do so:

• setRegion: to change the region used for ID/document validation. Use 2 digit country code for specific country, or "EU" for document issued within Europe, or "ALL" for document issued by any country. Default value is "ALL". If provided country code isn't supported, default one is used.
• setConfigurationId: Specify flow id from the dashboard in order to use configurations applied to that flow. Note that you still have to add onboarding steps via FlowConfig in order to display onboarding flow to the user.
• setValidationModuleList: List of Onboarding Validation modules to be taken into account for user scoring and approval. By default it is id, liveness, faceRecognition
• setCustomFields: Provide a list of custom fields that will be stored for this session
• setInterviewId: ID of the onboarding session. Specify in order to resume existing onboarding session.
• setExternalToken: Token of the onboarding session. Specify in order to resume existing onboarding session.
• setExternalId: Id that is used outside of Incode Omni platform. If a session with the same externalId already exists, it will be resumed instead of creating a new one.
• setQueueName: When using video conference module specify the queue which the user will enter once the flow is completed. If none specifed, user goes to default queue.

SessionConfig sessionConfig = new SessionConfig.Builder()
        .addRegion("US")
        .build();

Resuming an existing session, e.g started API to API

SessionConfig sessionConfig = new SessionConfig.Builder()
        .setInterviewId(...);
        .build();

3. Create Welcome Flow Configuration

In your Activity class where you want to show the onboarding UI to your users, add the following code inside the onCreate method.

Firstly, you should create an FlowConfig object and add all the modules you want to use in your onboarding flow.
If you omit a module it won't be shown in the flow. Modules will be shown in the order you added them to the builder.
Please note that some modules are mandatory and there is an order dependency between some of them.
E.g. every onboarding flow needs to have a selfie scan and an ID scan.
Another example is results module that can not precede modules that add or process data.
If any of the rules is broken FlowConfig.Builder.build() throws ModuleConfigurationException.

FlowConfig flowConfig = new FlowConfig.Builder()
        .addPhone()
        .addIDScan(new IdScan.Builder().build())
        .addDocumentScan(new DocumentScan.Builder().build())
        .addGeolocation()
        .addSelfieScan(new SelfieScan.Builder().build())
        .addFaceMatch()
        .addUserConsent()
        .addSignature()
        .addCaptcha()
        .addVideoSelfie()
        .addConference()
        .build();

Some modules require you to pass an instance of module config, which can be obtained and customized using module's Builder class.
For example: new IdScan.Builder().build() for IdScan module.

Some modules show tutorials by default. These can be disabled by calling the Builder's method setShowTutorials(false).
Conference is an optional step.

Use addConference(queueName) to specify a queue to which customers will be added for Video Interview.
If this isn't set customer will go to default queue.
Use addConference(queueName, disableMicOnCallStart) if you want to enable microphone once the video call starts.
Microphone is disabled by default, so provide false if you wish to enable it.

Results can be fetched through REST API.
If you want to display results in the client you can add results module by calling addResults().
By calling addResults(IDResultsFetchMode.FAST) you can change the validation mode.
Default value is IDResultsFetchMode.ACCURATE.

You can also approve user's onboarding application directly from the client by adding approval module addApproval().
If you are not using face match module, you can use addApproval(true, true) to perform face match in approval module.
By calling addApproval(true, true, true) you can force an approval even if validation results were under the recommended thresholds.

To enable proof of address step in video selfie use addVideoSelfie(true).

Review the API Javadocs for complete specification of FlowConfig.

4. Create a callback to receive SDK results

OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onOnboardingSessionCreated(String token, String interviewId, String region) {
        // Onboarding Session Created successfully
    }

    @Override
    public void onIntroCompleted() {
        // Intro screen completed
    }

    @Override
    public void onAddPhoneCompleted(PhoneNumberResult phoneNumberResult) {
        // Add phone completed
    }

    @Override
    public void onQRScanCompleted(QRScanResult qrScanResult) {
        // QR scan completed
    }

    @Override
    public void onIdValidationCompleted(IdValidationResult idValidationResult) {
        // ID Validation completed
    }

    @Override
    public void onPassportValidationCompleted(IdValidationResult validationResult) {
        // Passport validation completed
    }

    @Override
    public void onDocumentValidationCompleted(DocumentType documentType, DocumentValidationResult result) {
        // Document validation completed
    }

    @Override
    public void onSelfieScanCompleted(SelfieScanResult selfieScanResult) {
        // Selfie scan completed
    }

    @Override
    public void onFaceMatchCompleted(FaceMatchResult faceMatchResult) {
        // Face match completed
    }

    @Override
    public void onSignatureCollected(SignatureFormResult signatureFormResult) {
        // Signature collected
    }

    @Override
    public void onUserConsentCompleted() {
        // User consent complete
    }

    @Override
    public void onVideoRecorded() {
        // Video selfie finished successfully
    }

    @Override
    public void onCaptchaCollected(CaptchaResult captchaResult) {
        // Captcha collected
    }

    @Override
    public void onGeolocationFetched(GeolocationResult geolocationResult) {
        // Geolocation collected
    }

    @Override
    public void onApproveCompleted(boolean success) {
        // User's onboarding approval completed
    }

    @Override
    public void onResultsShown(UserScoreResult userScoreResult) {
        // Results shown to the user
    }

    @Override
    public void onQueuePositionChanged(int newQueuePosition) {
        // Queue position for the video call changed
    }

    @Override
    public void onEstimatedWaitingTime(int waitingTimeInSeconds) {
        // Called only once with the estimated waiting time in the queue. Waiting time is in seconds.
    }

    public void onConferenceEnded() {
        // Called when the video conference has ended
    }

    @Override
    public void onSuccess() {
        // User successfully finished whole onboarding flow
    }

    @Override
    public void onError(Throwable error) {
        // Onboarding flow was aborted due to error
    }

    @Override
    public void onUserCancelled() {
        // User cancelled the flow
    }
};

5. Create Common Configuration

You can optionally customize certain tresholds or specific UX behaviors by creating custom CommonConfig. Use the following CommonConfig.Builder APIs to do so:

• setShowCloseButton: to show/hide close button in all screens. Close button is hidden by default.
• setShowExitConfirmation: to show/hide a dialog where user needs to confirm that he wants to leave the flow after back button. Dialog is shown by default.
• setRecognitionThreshold to override the default face recognition threshold.
• setSpoofThreshold: to override the default liveness threshold.
• setMaskThreshold: to override the default mask check threshold.
• setIdGlareThreshold: to override the default glare threshold when capturing ID photo.
• setIdBlurThreshold: to override the default blur threshold when capturing ID photo.

Note that only on-device thresholds get overridden by calling APIs from above.

CommonConfig commonConfig = new CommonConfig.Builder()
        .setShowExitConfirmation(...)
        .setShowCloseButton(...)
        .setIdGlareThreshold(...)
        .setIdBlurThreshold(...)
        .build();

IncodeWelcome.getInstance().setCommonConfig(commonConfig);

6. Start the onboarding process

Once created SessionConfig (use null for using default session configs), FlowConfig, and OnboardingListener objects, initialize your session by calling startOnboarding() like following.

IncodeWelcome.getInstance().startOnboarding(this, sessionConfig, flowConfig, onboardingListener);

Review the API Javadocs for complete specification of startOnboarding method and OnboardingListener interface.

Emulator support

Emulator support provides dummy processing implementation for all modules that use camera for scanning, or depend heavily on photos taken by the camera:
ID scan, Selfie Scan, Face Match, Document Scan and Video Selfie.

Application shows black screen in place of camera, and after 2 seconds module finishes automatically with a specific code:
Selfie Scan, Face Match, Document Scan and Video Selfie: ResultCode.EMULATOR_DETECTED as resultCode
ID Scan: IdValidationResult.RESULT_EMULATOR_DETECTED as frontIdResult and backIdResult.

Make sure to remove setTestModeEnabled(true) before building the application for production!

Advanced Usage

If you would like to use SDK in a way that the default flow builder doesn't provide,
you can use SDK APIs for advanced usage where you'll be able to fully customize the experience of the flow,
ie. by calling individual SDK modules, or grouping SDK modules in sections, and returning control to your host application in between.

Create new onboarding session

Before calling any other Onboarding SDK components it is necessary to create a new onboarding session.

SessionConfig sessionConfig = new SessionConfig.Builder().build();

IncodeWelcome.getInstance().setupOnboardingSession(
        sessionConfig,
        new OnboardingSessionListener() {
            @Override
            public void onOnboardingSessionCreated(String token, String interviewId, String region) {
                // Onboarding Session Created successfully
            }

            @Override
            public void onError(Throwable error) {
            }

            @Override
            public void onUserCancelled() {
            }
        });

Optionally, you can specify a list of OnboardingValidationModule items.
This list determines which modules are used for verification and calculation of the onboarding score.
If you pass null as validationModuleList, the default values will be used: id, faceRecognition and liveness.

List<OnboardingValidationModule> validationModuleList = new ArrayList<>();
validationModuleList.add(OnboardingValidationModule.id);
validationModuleList.add(OnboardingValidationModule.secondId);
validationModuleList.add(OnboardingValidationModule.faceRecognition);
validationModuleList.add(OnboardingValidationModule.liveness);
validationModuleList.add(OnboardingValidationModule.faceRecognitionSecondId);
validationModuleList.add(OnboardingValidationModule.governmentValidation);
validationModuleList.add(OnboardingValidationModule.governmentOcrValidation);
validationModuleList.add(OnboardingValidationModule.governmentFaceValidation);
validationModuleList.add(OnboardingValidationModule.videoSelfie);
validationModuleList.add(OnboardingValidationModule.faceMask);

SessionConfig sessionConfig = new SessionConfig.Builder()
        ...
        .setValidationModuleList(validationModuleList)
        .build();

It is also possible to determine Validation Modules based on a specific Web Flow, by passing a Flow Configuration ID.

Split Onboarding SDK flow into sections

Once the new onboarding session is created (See previous section), you can separate Onboarding SDK flow into multiple sections based on your needs.

Make sure to call setFlowTag(String) for each section.

Make sure to call IncodeWelcome.getInstance().finishOnboarding() at the end of the flow,
but before CONFERENCE or RESULTS modules.

Create Onboarding Section

// Create section
FlowConfig FlowConfig = new FlowConfig.Builder()
        .setFlowTag("section 1") // Make sure to tag your flow section
        .addIntro()
        .addPhone()
        .addIDScan()
        .build();

// Start section
IncodeWelcome.getInstance().startOnboardingSection(OnboardingActivity.this,
        flowConfig,
        onboardingListener);

// Call when all finished
IncodeWelcome.getInstance().finishOnboarding(OnboardingActivity.this, null);

Important: Receive "Section Complete" Callback

OnboardingListener contains a callback for Onboarding Section Completed event onOnboardingSectionCompleted().
If you need to start another section from within the listener, make sure to only do that in onOnboardingSectionCompleted() method.

@Override
public void onOnboardingSectionCompleted(String flowTag) {
    ...
    startNextSection() // This will not work properly in module callback methods (example: `onIdFrontCompleted()`)
    // Use `onOnboardingSectionCompleted()` if you need to start other sections from the Listener
}

@Override
public void startNextSection() {
    FlowConfig nextFlowConfig = new FlowConfig.Builder()
        .setFlowTag("NEXT_SECTION_FLOW_TAG")
        // add modules
        ...
        .build();

    IncodeWelcome.getInstance().startOnboardingSection(OnboardingActivity.this,
        nextFlowConfig,
        onboardingListener);
}

Important: Call finishOnboarding() when you're done

If you are calling individual SDK modules, or using flow sections (split-flow),
make sure to call IncodeWelcome.getInstance().finishOnboarding() to mark the end of the flow and close the session on server.
If you are using CONFERENCE or RESULTS modules, call finishOnboarding() first.

Resuming an existing onboarding session

To continue an existing onboarding when app was uninstalled and installed again in the middle of the flow, make sure to call setupOnboardingSession API.
It's important to call it prior to making any other API calls in order to reset the configuration that got lost on uninstall.
Create a SessionConfig instance to set the existing interviewId.
Optionally, set the validationModuleList as well.

List<OnboardingValidationModule> validationModuleList = new ArrayList<>();
validationModuleList.add(OnboardingValidationModule.id);
validationModuleList.add(OnboardingValidationModule.faceRecognition);
validationModuleList.add(OnboardingValidationModule.liveness);
validationModuleList.add(OnboardingValidationModule.governmentValidation);

SessionConfig sessionConfig = new SessionConfig.Builder()
        .setInterviewId(interviewId) // Set interviewId
        .setValidationModuleList(validationModuleList) // Set validationModuleList (optional)
        .build();

IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, new OnboardingSessionListener() {
    @Override
    public void onOnboardingSessionCreated(String token, String interviewId, String region) {
        // it's safe to call individual APIs again
    }
    @Override
    public void onError(Throwable throwable) {
    }
    @Override
    public void onUserCancelled() {
    }
});

Non-UI APIs

Optionally, you can use specific set of modules without showing Incode's UI. Currently supported modules are: FaceMatch and Geolocation.

IncodeWelcome.getInstance().faceMatch(String interviewId, IdCategory idCategory, @NonNull FaceMatchListener faceMatchListener)

IncodeWelcome.getInstance().geolocation(@NonNull Context context, @Nullable String interviewId, @NonNull GeolocationListener geolocationListener)

Results are delivered via specific callbacks. Please note that there is no need to add a module to the flow or section configuration if you are using the non-UI variant.

Init SDK with External Token (no apiKey approach)

You can initialize the SDK with an external token instead of using the apiKey.

Steps to follow:

• 1: Initialize SDK with IncodeWelcome.Builder($CONTEXT, $WELCOME_API_URL)
• 2: Create SessionConfig object with external token, and OnboardingListener object, then call setupOnboardingSession() (how to create a session config, how to create a listener).
• 3: Create FlowConfig object (how to create a flow config). After onOnboardingSessionCreated() is called, call startOnboardingSection() to start the flow (use the listener created in the previous step).

Java

Step 1:

new IncodeWelcome.Builder($CONTEXT, $WELCOME_API_URL)
        // additional config
        .build();

Step 2:

SessionConfig sessionConfig = new SessionConfig.Builder()
        .setExternalToken($EXTERNAL_TOKEN) // add external token here
        .build();

IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, $LISTENER);

Step 3:

@Override
public void onOnboardingSessionCreated(String token, String interviewId, String region) {
    // create your flow config
    FlowConfig flowConfig = null;
    try {
        flowConfig = new FlowConfig.Builder()
            .setFlowTag("My Flow")
            .addGeolocation()
            .addPhone()
            .build();

    } catch (ModuleConfigurationException e) {
        e.printStackTrace();
    }

    IncodeWelcome.getInstance().startOnboardingSection($CONTEXT, flowConfig, $LISTENER);
}

Kotlin

Step 1:

IncodeWelcome.Builder($CONTEXT, $WELCOME_API_URL)
        // additional config
        .build()

Step 2:

val sessionConfig = SessionConfig.Builder()
        .setExternalToken($EXTERNAL_TOKEN) // add external token here
        .build()

IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, $LISTENER)

Step 3:

override fun onOnboardingSessionCreated(token: String, interviewId: String, region: String) {
    var flowConfig: FlowConfig? = null
    try {
        // create your flow config
        flowConfig = FlowConfig.Builder()
                .setFlowTag("My Flow")
                .addGeolocation()
                .addPhone()
                .build()
    } catch (e: ModuleConfigurationException) {
        e.printStackTrace()
    }

    IncodeWelcome.getInstance().startOnboardingSection($CONTEXT, flowConfig, $LISTENER)
}