Financial Intelligence Engine:Customize the selfie guidance page for Real ID

Background

The Real ID flow includes a default selfie guidance page. You can replace it with a custom page to better suit your business needs.

Note: This topic covers customization for native app users. To customize the selfie guidance page for Web SDK users, see Development -> Mobile web(H5) -mode integration -> H5 integration -> customise the face guide url.

Overview

The following diagram shows the basic steps to customize the selfie guidance page in Real ID.

Steps

1. Develop the Web Page

1.1 Get ZolozRealIdCore library

Download the JavaScript file from here and add it to your project.

1.2 Import ZolozRealIdCore

import ZolozRealIdCore from './zoloz-realid-core';
const zolozRealIDCore = new ZolozRealIDCore(langPack);

1.3 Configure language pack

The optional langPack parameter customizes the alert text in popovers. It contains 9 keys for system error, network error, and retry limit alerts. The default values are as follows:

//default value
const langPack = {      
    system_error_title:"System Error",
    system_error_msg: 'Please try again later',
    system_error_got_it: 'Got it',
    network_error_title: 'No Internet Connection',
    network_error_msg: 'Please check your internet connection and try again',
    network_error_got_it: 'Got it',
    fe_retry_max_title: '',
    fe_retry_max_msg:'Sorry, you have too many failed identification attempts. Please try again later.',
    fe_retry_max_got_it:'Got it'
};

1.4 End the page

When the page needs to transition (for example, navigating to the next page or going back), call the following method to end the current page.

let response = await zolozRealIDCore.end(type,params);
//await zolozRealIDCore.end('next');

The type and params are defined by the server side.

Type: 'next' | 'back' | 'error' | 'fail' | 'skip' | 'cancel'; Usually we only need 'next' and 'back';

Sample for 'next':

const buttonClick = () => {
  // if params needed, please add it
  const params = {};
    core.end('next',params);
}

Sample for 'back':

document.addEventListener('back', e => {
  // please prevent the default back event and let the core to controll the flow.
  e.preventDefault();
  core.end('back');
}, false);

1.5 Configure logging

import {ekycLog} from './zoloz-realid-core';
ekycLog(seed,message);
//ekycLog('clickBack',{'onPage':'infoFill'});

This function sends remote logs and should be used in accordance with your BI requirements.

1.6 Sample code:

Sample project:

The code in App.vue:

<template>
    <div id="app">
        <div @click='takeSelfie'>
            Next Page
        </div>
    </div>
</template>

<script>
    import ZolozRealIdCore, {ekycLog} from '@/utils/zolozRealIdCore';

    export default {
        name: 'app',
        data() {
            return {
                enableNext: true,
                zolozRealIdCore: new ZolozRealIdCore({}),
            };
        },
        mounted() {
            ekycLog('faceGuidePageAppear', {});
            document.addEventListener('back', e => {
              e.preventDefault();
              ekycLog('clickButton', {
                'onPage': 'face_guide',
                'clickItem': 'back'
              });
              this.zolozRealIdCore.end('back');
            }, false);
        },
        methods: {
            async takeSelfie() {
              // protect code
              if(this.enableNext) {
                ekycLog('faceGuidePageProceed');
                this.enableNext = false;
                await this.zolozRealIdCore.end('next');
                this.enableNext = true;
              }
            }
        }
    }
</script>

<style>
</style

Note

1. If you encounter the error exports is not defined or *is not a constructor, this is because ZolozRealIdCore is a CommonJS module. Update your babel.config.js as follows:

module.exports = {
  presets: [
    [
      '@vue/app',
      {
        modules:'commonjs'
      }
    ]
  ]
}

2. Because the customized page is hosted in an iframe, you may encounter CORS or privilege issues when implementing complex functionality. A pure STATIC page is recommended.

Support Android 15 Edge-to-Edge

To support Android 15 Edge-to-Edge functionality, you need to add the following querySystemWindowInsets() function definition in your JavaScript code (this JavaScript API is only available on Android devices).

export function querySystemWindowInsets(){
  return new Promise((resolve)=>{
    ready(()=>{
      AlipayJSBridge.call('querySystemWindowInsets',{},(response)=>resolve(response));
    });
  });
}

Call querySystemWindowInsets() during page initialization to query the current device's insets. The return value example is as follows:

{
    "top": 128, 
    "bottom": 360, 
    "left": 0, 
    "right": 0}

Parameter Description:

• top: Top inset dimension (i.e., status bar height)

• bottom: Bottom inset dimension (i.e., navigation bar height)

• left: Left inset dimension

• right: Right inset dimension

2. Deploy the Web Page

Deploy the web page to any location that is accessible from the public network.

3. Set the Web Page

When you initialize Real ID on the server side, pass the URL as a parameter. The URL must use HTTPS:

{
    "bizId": "...",
    "userId": "...",
    "docType": "...",
    "pageConfig":{"urlFaceGuide":"https://url-to-the-customized-web-page.html"},
    "metaInfo": "..."
}

4. Use the Default Selfie Guidance Page (Optional)

When you initialize Real ID on the server side, you can use the default selfie guidance page, which supports English (en), Simplified Chinese (zh-CN), and Traditional Chinese (zh-HK). Pass the corresponding URL in pageConfig:

{
    "bizId": "...",
    "userId": "...",
    "docType": "...",
    "pageConfig":{"urlFaceGuide":"https://sg-production-cdn.zoloz.com/page/realid-lite-fe/faceGuide.html?locale=en"},
    "metaInfo": "..."
}

urlFaceGuide	Language
https://sg-production-cdn.zoloz.com/page/realid-lite-fe/faceGuide.html?locale=en	English
https://sg-production-cdn.zoloz.com/page/realid-lite-fe/faceGuide.html?locale=zh-CN	Simplified Chinese
https://sg-production-cdn.zoloz.com/page/realid-lite-fe/faceGuide.html?locale=zh-HK	Traditional Chinese

For more information, see the Real ID API documentation.