Skip to main content

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. These 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 Javadoc 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:

  • setRegionIsoCode: to change the region used for ID/document validation. Use a 2-digit country code for a specific country, e.g. "EU" for a document issued within Europe, or "ALL" for documents issued by any country. The default value is "ALL". If the provided country code isn't supported, the default code 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()
        .setRegionIsoCode("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:

FlowConfig flowConfig = new FlowConfig.Builder()
        .addPhone()
        .addID(new IdScan.Builder()
            .setIdType(IdScan.IdType.ID)
            .setShowIdTutorials(true)
            .setWaitForTutorials(true)
            .build())
        .addDocumentScan(new DocumentScan.Builder().build())
        .addGeolocation()
        .addSelfieScan(new SelfieScan.Builder().build())
        .addFaceMatch()
        .addUserConsent(new UserConsent.Builder().build())
        .addSignature()
        .addCaptcha()
        .addVideoSelfie()
        .addConference()
        .build();

Let's take a look at what this code does. First, we are creating an FlowConfig object and adding all the modules we want to use in our onboarding flow. If a module is omitted it won't be shown in the flow. Modules will be shown in the order they are added 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 the results module cannot precede modules that add or process data. If any of the rules are broken FlowConfig.Builder.build() throws ModuleConfigurationException.

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

Some modules show tutorials by default. These can be disabled by calling the Builder's setShowTutorials(boolean) method and passing false as an argument.

Conference is an optional step.

Use addConference(disableMicOnCallStart) if you want to enable the microphone once the video call starts.
The microphone is disabled by default, so provide false if you wish to enable it.

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

The getUserScore() SDK API can also be used to fetch results. This SDK API doesn't show any UI if you only need the data.

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

To enable the proof of address step in video selfie, use addVideoSelfie(VideoSelfie.Build().setDocumentScanEnabled(true).build()).

Review the API Javadoc 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 onIdFrontCompleted(@NonNull IdScanResult frontIdScanResult) {
        // Scanning the front of an ID completed
    }

    @Override
    public void onIdBackCompleted(@NonNull IdScanResult backIdScanResult) {
        // Scanning the back of an ID completed
    }

    @Override
    public void onIdProcessed(IdProcessResult idProcessResult) {
        // ID Validation completed
    }

    @Override
    public void onNfcScanCompleted(@NonNull NfcScanResult nfcScanResult) {
        // NFC scan 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(VideoSelfieResult videoSelfieResult) {
        // Video selfie finished successfully
    }

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

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

    @Override
    public void onApproveCompleted(ApproveResult approveResult) {
        // 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
    }
};

Important: Call deleteUserLocalData() when you're done​

Because Incode SDK has multiple ways to exit the flow, make sure to call IncodeWelcome.getInstance().deleteUserLocalData() to delete all the local user data generated during the flow when you are done.

It is recommended to call deleteUserLocalData() in the following callbacks:

public void onSuccess()
public void onError(Throwable error)
public void onUserCancelled()

5. Create Common Configuration​

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

  • setShowCloseButton: to show/hide the close button in all screens. The 'Close' button is hidden by default.
  • setShowExitConfirmation: to show/hide a dialog where the user needs to confirm that he wants to leave the flow after pressing the back button. Dialog is shown by default.
  • setIdAutoCaptureTimeout to override the default auto-capture timeout in ID scan. Supported in capture-only mode. Not applied in enroll mode.
  • setSelfieAutoCaptureTimeout: to override the default auto-capture timeout in Selfie scan. Supported in capture-only and login mode. Not applied in enroll mode.

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

CommonConfig commonConfig = new CommonConfig.Builder()
        .setShowCloseButton(...)
        .setShowExitConfirmation(...)
        .setIdAutoCaptureTimeout(...)
        .setSelfieAutoCaptureTimeout(...)
        .build();

IncodeWelcome.getInstance().setCommonConfig(commonConfig);

6. Start the onboarding process​

Once the SessionConfig, FlowConfig, and OnboardingListener objects are created, initialize your session by calling startOnboarding() like this:

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

Review the API Javadoc for complete specification of the startOnboarding() method and OnboardingListener interface.

Emulator support​

Emulator support provides a dummy processing implementation for all modules that use the camera for scanning, or depend heavily on photos taken by the camera:

ID scan, Selfie Scan, Face Match, Document Scan and Video Selfie.

The application shows a black screen in place of the camera. After 2 seconds, the module finishes automatically with a specific code:

  • Selfie Scan, Face Match, Document Scan and Video Selfie: ResultCode.EMULATOR_DETECTED as resultCode
  • ID Scan: IdResults.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 the SDK in a way that the default flow builder doesn't provide, you can use the SDK APIs for advanced usage. In this way, you'll be able to fully customize the experience of the flow by calling individual SDK modules or grouping SDK modules in sections and returning control to your host application in between.

Simple vs Advanced usage

1. Create new onboarding session​

Before calling any other Onboarding SDK components, it is necessary to create a new onboarding session using the following code:

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

2. Split Onboarding SDK flow into sections​

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

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

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

It is recommended to call deleteUserLocalData() after calling finishOnboarding() to delete local user data.

3. Create Onboarding Section​

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

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

// Call when all finished
IncodeWelcome.getInstance().finishOnboarding(activityContext, new FinishOnboardingListener() {
    @Override
    public void onOnboardingFinished() {
        IncodeWelcome.getInstance().deleteUserLocalData(); // recommended to delete local user data at this point
    }
    ...
});

Things to Remember

Important: Receive "Section Complete" Callback​

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

@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 onIdFrontCompleted(IdScanResult frontIdScanResult) {
    ...
    // startNextSection(); // DON'T DO THIS HERE! Do it in `onOnboardingSectionCompleted()` instead!
}

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

    IncodeWelcome.getInstance().startOnboardingSection(
        activityContext,
        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 the app was uninstalled and reinstalled 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 in the uninstall.
Create a SessionConfig instance to set the existing interviewId.
Optionally, set the validationModuleList as well. Refer to the following:

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() {
    }
});

Other Usages

Non-UI APIs​

Optionally, you can use a specific set of modules without showing Incode's UI.

IncodeWelcome.getInstance().faceMatch(@Nullable String interviewId, @Nullable IdCategory idCategory, @NonNull FaceMatchListener faceMatchListener)
IncodeWelcome.getInstance().geolocation(@NonNull Context context, @Nullable String interviewId, @NonNull GeolocationListener geolocationListener)
IncodeWelcome.getInstance().processId(@Nullable String interviewId, @Nullable IdCategory idCategory, @NonNull IdProcessListener idProcessListener)
IncodeWelcome.getInstance().processLaborHistory(@Nullable String interviewId, @NonNull String curp, @NonNull ProcessLaborHistoryListener laborHistoryListener)
IncodeWelcome.getInstance().processPaymentProof(@Nullable String interviewId, @NonNull ProcessPaymentProofListener processPaymentProofListener)
IncodeWelcome.getInstance().getPaymentProofInfo(@Nullable String interviewId, @NonNull PaymentProofInfoListener getPaymentProofInfoListener)
IncodeWelcome.getInstance().getUserScore(@NonNull IDResultsFetchMode idResultsFetchMode, @Nullable String interviewId, @NonNull GetUserScoreListener getUserScoreListener)

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.

To do this, see the following code:

1: Initialize SDK with IncodeWelcome.Builder($CONTEXT, $WELCOME_API_URL) like this:

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

2: Create a SessionConfig object with external token, and OnboardingListener object, then call setupOnboardingSession() (how to create a session config, how to create a listener). Here is how we can do that:

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

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

3: Create a 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). Refer to the following code:

@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(activityContext, flowConfig, $LISTENER);
}

Submit-Only Mode​

  • You can initialize the SDK in 'Submit-Only Mode' to prevent access to any PII (Personal Identifiable Information).
  • You need to use a special apiKey to create a limited token without read permission.
  • You have access to a limited amount of callbacks when using this mode.

Available Callbacks in 'Submit-Only Mode'​

You have access to only these 6 callbacks in 'Submit-Only Mode':

OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onSuccess() {
        ...
    }

    @Override
    public void onError(Throwable throwable) {
        ...
    }

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

    @Override
    public void onOnboardingSectionCompleted(String flowTag) {
        ...
    }

    @Override
    public void onEvent(@NonNull Event event, @Nullable HashMap<String, Object> eventData) {
        ...
    }

    @Override
    public void onOnboardingSessionCreated(String token, String interviewId, String region) {
        // token, interviewId & region always contain null
        // start split flow here
        ...
    }

Simple Usage​

Step 1: Initialize IncodeWelcome SDK with SPECIAL_API_KEY:

@Override
public void onCreate() {
    super.onCreate();
    ...
    // API_URL and SPECIAL_API_KEY will be provided by Incode
    new IncodeWelcome.Builder(CONTEXT, $API_URL, $SPECIAL_API_KEY)
            // additional config
            .build();
    ...
}

Step 2: Set Submit-Only Mode by using setSdkMode(SUBMIT_ONLY):

IncodeWelcome.getInstance().setSdkMode(SdkMode.SUBMIT_ONLY);

Step 3: Follow these steps and finally call startOnboarding(...) (or setupOnboardingSession(...) if you need the split API):

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

// or
IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, onboardingListener);

Usage with External Token​

Alternatively, you can use an external token init + 'Submit-Only Mode':

Step 1: Initialize IncodeWelcome SDK without SPECIAL_API_KEY:

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

Step 2: Set Submit-Only Mode by using setSdkMode(SUBMIT_ONLY):

IncodeWelcome.getInstance().setSdkMode(SdkMode.SUBMIT_ONLY);

Step 3: Set external token with setExternalToken() in the SessionConfig:

SessionConfig sessionConfig = new SessionConfig.Builder()
        // LIMITED_EXTERNAL_TOKEN should be created outside using the SPECIAL_API_KEY
        .setExternalToken($LIMITED_EXTERNAL_TOKEN)
        .build();

Step 4: Follow these steps and finally call startOnboarding(...) (or setupOnboardingSession(...) if you need the split API):

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

// or
IncodeWelcome.getInstance().setupOnboardingSession(sessionConfig, onboardingListener);