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 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 OnboardingConfigV2 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 OnboardingConfigV2.build() throws ModuleConfigurationException.

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

Add setRegion(String regionIsoCode) call to change the region used for ID/document validation.
Use 2 digit country code for specific country, or "EU" for document issued withing Europe, or "ALL" for document issued by any country.
Default value is "ALL". If provided country code isn't supported default one is used.

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

3. Create a callback to receive SDK results

OnboardingListenerV2 onboardingListenerV2 = new IncodeWelcome.OnboardingListenerV2() {
    @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
    }
};

4. Start the onboarding process

IncodeWelcome.getInstance().startOnboardingV2(this, onboardingConfigV2, onboardingListenerV2);

Review the API Javadocs for complete specification of startOnboarding method and OnboardingListenerV2 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.

OnboardingConfigV2 onboardingConfigV2;
try {
    onboardingConfigV2 = new OnboardingConfigV2.OnboardingConfigBuilderV2().build();

    IncodeWelcome.getInstance().createNewOnboardingSession(
            onboardingConfigV2,
            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() {
                }
            });
} catch (ModuleConfigurationException e) {
    e.printStackTrace();
}

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);

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
OnboardingFlowConfig onboardingFlowConfig = new OnboardingFlowConfig.Builder()
        .setFlowTag("section 1") // Make sure to tag your flow section
        .addIntro()
        .addPhone()
        .addIDScan()
        .build();

// Start section
IncodeWelcome.getInstance().startOnboardingSection(OnboardingActivity.this,
        interviewId,
        onboardingFlowConfig,
        onboardingListenerV2);

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

Important: Receive "Section Complete" Callback

OnboardingListenerV2 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) {
    ...
    // This will not work properly in module callback methods (example: `onIdFrontCompleted()`)
    // Use `onOnboardingSectionCompleted()` if you need to start other sections from the Listener
    startNextSection()
}

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

    // remember to use the same interviewId & onboardingListenerV2 across all sections
    IncodeWelcome.getInstance().startOnboardingSection(OnboardingActivity.this,
        interviewId,
        nextFlowConfig,
        onboardingListenerV2);
}

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 is uninstalled and installed again in the middle of the flow make sure to call setOnboardingSession 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.

List<OnboardingValidationModule> validationModuleList = new ArrayList<>();
validationModuleList.add(OnboardingValidationModule.id);
validationModuleList.add(OnboardingValidationModule.faceRecognition);
validationModuleList.add(OnboardingValidationModule.liveness);
validationModuleList.add(OnboardingValidationModule.governmentValidation);
try {
    OnboardingConfigV2 onboardingConfig = new OnboardingConfigV2.OnboardingConfigBuilderV2()
            .setInterviewId(interviewId) // Set interviewId
            .build();
    IncodeWelcome.getInstance().setOnboardingSession(onboardingConfig, validationModuleList, 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() {
        }
    });
} catch (ModuleConfigurationException e) {
}

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 OnboardingConfigV2 object with external token & OnboardingListenerV2 object, then call setOnboardingSession() (how to create a config, how to create a listener).
• 3: After callback onOnboardingSessionCreated() is called, call startOnboardingSection() to start the flow (as parameters, create a new flow config & the listener created in the previous step).

Java

Step 1:

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

Step 2:

OnboardingConfigV2 initConfig = null;
try {
    initConfig = new OnboardingConfigV2.OnboardingConfigBuilderV2()
    // add external token here
    .setExternalToken($PLACE_EXTERNAL_TOKEN)
    .build();
} catch (ModuleConfigurationException e) {
    e.printStackTrace();
}

IncodeWelcome.getInstance().setOnboardingSession(initConfig, $LISTENER);

Step 3:

@Override
public void onOnboardingSessionCreated(String token, String interviewId, String region) {
    // create your flow config
    OnboardingConfigV2 flowConfig = null;
    try {
        val flowConfig = new OnboardingConfigV2.OnboardingConfigBuilderV2()
            .setFlowTag("My Flow")
            .addGeolocation()
            .addPhone()
            .build();
    
    } catch (ModuleConfigurationException e) {
        e.printStackTrace();
    }
    // pass empty string ("") for interviewId parameter
    IncodeWelcome.getInstance().startOnboardingSection($CONTEXT, "", flowConfig, $LISTENER);
}

Kotlin

Step 1:

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

Step 2:

var initConfig: OnboardingConfigV2? = null
try {
    initConfig = OnboardingConfigBuilderV2()
        // add external token here
        .setExternalToken($PLACE_EXTERNAL_TOKEN)
        .build()
} catch (e: ModuleConfigurationException) {
    e.printStackTrace()
}

IncodeWelcome.getInstance().setOnboardingSession(initConfig, $LISTENER)

Step 3:

override fun onOnboardingSessionCreated(token: String, interviewId: String, region: String) {
    var flowConfig: OnboardingConfigV2? = null
    try {
        // create your flow config
        flowConfig = OnboardingConfigBuilderV2()
            .setFlowTag("My Flow")
            .addGeolocation()
            .addPhone()
            .build()
    } catch (e: ModuleConfigurationException) {
        e.printStackTrace()
    }
    // pass empty string ("") for interviewId parameter
    IncodeWelcome.getInstance().startOnboardingSection($CONTEXT, "", flowConfig, $LISTENER)
}