すべてのプロダクト
Search

このプロダクト

    Financial Intelligence Engine:アプリ SDK モード統合

    ドキュメントセンター

    Financial Intelligence Engine:アプリ SDK モード統合

    最終更新日:Mar 13, 2025

    ZOLOZ は、ネイティブモバイル アプリケーションと統合するための SDK と API を提供しています。この記事では、アーキテクチャ、サポートされているプロダクト、インタラクションフロー、一般的な統合プロセスという観点から、アプリ SDK モード統合の概要を説明します。

    サポートされているプロダクト

    アプリ SDK モード統合は、以下のプロダクトに適用できます。

    • Real ID

    • Face Capture

    • ID 認識

    • Connect

    • NFC Reader

    統合アーキテクチャ

    次の図は、アプリ SDK モード統合のアーキテクチャを示しています。

    01-p776957.png

    図 1. アプリ SDK モード統合アーキテクチャ

    アプリ SDK モード統合は、2 つの部分で構成されています。

    • クライアント側統合: 加盟店アプリケーションに ZOLOZ SDK を統合します。 ZOLOZ SDK は、iOS アプリケーションと Android アプリケーションの両方に、顔画像、身分証明書画像などの必要なユーザーデータをキャプチャするための一連の画面とツールを提供します。 ZOLOZ SDK を統合することで、ユーザーにとって使いやすいインタラクションエクスペリエンスを簡単に作成できます。

      • ビジネスプロセス全体をユーザーに案内する、適切に設計された UI

      • 複数のアルゴリズムを適用した、高い成功率と高いセキュリティ

      • 画像を ZOLOZ サービスに直接アップロードすることで、統合プロセスを簡素化

    • サーバー側統合: 加盟店アプリケーションが加盟店サーバーと対話できるように、加盟店サーバーに加盟店アプリケーションのエンドポイントを公開します。その後、加盟店サーバーは ZOLOZ API にアクセスしてトランザクションを初期化し、検証結果を再確認します。

    インタラクションフロー

    次の図は、モバイル アプリケーションから ZOLOZ サービスが開始されたときのインタラクションフロー全体を示しています。

    02-p776958.svg

    図 2. シーケンス図

    1. ユーザーは、加盟店アプリケーションを通じてビジネスプロセス (ID 確認プロセスなど) を開始します。

    2. 加盟店アプリは getMetaInfoZOLOZ SDK とユーザー デバイスのメタ情報を取得するためのインターフェースです。

    3. ZOLOZ SDK は、メタ情報を加盟店アプリケーションに返します。

    4. 加盟店アプリケーションはトランザクションを初期化し、メタ情報を加盟店サーバーに渡します。

    5. メタ情報を入力として、加盟店サーバーは API を呼び出して、SDK の接続と動作に関するパラメーターを含むクライアント構成情報を取得します。初期化 SDK の接続と動作に関するパラメーターを含む、クライアント構成情報を取得するための API です。

    6. ZOLOZ サーバーは、メタ情報に基づいてユーザビリティチェックを実行します。チェックに合格すると、ZOLOZ サーバーはクライアント構成情報を加盟店サーバーに返します。

    7. 加盟店サーバーは、クライアント構成情報を加盟店アプリケーションに返します。

    8. 加盟店アプリケーションは、手順 7 で取得したクライアント構成情報を使用して ZOLOZ SDK を起動します。

    9. ZOLOZ SDK はユーザーと対話し、必要なデータ (顔画像など) をキャプチャし、検証のために ZOLOZ サーバーにアップロードします。 ZOLOZ SDK と ZOLOZ サーバー間で複数回のインタラクションが行われる場合があります。

    10. ZOLOZ サーバーは、アップロードされたユーザーデータに対して関連チェックを実行し、トランザクションステータスを ZOLOZ SDK に返します。対応するすべてのチェックに合格すると、成功を示す結果コードが ZOLOZ SDK に返されます。そうでない場合、プロセスが中断され、ユーザーと ZOLOZ SDK 間のさらなるインタラクションが必要になる場合があります。

    11. ZOLOZ SDK は、トランザクションが完了したことを加盟店アプリケーションに通知します。

    12. 加盟店アプリケーションは、トランザクションが完了したことを加盟店サーバーと同期し、トランザクションの詳細の再確認を開始します。

    13. 加盟店サーバーが checkResult ZOLOZ サーバーでトランザクションの詳細を再確認するための API です。

    14. ZOLOZ サーバーは、トランザクションの詳細を加盟店サーバーに返します。

    注: 情報セキュリティを確保するため、キャプチャされた顔画像などの機密情報は加盟店サーバーにのみ返されます。

    1. 加盟店サーバーは、ZOLOZ サーバーから返されたトランザクションの詳細をフィルタリングし、加盟店アプリケーションにとって機密ではない情報を返します。

    2. 加盟店アプリケーションは、プロセスが完了したことをユーザーに通知します。

    一般的な統合プロセス

    このセクションでは、サーバー側とクライアント側からアプリ SDK モード統合を実装する方法について説明します。

    サーバー側統合

    前提条件

    サーバー側統合を実行する前に、「」の手順に従って、ZOLOZ ゲートウェイサービスを正常に呼び出すことができるようにし、API リクエストとレスポンスを正しく処理できるようにします。ZOLOZ ゲートウェイと連携するZOLOZ ゲートウェイ サービスが正常に呼び出され、API リクエストとレスポンスが正しく処理されるようにするためです。

    手順

    加盟店アプリケーションが加盟店サーバーと対話し、加盟店サーバーが ZOLOZ API を呼び出すことができるようにするには、加盟店サーバーに加盟店アプリケーションのエンドポイントを公開する必要があります。次のサンプルコードでは、Real ID API を例に使用して、アノテーションを使用して加盟店アプリケーションのエンドポイントを公開する方法を示します。

    注: このサンプルは、加盟店サーバーが ZOLOZ サーバーと対話するために必要な処理ロジックのみを示しています。必要に応じて、ビジネスロジックを実装する必要があります。次に例を示します。

    • 初期化 API を実装する際は、後で取得するために、ZOLOZ サーバーから返されるトランザクション ID を保存してください。

    • checkResult API を実装する際は、トランザクションの詳細を保存し、機密情報をマスキングして、マスキングされた情報をクライアント側に返します。

    // クライアント アプリケーションが使用するエンドポイントを公開するためにアノテーションを使用する
@RestController
//API エンドポイントの共通ベースパスを定義する
@RequestMapping(value = {"/webapi"})
public class NativeClientModeController {
    
    // ZOLOZ API を呼び出すために ZOLOZ によって提供される openApiClient オブジェクトを自動配線する
    @Autowired
    private OpenApiClient openApiClient;
    
    // API URL パスにマッピングする最初のサービスを定義する
    @RequestMapping(value = {"/realid/initialize"}, method = RequestMethod.POST)
    public JSONObject realIdInit(@RequestBody JSONObject request) {

        // 手順 1: リクエストオブジェクトをインスタンス化し、必要なパラメーターを提供する
        JSONObject apiReq = new JSONObject();   
        apiReq.put("flowType", "REALIDLITE_KYC");
        // apiReq.put("...","..."); 必要に応じてさらにリクエストパラメーターを追加する。 Real ID initialize API のリクエストパラメーターの詳細については、API リファレンスチャプターの対応する API 仕様を参照してください。
        
        // 手順 2: openApiClient を介して ZOLOZ API を呼び出す
        String apiRespStr = openApiClient.callOpenApi(
                "v1.zoloz.realid.initialize",
                JSON.toJSONString(apiReq)
        );

        // 手順 3: ZOLOZ API レスポンスを処理し、戻りオブジェクトを構築する
        JSONObject apiResp = JSON.parseObject(apiRespStr);
        JSONObject response = new JSONObject(apiResp);
        response.put("rsaPubKey", openApiClient.getOpenApiPublicKey());
        // ... その他のコードは省略

        // 手順 4: サービスレスポンスを返す
        return response;
    }

    // 必要に応じてさらにサービスを定義する。たとえば、Real ID の場合は、トランザクション結果を確認するサービスを定義する必要がある
    @RequestMapping(value = "/realid/checkresult", method = RequestMethod.POST)
    public JSONObject realIdCheck(@RequestBody JSONObject request) {

        // リクエストを作成し、レスポンスを処理するための詳細なロジックを実装する
    }
}

    最小限の加盟店サーバーの例

    ZOLOZ は、さまざまなプロダクト向けの簡略化されたマーチャントサーバーのサンプルコードを提供しています。このサンプルコードには、ZOLOZ SaaS 環境とのやり取りに必要な最小限のコードリソースが含まれています。このコードは、Githubでオープンソース化されています。

    注:加盟店サーバーコードは、ZOLOZ が提供するデモ アプリと連携して動作する必要があります。デモ アプリの詳細については、デモアプリの例

    API リファレンス

    各 ZOLOZ プロダクトに提供される API の詳細については、以下を参照してください。

    クライアント側統合

    SDK 要件

    ZOLOZ SDK は、Android と iOS の両方をサポートしています。 ZOLOZ SDK を統合するには、モバイルデバイスシステムが次の要件を満たしていることを確認してください。

    • オペレーティングシステムのバージョンは、Android 4.3 以降、または iOS 9 以降である必要があります。

    • ネットワークとカメラの権限が ZOLOZ SDK に付与されている必要があります。

    注: x86 アーキテクチャはサポートされていないことに注意してください。

    Android 統合

    1. SDK のインポート

    a. maven リポジトリを構成する

    プロジェクトのルートディレクトリにある build.gradle ファイルに、次の maven リポジトリ構成を追加します。

    mavenCentral()

    b. SDK 依存関係を追加する

    モジュール (アプリケーションレベル) の gradle ファイル (通常は app/build.gradle) に依存関係として SDK を追加します。

    implementation 'com.zoloz.android.build:zolozkit:latest-version' //便宜上 最新バージョンの SDK を使用することをお勧めします。これは、プロダクトエクスペリエンスとセキュリティを常に強化するためです。現在のリリースノートについては、https://docs.zoloz.com/zoloz/saas/releasenotes/ を参照してください。
implementation 'com.zoloz.android.build:nearx:latest-version' //セキュリティのために この実装を追加することを強くお勧めします。 nearx
implementation "com.squareup.okio:okio:1.7.0@jar"
implementation "com.alibaba:fastjson:1.1.68.android"
implementation 'com.zoloz.android.build:znfc:latest-version' //オプション。 nfc リーダーのサポート

    注記:

    • コード「implementation 'com.zoloz.android.build:nearx:latest-version'は EagleFaceID ​関数、および "implementation 'com.zoloz.android.build:znfc:latest-version'" は NFC 関数です。これらの関数をアクティブにする必要がある場合は、ZOLOZ チームに連絡してください。これらの 2 行のコードは、必要ない場合は省略できます。EagleFaceID または NFC 関数。

    • 他の SDK を同時に統合すると、「OS 独立パス 'lib/arm64-v8a/libc++_shared.so' を持つ複数のファイルが見つかりました」というエラーが発生する場合があります。これは、ZOLOZ SDK と他の SDK が libc++_shared.so ライブラリを追加していることが原因です。この問題を解決するには、 に次の構成を追加してください。build.gradle：

    packagingOptions { 
    pickFirst 'lib/arm64-v8a/libc++_shared.so' 
    pickFirst 'lib/armeabi-v7a/libc++_shared.so' 
}
    2. メタ情報を取得する

    ZLZFacade クラスとそのメソッド getMetaInfo を使用して、ZOLOZ SDK とユーザーのデバイスに関するメタ情報を取得します。メタ情報は、後でトランザクションを初期化するために使用されます。ZLZFacade と getMetaInfo の詳細については、「ZLZFacade」を参照してください。

    String metaInfo = ZLZFacade.getMetaInfo(applicationContext);

    メタ情報を含むリクエストを加盟店サーバーに送信して、トランザクションを初期化します。その後、加盟店サーバーは initialize API を呼び出してクライアント構成を取得し、加盟店アプリケーションに返します。

    4. トランザクションフローを開始する

    a. クライアント構成を使用して ZLZRequest オブジェクトを構築します

    ZLZRequest request = new ZLZRequest();
request.bizConfig = new HashMap<>();
request.bizConfig.put(ZLZConstants.CONTEXT, this);
request.bizConfig.put(ZLZConstants.LOCALE, locale);
request.zlzConfig = clientCfg;
return request;

    b. 手順 5(a) で構築した ZLZRequest オブジェクトを使用して start メソッドを呼び出すことで、トランザクションフローを開始します。また、トランザクション結果を処理するためにコールバック関数をオーバーライドする必要もあります。

    ZLZFacade.getInstance().start(request, new IZLZCallback() {
    @Override
    public void onCompleted(ZLZResponse response) {
    }
    @Override
    public void onInterrupted(ZLZResponse response) {
    }
});

    トランザクション結果には、トランザクションフローステータスを示す結果コードが含まれています。エンドユーザーがフローを完了した場合、 メソッドが呼び出されます。このメソッドでは、トランザクションステータスを加盟店サーバーと同期し、再確認を開始する必要があります。その後、加盟店サーバーは checkResult API を呼び出してトランザクションの詳細を取得し、加盟店アプリケーションに返します。onCompleted メソッドが呼び出されると、トランザクション ステータスを (加盟店) サーバーと同期し、二重チェックを開始する必要があります。次に、(加盟店) サーバーは checkResult API を呼び出してトランザクションの詳細を取得し、(加盟店) アプリケーションに返す必要があります。

    エンドユーザーがフローを完了していない場合、onInterrupted メソッドが呼び出されます。関連する処理ロジックは、ビジネス要件に従って実装する必要があります。

    クラスの詳細については、ZLZRequest、ZLZResponse、ZLZConstantsについては、Android SDK。

    5. ProGuard を処理する

    Android アプリケーションで ProGuard が有効になっている場合、ZOLOZ SDK をアプリケーションで正常に呼び出すことができるようにするには、プロジェクトの confusing ファイルに次の構成を追加します。

    -dontwarn com.zoloz.**

-keep class okio.** { *; }
-keep class com.alibaba.fastjson.** { *; }
-keep class com.alibaba.fastjson2.** { *; }
-keep class com.zoloz.zhub.** { *; }
-keep class com.alipay.zoloz.** { *; }
-keep class com.zoloz.zcore.facade.common.** { *; }
-keep class com.alipay.android.phone.zoloz.** { *; }
-keep class com.alipay.biometrics.** { *; }
-keep class com.alipay.bis.** { *; }
-keep class com.alipay.mobile.security.** { *; }
-keep class com.ap.zoloz.** { *; }
-keep class com.ap.zhubid.endpoint.** { *; }
-keep class com.zoloz.android.phone.zdoc.** { *; }
-keep class zoloz.ap.com.toolkit.** { *; }
-keep class com.zoloz.builder.** { *; }
-keep class com.ant.phone.xmedia.** { *; }
-keep class com.alipay.alipaysecuritysdk.** { *; }
-keep class com.alipay.blueshield.** { *; }
-keep class com.alipay.deviceid.** { *; }
-keep class com.alipay.edge.** { *; }
-keep class com.alipay.softtee.NativeHelper { *; }
-keep class com.alipay.apmobilesecuritysdk.tool.si.SIUtils { *; }
-keep class face.security.device.api.** { *; }
-dontwarn face.security.device.api.**

    注: クライアントがバージョンをアップグレードする場合は、難読化ルールも更新してください。

    iOS 統合

    1. プライバシー権限の説明

    ZOLOZ は、次のユーザー権限へのアクセスを必要とします。

    権限

    説明

    NSCameraUsageDescription

    ZOLOZ は、カメラの権限を使用して顔と ID の情報を収集します

    NSLocalNetworkUsageDescription

    デバイスランチングやグループコントロールなどのリスクを検出するために、ローカルエリアネットワーク内のデバイスの接続性を取得するために使用されます

    NSUserTrackingUsageDescription

    IDFA 情報を取得し、デバイス ID の安定性を向上させるために使用されます

    2. SDK 依存関係を構成する

    a. Podfile でプライベート仕様を構成する:

    source "https://github.com/zoloz-pte-ltd/zoloz-demo-ios"

    b. Podfile に SDK 依存関係を追加する:

    #zolozkit changelog https://docs.zoloz.com/zoloz/saas/releasenotes/

# #最新バージョンを使用することをお勧めします。これには、新機能とセキュリティの改善が含まれています。 特定のバージョンの詳細が必要な場合は、変更ログを確認してください
pod 'zolozkit'  #コアモジュール
pod 'zolozkit/ZolozNfcReader' #nfc リーダーモジュール

    注: コード "pod 'zolozkit/ZolozNfcReader'" は NFC 機能に対応しています。 NFC 機能を有効にする必要がある場合は、ZOLOZ チームにご連絡ください。 NFC 機能が不要な場合は、この 1 行のコードを省略できます。

    3. SDK を取得する

    次のコマンドを実行して SDK を取得します。

    pod install
    4. リンカーフラグを構成する

    -ObjC 定数と $(inherited) 定数を [ビルド設定]> [その他のリンカーフラグ] に追加します。

    03-p563054.png

    図 3. その他のリンカーフラグの設定

    5. ヘッダー参照ヘッダー参照

    Objective-C:

    #import <hummer/ZLZFacade.h>
#import <hummer/ZLZRequest.h>
#import <hummer/ZLZResponse.h>

    Swift:

    import hummer
    6. メタ情報を取得する

    を使用しますZLZFacae クラスとそのメソッド getMetaInfo ZOLOZ SDK とユーザーのデバイスに関するメタ情報を取得するためです。メタ情報は、後でトランザクションを初期化するために使用されます。 ZLZFacae と getMetaInfo の詳細については、「ZLZFacade。

    Objective-C:

    NSString *metainfo = [ZLZFacade getMetaInfo];

    Swift:

    let metainfo = ZLZFacade.getMetaInfo()
    7. トランザクションを初期化する

    メタ情報を含むリクエストを加盟店サーバーに送信して、トランザクションを初期化します。その後、加盟店サーバーは initialize API を呼び出してクライアント構成を取得し、加盟店アプリケーションに返します。

    8. トランザクションフローを開始する

    a. クライアント構成を使用して ZLZRequest オブジェクトを構築します。

    Objective-C:

    NSString *clientConfig = clientCfg;
NSMutableDictionary *bizConfig = [NSMutableDictionary dictionary];
// `self` viewcontroller は UINavigationController にネストされている必要がある
[bizConfig setObject:self forKey:kZLZCurrentViewControllerKey]; 
//.ロケールを bizConfig に渡す
[bizConfig setObject:locale forKey:kZLZLocaleKey]
ZLZRequest *request = [[ZLZRequest alloc] initWithzlzConfig:clientConfig bizConfig:bizConfig];

    Swift:

    let clientConfig = clientCfg
let bizConfig = NSMutableDictionary()
// `self` viewcontroller は UINavigationController にネストされている必要がある
bizConfig[kZLZCurrentViewControllerKey] = self
//.ロケールを bizConfig に渡す
bizConfig[kZLZLocaleKey] = locale
let request = ZLZRequest.init(zlzConfig: clientConfig ?? "", bizConfig: bizConfig as! [AnyHashable : Any])

    b. 手順 6(a) で構築した ZLZRequest オブジェクトを使用して startWithRequest を呼び出すことで、トランザクションフローを開始します。また、トランザクション結果を処理するためにコールバック関数をオーバーライドする必要もあります。

    Objective-C:

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

    Swift:

    ZLZFacade.sharedInstance().start(with: request) { response in
} interruptCallback: { response in
}

    トランザクション結果には、トランザクションフローのステータスを示す結果コードが含まれています。エンドユーザーがフローを完了した場合、completeCallback が呼び出されます。この場合、トランザクションステータスを（加盟店）サーバーと同期し、二重チェックを開始する必要があります。次に、（加盟店）サーバーは checkResult API を呼び出してトランザクションの詳細を取得し、（加盟店）アプリケーションに返す必要があります。

    エンドユーザーがフローを完了していない場合、interruptCallback が呼び出されます。ビジネス要件に応じて、関連するプロセスロジックを実装する必要があります。

    クラスの詳細については、ZLZRequest および ZLZResponse、iOS SDK。

    デモアプリの例

    ZOLOZ は、iOS と Android のデモアプリケーションを提供しています。これらのアプリケーションは、ZOLOZ SDK が統合されたモバイルアプリケーション環境をシミュレートします。デモアプリケーションを ZOLOZ が提供する加盟店サーバーコードと一緒に使用して、統合フロー全体をテストできます。

    デモアプリは Github でオープンソース化されています。

    加盟店サーバーコードの詳細については、「最小限の加盟店サーバーの例」をご参照ください。