ZOLOZZOLOZDOCS

      Client-mode Product Integration

      #TheMobile Client SDK

      We provide a mobile client SDK, which needs to be integrated into merchant's APP. And the SDK is available for both Android and iOS.


      SDK Requirements

      • Minimum OS version supported: Android 4.3+, iOS 8+.
      • Permissions required: network and camera.



      #Integration Overview

      image.png


      All client-mode products involve 4 anticipants:

      • The merchant's server
      • The merchant's mobile application
      • ZOLOZ SaaS service
      • ZOLOZ mobile client SDK


      The customer must fully understand the whole interaction sequence before any integration attempt.


      #Overall Sequence

      Client-mode Product Integration


      #Detailed Steps

      1. Start business. A user starts the process (e.g. eKYC process) by requesting the mobile app.
      2. Get meta info. The mobile app asks ZOLOZ client SDK for meta info such as device model and operation system version as the preparation step.
      3. Return meta info. ZOLOZ SDK returns meta info to the mobile app.
      4. Initialize transaction. The mobile app sends initialization request to the merchant server together with the meta info retrieved from ZOLOZ SDK.
      5. Initialize transaction. The merchant server calls ZOLOZ SaaS service to initialize the transaction of the product (such as RealId) and passes along meta info.
      6. Return initialize result and client config. ZOLOZ SaaS service completes transaction initialization and returns result as well as corresponding client configuration prepared for ZOLOZ SDK to the merchant server.
      7. Return initialize result and client config. The merchant server returns the initialization result and client configuration to mobile app.
      8. Invoke with client config. The mobile app invokes ZOLOZ SDK with client configuration.
      9. Capture user data and upload. ZOLOZ SDK starts to interact with the end-user, capture required data and then upload. There might be multiple rounds of interaction between ZOLOZ SDK and ZOLOZ server.
      10. Process complete. The process is completed and ZOLOZ server returns the process status to ZOLOZ SDK.
      11. Inform completion with status. ZOLOZ SDK informs the completion of the process to the mobile app.
      12. Inform completion. The mobile app informs the merchant server about the process completion.
      13. Check transaction details. The merchant server asks ZOLOZ SaaS service for transaction details.
      14. Return transaction details. ZOLOZ server returns details to the merchant server.
      15. Confirmed. The information from the mobile app is confirmed by the merchant server.
      16. Inform completion. The mobile app tells user that the process is completed.


      #Server-side Integration

      The merchant's server need to provide proper endpoint for the merchant application to create a transaction, as well as fetch the final result of transaction. The request from the merchant application could be simply forwarded to ZOLOZ SaaS APIs.


      Similar with integrating APIs of server-mode products, ZOLOL API SDK helps a lot by easing the gateway protocol implementation. In this document we only demonstrate how to integrate with ZOLOZ API SDK. 


      #Instantiate and Configure API SDK Client

      copy
      // initialize OpenApiClient
      String clientId = "<Client ID>";
      String zolozPublicKey = "<ZOLOZ's public key content encoded in base64>";
      String merchantPrivateKey = "<The merchant's private key content encoded in base64>";
      
      OpenApiClient client = new OpenApiClient();  // construct with signature and encryption by default
      client.setHostUrl("https://sg-production-api.zoloz.com");
      client.setClientId(clientId);
      client.setMerchantPrivateKey(merchantPrivateKey);
      client.setOpenApiPublicKey(zolozPublicKey);
      //client.setSigned(false);     // signature (of response) validation can be turned off
      //client.setEncrypted(false);  // encryption can be turned off


      #Expose Endpoint for Client Application

      copy
      @RestController
      @RequestMapping(value = {"/webapi"})
      public class NativeClientModeController {
      
          private static final Logger logger = LoggerFactory.getLogger(NativeClientModeController.class);
      
          @Autowired
          private OpenApiClient openApiClient;
      
          @RequestMapping(value = {"/realid/initialize"}, method = RequestMethod.POST)
          public JSONObject realIdInit(@RequestBody JSONObject request) {
      
              logger.info("request=" + request);
      
              String metaInfo = request.getString("metaInfo");
              String businessId = "dummy_bizid_" + System.currentTimeMillis();
              String userId = "dummy_userid_" + System.currentTimeMillis();
      
              JSONObject apiReq = new JSONObject();
              apiReq.put("bizId", businessId);
              apiReq.put("flowType", "REALIDLITE_KYC");
              apiReq.put("docType", "00000001003");
              apiReq.put("pages", "1");
              apiReq.put("metaInfo", metaInfo);
              apiReq.put("userId", userId);
      
              String apiRespStr = openApiClient.callOpenApi(
                      "v1.zoloz.realid.initialize",
                      JSON.toJSONString(apiReq)
              );
      
              JSONObject apiResp = JSON.parseObject(apiRespStr);
      
              JSONObject response = new JSONObject(apiResp);
              response.put("rsaPubKey", openApiClient.getOpenApiPublicKey());
              response.put("transactionId", apiResp.getString("transactionId"));
              response.put("clientCfg", apiResp.getString("clientCfg"));
              logger.info("response=" + apiRespStr);
      
              return response;
          }
      
          @RequestMapping(value = "/realid/checkresult", method = RequestMethod.POST)
          public JSONObject realIdCheck(@RequestBody JSONObject request) {
      
              logger.info("request=" + request);
      
              String businessId = "dummy_bizid_" + System.currentTimeMillis();
              String transactionId = request.getString("transactionId");
      
              JSONObject apiReq = new JSONObject();
              apiReq.put("bizId", businessId);
              apiReq.put("transactionId", transactionId);
      
              String apiRespStr = openApiClient.callOpenApi(
                      "v1.zoloz.realid.checkresult",
                      JSON.toJSONString(apiReq)
              );
      
              JSONObject apiResp = JSON.parseObject(apiRespStr);
      
              JSONObject response = new JSONObject(apiResp);
              return response;
          }
      }
      


      #Example of Minimum Server

      #Build Examples

      Prequisites

      • JDK 1.8
      • Maven >3.2.5


      The examples are also included in the API SDK project, to build the project, simply execute following command from the root directory of the API SDK project:

      copy
      mvn package


      #Launch Business Server

      Prequisite

      • JDK 1.8


      Execute following command (on local machine typically):

      copy
      java \
        -Dclient.id=<client_id> \
        -Dmerchant.privkey.path=<merchant_private_key_path> \
        -Dzoloz.pubkey.path=<zoloz_public_key_path> \
        -jar src/examples/clientmode-bizserver/target/zoloz-clientmode-bizserver-1.0-SNAPSHOT.jar


      or specify public key content directly instead of specify the file path of the public key:

      copy
      java \
        -Dclient.id=<client_id> \
        -Dmerchant.privkey.path=<merchant_private_key_path> \
        -Dzoloz.pubkey=<zoloz_public_key_base64_content> \
        -jar src/examples/clientmode-bizserver/target/zoloz-clientmode-bizserver-1.0-SNAPSHOT.jar


      #API Specification Reference

      Refer to RealId API specification for more information.


      #Client-side Integration

      #Configurations

      Our SDK requires configurations to function, and there are two types of configurations to be noted.


      Runtime configurations are obtained from zoloz server during runtime, and need to be supplied to SDK when invoking the SDK.


      Static configurations are done during development and build phase.

      • UI style: This is optional as there is a default UI style in place. However, you can customize your UI style via Chameleon configurations.
      • RSA public key: The traffic payload between our SDK and our server is encrypted with RSA, hence you need to generate a pair of keys, and keep the private key at zoloz server, and the public key in our SDK.


      #SDK API Specification

      Both Android and iOS have similar interfaces defined, here we take Android for example. 


      #ZLZFacade

      This is the primary interface to be used to call our SDK. Please note in iOS getMetaInfo doesn't require any arguments, while Android requires a context as the input.


      copy
      public class ZLZFacade {
          /**
           * get single instance of hummer facade
           */
          public static ZLZFacade getInstance() ;
      
          /**
           * Start the SDK.
           * Runtime configurations shall be enclosed in the request.
           */
          public void start(ZlZRequest request, final IZLZCallback callback);
          
          /**
           * To get necessary device and SDK meta info, which includes SDK version
           * and device model etc. 
           * The meta info needs to be sent to ZOLOZ server during initialization.
           * 
           * Note: iOS does not require the context parameter.
           */
          public static String getMetaInfo(Context context) 
      
      }


      #IZLZCallback

      This interface consists of two callback functions, which will be called by our SDK when eKYC is completed or interrupted. You need to implement them with business logics to handle the outcome from our SDK.


      copy
      public interface IZLZCallback {
          /**
           * will be triggered by ZOLOZ SDK when the process is finished
           *
           * @param response
           */
          public void onCompleted(ZLZResponse response);
          
          /**
           * will be triggered by ZOLOZ SDK when the process is interrupted
           *
           * @param response
           */
          public void onInterrupted(ZLZResponse response);
      }



      #Android Integration Guide

      Add dependency library

      1. Get the latest SDK, unzip and move it to libs folder.
        image


      1. Add libs folder to flatDir like this:
      copy
      repositories {
        flatDir {
          dirs 'libs'
        }
      }


      1. In your module's (app-level) Gradle file (usually app/build.gradle), add Zoloz sdk as dependecy.
      copy
      dependencies {
          // ...
          implementation (name:'zoloz-kit', ext: 'aar')
          
          implementation "com.squareup.okio:okio:1.7.0@jar"
          implementation "com.alibaba:fastjson:1.1.68.android"
      }


      Start the SDK

      To start SDK, some runtime configurations need to be obtained from server first, refer to step 4 in the sequence diagram, and in this step, meta info must be sent to server.


      To get the meta info from our SDK, you can simply do this:

      copy
      ZLZFacade.getMetaInfo(applicationContext);


      If server initialized the eKYC flow successfully, and returned with the configurations clientCfg, you can then construct a ZLZRequest object and start the SDK in this way. You need to implement the callback functions to handle the eKYC outcome.

      copy
      public ZLZRequest createZLZRequest(String clientCfg) {
        ZLZRequest request = new ZLZRequest();
        request.bizConfig = new HashMap<>();
        request.bizConfig.put(ZLZConstants.CONTEXT, this);
        request.bizConfig.put(ZLZConstants.PUBLIC_KEY, publickey);
        request.bizConfig.put(ZLZConstants.LOCALE, locale);
        request.zlzConfig = clientCfg;
        return request;
      }
      
      public void startZolozSDK(ZLZRequest request) {
        ZLZFacade.getInstance().start(request, new IZLZCallback() {
            @Override
            public void onCompleted(ZLZResponse response) {
              // to be implemented by you
              // will be called by our SDK when eKYC is completed.
            }
      
            @Override
            public void onInterrupted(ZLZResponse response) {
              // to be implemented by you
              // will be called by our SDK when eKYC is interrupted.
            }
          });
      }


      #Proguard

      Please add the following configuration to the project's confusing file:

      copy
      -dontwarn com.zoloz.**
      -keep class com.zoloz.zhub.**{
        <fields>;
         <methods>;
      }
      -keep class com.alipay.zoloz.**{
         <fields>;
         <methods>;
      }
      -keep class com.alipay.android.phone.zoloz.**{
         <fields>;
         <methods>;
      }
      -keep class com.alipay.biometrics.**{
         <fields>;
         <methods>;
      }
      -keep class com.alipay.bis.**{
         <fields>;
         <methods>;
      }
      -keep class com.alipay.mobile.security.**{
         <fields>;
         <methods>;
      }
      -keep class com.ap.zoloz.**{
         <fields>;
         <methods>;
      }
      -keep class com.ap.zhubid.endpoint.**{
         <fields>;
         <methods>;
      }
      -keep class com.zoloz.android.phone.zdoc.**{
         <fields>;
         <methods>;
      }
      -keep class zoloz.ap.com.toolkit.**{
         <fields>;
         <methods>;
      }
      -keep class com.zoloz.builder.** {
         <fields>;
         <methods>;
      }


      #iOS Integration

      Add dependency library

      1. Download latest SDK.
      2. Unzip and add zolozkit.framework to your project. and also need add System Library in pic:

      image.png

      1. Zoloz sdk requires camera permission, please add Camera Permissions into plist file. Click here for more about camera permission.
      2. Import Zoloz resources, usually resources will be added automatically when importing Zoloz SDK.Developers need to make sure main bundle can read these resources.
        ZolozKit.bundle,ToygerService.bundle,BioAuthEngine.bundle WebContainerLite.bundle

      image.png

      1. add -ObjC in Other Linker Flags


      Screen Shot 2020-01-22 at 4.14.18 PM.png


      Start eKYC

      The process is similar with Android, here we listed the iOS code samples.


      To get the meta info from SDK:

      copy
      NSString *metainfo = [ZLZFacade getMetaInfo];


      Construct ZLZRequest object with clientCfg returned from server and public key generated by your server :

      copy
      NSString *clientConfig = clinetCfg;
      //.pass the current ViewController to bizConfig
      NSMutableDictionary *bizConfig = [NSMutableDictionary dictionary];
      [bizConfig setObject:self forKey:kZLZCurrentViewControllerKey];
      //.pass the public key to bizConfig
      [bizConfig setObject:publicKey forKey:kZLZPubkey];
      //.pass the locale to bizConfig
      [bizConfig setObject:locale forKey:kZLZLocaleKey]
      ZLZRequest *request = [[ZLZRequest alloc] initWithzlzConfig:clientConfig bizConfig:bizConfig];


      Start the SDK with ZLZRequest, completionCallback and interruptCallback objects:

      copy
      [[ZLZFacade sharedInstance] startWithRequest:request completeCallback:^(ZLZResponse *response) {
        
      } interruptCallback:^(ZLZResponse *interrupt){
        
      }];


      #Example

      #Android Examples

      sdk& demo code: 📎saas_demo_app.zip

      compiled apk:📎saas_demo_app_apk.zip


      #iOS Examples

      sdk& demo code:📎saas_demo_ios.zip