すべてのプロダクト
Search

このプロダクト

    ID Verification:HarmonyOS との統合

    ドキュメントセンター

    ID Verification:HarmonyOS との統合

    最終更新日:Nov 09, 2025

    このトピックでは、HarmonyOS 用の FACE_GUARD ソフトウェア開発キット (SDK) を統合する方法について説明します。

    前提条件

    重要

    FACE_GUARD を統合するアプリケーションには、成熟した顔認識アルゴリズムと脅威ポリシーを管理するシステムが必要です。まず、ビジネスシナリオに適しているかどうかを評価するために、ビジネスマネージャーに相談することをお勧めします。

    HarmonyOS SDK には、次の制限があります。

    • エミュレーターモードでのデバッグはサポートされていません。

    • HarmonyOS NEXT (0.0.71) 以降では、サポートされる最小 API バージョンは 12 です。

    • バイトコード暗号化ソリューションのみがサポートされています。

    統合手順

    準備

    SDK を統合する前に、権限と依存関係を構成する必要があります。

    権限

    顔の偽装検出を向上させるために、SDK には次の権限が必要です。

    権限

    必須

    説明

    ohos.permission.INTERNET

    はい

    インターネットアクセス。SDK が機能するには、インターネット接続が必要です。

    ohos.permission.GET_NETWORK_INFO

    はい

    ネットワーク状態へのアクセス。SDK はネットワーク状態を使用して、より良いサービスを提供します。

    ohos.permission.STORE_PERSISTENT_DATA

    いいえ (推奨)

    アプリケーションが永続データを保存できるようにします。これにより、デバイスフィンガープリントの安定性が向上します。

    依存関係の構成

    1. HarmonyOS SDK をダウンロードして解凍します。SDK はビジネスマネージャーから入手できます。SDK は、標準の HarmonyOS .har パッケージです。

    2. .har ファイルを、プロジェクト内の .har パッケージが保存されているディレクトリにコピーします。公式の HarmonyOS ドキュメントで推奨されているように、ファイルを libs ディレクトリに配置することをお勧めします。プロジェクトのルートディレクトリで、認証パッケージを oh-package.json5 ファイルの依存関係リストに追加し、バージョン番号を指定します。次のコードは例です。

      {
  ....
  "dependencies": {
    "aliyunfaceguard": "file:./libs/AliyunFaceGuard-xxx.har" // パッケージの依存関係を追加します。
    ....
  }
}

      image.png

    API 難読化の構成 (重要)

    API の難読化による機能上の問題を回避するために、.har パッケージの obfuscation.txt ファイル内の構成を確認してください。このファイルを削除しないでください。

    一部のコンパイラバージョンで難読化構成のマージに失敗し、統合の失敗を引き起こす場合は、パッケージング中に obfuscation-rules.txt 構成ファイルを .har パッケージからアプリケーションのメインプロジェクトに追加する必要があります。その後、難読化ルールをプロジェクトに追加します。

    SDK の呼び出し

    準備が完了したら、次の 3 つのステップに従ってクライアント側の統合を完了します。

    1. SDK の初期化 (initWithOptions)

    2. クライアントトークンの取得 (getDeviceToken)

    3. トークンを使用してサーバーにリクエストを送信する

    1. SDK の初期化 (initWithOptions)

    この関数は SDK を初期化します。アプリケーションの起動後、できるだけ早くこの関数を呼び出す必要があります。詳細については、「統合フロー」をご参照ください。[タイミング 1] で initWithOptions API 操作を呼び出します。

    重要

    マルチスレッドシナリオでは、メインスレッドで初期化 API 操作を呼び出す必要があります。この操作は、アプリケーションライフサイクル中に一度だけ呼び出す必要があります。

    • 関数プロトタイプ

        public initWithOptions(ctx: Context, userProductKey: string,
                         options: Map<string, string>,
                         securityInitListener: SecurityInitListener): void

    • パラメーター

      • ctx: 現在の UIContext または Context。getContext() メソッドを使用して取得できます。

      • userProductKey: Alibaba Cloud によってユーザーを識別するために割り当てられた AppKey。このキーは AccessKey (AK) とは異なります。ビジネスマネージャーから入手できます。

        重要

        FACE_GUARD を統合するアプリケーションには、成熟した顔認識アルゴリズムと脅威ポリシーを管理するシステムが必要です。まず、ビジネスシナリオに適しているかどうかを評価するために、ビジネスマネージャーに相談することをお勧めします。

      • options: データ収集のためのオプションパラメーター。デフォルト値は null です。次のパラメーターが利用可能です。

        説明

        • ID Verification クライアントには、Device Guard セキュリティモジュールが組み込まれています。さまざまなリージョンでのデータ収集コンプライアンス要件を満たすために、さまざまなデータレポートサイトを提供します。CustomUrl と CustomHost を設定して、ユーザー属性に基づいてレポートサイトを指定できます。

          注: 1 つのアプリケーションセッションライフサイクル内で指定できるレポートサイトは 1 つだけです。サーバークエリリージョンはレポートサイトと一致する必要があります。

        • レポートサイトの指定:

          • シンガポールサイト (デフォルト): https://cloudauth-device.ap-southeast-1.aliyuncs.com

          • インドネシアサイト: https://cloudauth-device.ap-southeast-5.aliyuncs.com

          • 米国西部 (シリコンバレー): https://cloudauth-device.us-west-1.aliyuncs.com

          • ドイツ (フランクフルト): https://cloudauth-device.eu-central-1.aliyuncs.com

          • 中国 (香港): https://cloudauth-device.cn-hongkong.aliyuncs.com

        • プロダクトサーバーでサポートされているリージョンの詳細については、「サポートされているリージョン」をご参照ください。

        フィールド名

        説明

        例

        IPv6

        デバイス情報をレポートするために IPv6 ドメイン名を使用するかどうかを指定します。

        • 0 (デフォルト): いいえ (IPv4 ドメイン名を使用)

        • 1: はい (IPv6 ドメイン名を使用)

        "1"

        DataSwitch

        デバイス情報をレポートするタイミング。

        • 0 (デフォルト): 初期化時

        • 1: トークン取得時

        説明

        デフォルトの構成を使用することをお勧めします。

        "1"

        CustomUrl

        データレポートサーバーのドメイン名を設定します。

        "https://cloudauth-device.ap-southeast-1.aliyuncs.com"

        CustomHost

        データレポートサーバーのホストを設定します。

        "cloudauth-device.ap-southeast-1.aliyuncs.com

      • securityInitListener: 初期化コールバックリスナー。コールバックを使用して、初期化が成功したかどうかを確認できます。デフォルト値は null です。`code` フィールドに設定可能な値の詳細については、「code の戻り値」をご参照ください。

        securityInitListener の定義

        public interface FaceSecInitListener {
    // code は API 呼び出しの状態コードを示します
    onInitFinish: (code: number) => void;
}

    • 呼び出し例

      @State USER_PRODUCT_KEY: string = "123e4567e89b12d3a45642661417****";

let options: Map<string, string> = new Map<string, string>();
options.set("IPv6", "0"); // IPv4 に設定
options.set("DataSwitch", "0"); // 初期化中にデータを収集するように設定
// カスタムデータレポートリージョンを設定
// options.set("CustomUrl", "xxx"); // レポートサイトの URL を設定
// options.set("CustomHost", "xxx"); // レポートサイトのホストを設定

// 標準呼び出し (推奨)
FaceSecDevice.getInstance().initWithOptions(getContext(), 
                            this.USER_PRODUCT_KEY, options, null);

// コールバック呼び出し
FaceSecDevice.getInstance().initWithOptions(this.context, 
                            this.USER_PRODUCT_KEY, options, {
    onInitFinish(code: number) {
      if (FaceSecCode.SC_SUCCESS != code) {
        console.log("AliyunFaceGuard の初期化に失敗しました");
      } else {
        console.log("AliyunFaceGuard の初期化に成功しました");
      }
    }
});

    2. クライアント トークンの取得 (getDeviceToken)

    この操作はクライアントトークンを取得します。詳細については、「統合フロー」をご参照ください。この操作を [タイミング 2] で呼び出します。トークンをサーバーにレポートします。次に、サーバーから FACE_GUARD API 操作 (FaceGuardRisk) を呼び出して、クライアントからデバイスの脅威検出情報を取得します。

    重要

    • 詳細については、「統合フロー」をご参照ください。initWithOptions API 操作を [タイミング 1] で呼び出し、getDeviceToken API 操作を [タイミング 2] で呼び出します。または、initWithOptions と getDeviceToken API 操作の呼び出しの間に少なくとも 3 秒の間隔を確保してください。

    • getDeviceToken を呼び出すときは、bizId を渡すことをお勧めします。これにより、トークンが一意のビジネス認証 ID に関連付けられます。サーバーで結果をクエリするときは、同じ ID を渡す必要があります。クライアントから渡された bizId がサーバーから渡された ID と一致することを確認してください。これにより、トークンの改ざんの脅威を防ぐことができます。

    • getDeviceToken API 操作はサブスレッドで呼び出すことをお勧めします。これにより、API 呼び出しの完了に時間がかかった場合にアプリケーションがクラッシュするのを防ぐことができます。

    • 関数プロトタイプ

      // bizId を渡すことをお勧めします
public getDeviceToken(bizId?: string): SecurityToken

    • パラメーター

      bizId: カスタムビジネス ID。この ID は、トークンを特定のビジネス操作に関連付けるために使用されます。このパラメーターはオプションです。

    • 戻り値

      • 次のプロパティを持つ `FaceSecToken` オブジェクトが返されます。 

        public class FaceSecToken {
    // API 呼び出しの状態コード
    public code: number = 0;

    // サーバー側の結果クエリに使用されるトークン文字列。
    public token: string = "";
}

        • code: API 呼び出しの状態コード。このコードを使用して、呼び出しが成功したかどうかを判断できます。

          code の戻り値

          FaceSecCode

          コード

          注記

          SC_SUCCESS

          10000

          SDK は正常に初期化されました。

          SC_NOT_INIT

          10001

          SDK は初期化されていません。

          SC_NOT_PERMISSION

          10002

          SDK に必要な基本的な Android 権限が完全に付与されていません。

          SC_UNKNOWN_ERROR

          10003

          不明なシステムエラーが発生しました。

          SC_NETWORK_ERROR

          10004

          ネットワークエラーが発生しました。

          SC_NETWORK_ERROR_EMPTY

          10005

          ネットワークエラーが発生しました。返されたコンテンツは空の文字列です。

          SC_NETWORK_ERROR_INVALID

          10006

          ネットワーク応答のフォーマットが無効です。

          SC_PARSE_SRV_CFG_ERROR

          10007

          サーバー構成の解析に失敗しました。

          SC_NETWORK_RET_CODE_ERROR

          10008

          ゲートウェイが失敗を返しました。

          SC_APPKEY_EMPTY

          10009

          AppKey が空です。

          SC_PARAMS_ERROR

          10010

          その他のパラメーターエラー。

          SC_FGKEY_ERROR

          10011

          キー計算エラーが発生しました。

          SC_APPKEY_ERROR

          10012

          AppKey が無効です。

      • token: 返されたトークン文字列。これを使用して、後続の FACE_GUARD の FaceGuardRisk API 操作の呼び出しを行うことができます。

        重要

        token 文字列は、安定したネットワーク接続で約 600 バイトの長さです。不安定なネットワーク接続では、長さは約 2.5 KB で、特別な識別子が含まれます。

        • 安定したネットワーク: "U0dfTkxxxx"

        • 不安定なネットワーク: "U0dfUFxxxx"

        アプリケーションが多数の長いトークンを生成する場合:

        • まず、クライアントが安定したネットワーク接続を持っていることを確認してください。

        • 次に、「統合フロー」で説明されているように、initWithOptions API 操作を [タイミング 1] で呼び出し、getDeviceToken API 操作を [タイミング 2] で呼び出します。または、initWithOptions と getDeviceToken API 操作の呼び出しの間に少なくとも 3 秒の間隔を確保してください。

    • 呼び出し例

      // bizId を渡す例。bizId は顧客のビジネス ID であり、オプションです。
let bizId = "1234567890abcdef1234567890ab****"
let tokenObj: FaceSecToken = FaceSecDevice.getInstance().getDeviceToken(bizId);
if (tokenObj.code == FaceSecCode.SC_SUCCESS) {
  console.log("Aliyun Token: " + tokenObj.token);
} else {
  console.log("Aliyun Code: " + tokenObj.code);
}

    3. トークンを使用してサーバーにリクエストを送信する

    deviceToken (`FaceSecToken.token`) を取得した後、このパラメーターをビジネスサーバーへのリクエストに含めます。サーバーはこのトークンを使用して結果をクエリおよび検証できます。詳細については、「サーバー側の API 操作」をご参照ください。

    完全なコード例

    import { FaceSecCode, FaceSecToken, FaceSecDevice } from 'aliyunfaceguard';

@Entry
@Component
struct Index {
  @State message: string = 'AliyunFaceGuard';
  @State USER_PRODUCT_KEY: string = "<ビジネスマネージャーに連絡して入手してください>";

  build() {
    Row() {
      Column() {
        Button(this.message)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .onClick((event: ClickEvent) => {
            // SDK を初期化する
            // これはアプリのライフサイクルで一度だけ呼び出す必要があります
            // 統合フローのタイミング 1 で initWithOptions API 操作を呼び出すことをお勧めします
            this.doInit();

            // ここで 2 秒待機して、顔認証フローをシミュレートします
            setTimeout(() => {
              // 統合フローのタイミング 2 で getDeviceToken API 操作を呼び出すことをお勧めします
              this.doGetToken();
            }, 2000);
          })
          .margin({ top: 10 })
      }
      .width('100%')
    }
    .height('100%')
  }

  doInit(): void {
    let options: Map<string, string> = new Map<string, string>();
    options.set("IPv6", "0"); // IPv4 モードに設定
    options.set("DataSwitch", "0"); // init フェーズ中にデータを収集するように設定
    // options.set("CustomUrl", "xxx"); // レポートサイトの URL を設定
    // options.set("CustomHost", "xxx"); // レポートサイトのホストを設定
    FaceSecDevice.getInstance().initWithOptions(getContext(), this.USER_PRODUCT_KEY, options, null);
  }

  doGetToken(): void {
    // bizId を渡す例。bizId は顧客のビジネス ID であり、オプションです。
    let bizId = "1234567890abcdef1234567890ab****"
    let tokenObj: FaceSecToken = FaceSecDevice.getInstance().getDeviceToken(bizId);
    if (tokenObj.code == FaceSecCode.SC_SUCCESS) {
      console.log("Aliyun Token: " + tokenObj.token);
    } else {
      console.log("Aliyun Code: " + tokenObj.code);
    }
  }
}