ウォレットを登録する

概要

デジタルウォレットアプリケーションを登録するのは NFC Wallet SDK 初期化後かつ開始前に トークン化.

ウォレット登録では、デジタルウォレットアプリケーションに、使用に必要なセキュリティ資産をプロビジョニングします NFC Wallet サービス:

• これはウォレットインスタンスごとに1回実行します。
• デジタルウォレットアプリケーションが NFC Wallet サービスを使用する場合にのみ実行してください。
• これは対象デバイスでのみ実行してください。

を使用するデジタルウォレットアプリケーションのみを登録してください NFC Wallet サービスを使用する場合にのみ実行してください。

これにより、デジタルウォレットアプリケーションからの不要なネットワーク通信と、への不要な負荷を回避できます NFC Wallet.

シーケンス図

ウォレットアプリケーションを登録するための高レベルのフロー。

ウォレット登録の高レベルフロー。

このフローは技術的には ウォレットセキュア登録 次に NFC Wallet.

SDK 統合

前提条件

開始前に、次の点を確認してください:

• デジタルウォレットアプリケーションがNFC Walletバックエンドにオンボードされていること。
• を初期化しました NFC Wallet SDK.
• ウォレットは登録されていません（下記参照）。

ウォレット登録を実行する

ウォレット登録は、デジタルウォレットアプリケーションのライフサイクルにおける1回限りの処理です。

SDKの初期化後に実行し、ウォレットが登録されていない場合にのみ実行してください。

1. を取得します WalletSecureEnrollmentBusinessService インスタンス。
2. 確認します getState() が返す WSE_REQUIRED.
3. 必要に応じて、 startWalletSecureEnrollment() を呼び出してウォレット登録を開始します。
4. 実装する WalletSecureEnrollmentListener を使用して進行状況を追跡します。

考えられるコールバックは次のとおりです:

• onProgressUpdate 状態が WSE_STARTEDの場合: 処理が開始されます。
• onProgressUpdate 状態が WSE_COMPLETEDの場合: 処理が正常に完了します。
• onErrorの場合: 処理はエラーで失敗します。

ウォレット登録が正常に完了したら、次を続行します カードをトークン化する.

public void performWseIfNeeded() {
    // まず現在の状態を確認します。WSEが本当に必要かどうか。
    final WalletSecureEnrollmentBusinessService wseService 
                = ProvisioningServiceManager.getWalletSecureEnrollmentBusinessService();
    final WalletSecureEnrollmentState state = wseService.getState();

    switch (state) {
        case WSE_COMPLETED:
        case WSE_NOT_REQUIRED:
            // WSEは、現在または以前のインスタンスですでに完了しています。
            break;
        case WSE_STARTED:
            // WSEはこのインスタンス中に開始されました。最初の処理が終わるのを待つだけです。
            return;
        case WSE_REQUIRED:
            // WS登録を開始します。
            wseService.startWalletSecureEnrollment(new WalletSecureEnrollmentListener() {
                @Override
                public void onProgressUpdate(final WalletSecureEnrollmentState wseState) {
                    if (wseState == WalletSecureEnrollmentState.WSE_COMPLETED) {
                        // 成功
                    }
                    else if (wseState == WalletSecureEnrollmentState.WSE_STARTED) {
                        // 開始済み
                    }
                }

                @Override
                public void onError(final WalletSecureEnrollmentError wbDynamicKeyRenewalServiceError) {
                    // エラーをログに記録
                }
            });
            break;
        default:
            // 本来起こるべきではないため、エラーを記録します
            break;
    }
}   

エラーコードの詳細

次のとき WalletSecureEnrollmentListener.onError(...) がトリガーされると、SDKは WalletSecureEnrollmentError.

を提供します。そこには、エラーコードとメッセージに加え、失敗の種類に応じた追加フィールドが含まれます。

解析 WalletSecureEnrollmentError

次のとおりです。 WalletSecureEnrollmentError オブジェクトの構造は次のとおりです：

• SDKエラーコード: この操作のエラー種別。
• CPSエラーコード: CPSモジュール（サーバー側）から返される数値のエラーコード。
• HTTPステータスコード: 通信エラーで返されるHTTPステータスコード。
• メッセージ: 人間が読めるエラーの説明。

エラーは次のように解析する必要があります:

1. 読み取り getSdkErrorCode() を取得するには WalletSecureEnrollmentErrorCodes の値。
2. SDKエラーコードが通信エラーを示す場合（COMM_ERROR）、 getHttpStatusCode().
3. SDKエラーコードがサーバー側エラーを示す場合（SERVER_ERROR）、 getCpsErrorCode().
4. 読み取り getErrorMessage() ログ向けの説明として。
5. SDKエラーコードが DEVICE_SUSPICIOUSの場合は、 getStatusAdditionalInfo() を読み取り、トラブルシューティング用に記録してください。

参照してください WalletSecureEnrollmentErrorCodes の Android API リファレンスで全コード一覧を確認してください。

WalletSecureEnrollmentErrorCodes

再試行、停止、またはSDKのリセットのいずれを行うかを判断するには、次の推奨事項を使用してください。

呼び出します SDKDataController.wipeAll() 推奨がSDKのリセットである場合に実行します。

エラーコード表

エラーコード	発生条件	推奨アクション
WSE_INTERNAL_ERROR	SDK内部エラーが発生します。	ウォレット登録を再試行してください。 問題が続く場合は、SDKをリセットしてください。
COMMON_NO_INTERNET	デバイスにネットワーク接続がありません。	エンドユーザーにネットワークへ接続するよう依頼し、その後ウォレット登録を再試行してください。
COMMON_COMM_ERROR	セキュリティ資産の取得中に通信エラーが発生します。	ウォレット登録を再試行してください。
COMMON_SERVER_ERROR	セキュリティ資産の取得中にサーバー側エラーが発生します。	ウォレット登録を再試行してください。 問題が続く場合は、Thalesのデリバリーチームに連絡して環境設定を検証してください。
RE_ENROLLMENT_REQUIRED	セキュリティ上の理由により再登録が必要です。	SDKをリセットしてから、もう一度ウォレット登録を実行してください。
WSE_STORAGE_ACCESS_ERROR	セキュアストレージへのアクセス時に、SDKが内部の再試行上限を超えます。	SDKをリセットしてから、ウォレット登録を再試行してください。
JSON_PARSING_ERROR	応答データを解析できません。	ウォレット登録を再試行してください。 問題が続く場合は、SDKをリセットしてください。
WSE_REQUEST_ERROR	登録リクエストが失敗します。	ウォレット登録を再試行してください。
WSE_DOWNLOAD_ERROR	セキュリティ資産のダウンロードが失敗します。	ネットワーク接続を確認し、その後ウォレット登録を再試行してください。
WSE_ERROR_INIT_SESSION	WSEセッションの初期化が失敗します（通常は認証関連）。	ウォレット登録を再試行してください。
WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_PACKAGE_NOT_FOUND	パッケージ名を解決できないため、SDKは認証値を計算できません。	オンボーディング設定で使用しているアプリケーションのパッケージ名を確認し、その後ウォレット登録を再試行してください。
WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_CERT_EXCEPTION	アプリケーション署名または公開鍵の問題により、SDKは認証値を計算できません。	オンボーディング設定で使用しているアプリケーションの署名証明書を確認し、その後ウォレット登録を再試行してください。
WSE_CPS_COMPONENT_NOT_INITIALIZED	CPSコンポーネントが初期化される前にウォレット登録が開始されます。	SDKを初期化してから、ウォレット登録を再試行してください。
WSE_MG_COMPONENT_NOT_INITIALIZED	MobileGatewayコンポーネントが初期化される前にウォレット登録が開始されます。	SDKを初期化してから、ウォレット登録を再試行してください。
DEVICE_SUSPICIOUS	SDKがデバイスのセキュリティ脅威を検出します。	フローを停止し、そのデバイスは使用できないことをエンドユーザーに通知してください。 キャプチャして共有してください getStatusAdditionalInfo() Thalesサポートに連絡する際に。
WSE_KCV_ERROR	SDKはダウンロードしたセキュリティ資産の検証に失敗します（KCVチェックに失敗）。	ウォレット登録を再試行してください。

アプリケーションバインディングキー（注意事項）

で説明されているように オンボーディング では、 アプリケーションバインディングキーを指定する必要があります。

アプリケーションバインディングキーが指定されていない、または不正な場合、ウォレット登録は失敗します。

以下の警告と注意事項を確認してください。

署名鍵のローテーション / 複数の署名者

ローテーション証明構造体の最初の署名者の値として最も古い署名鍵が指定されていない場合、ウォレット登録は失敗します

NFC Wallet SDKの以前のバージョンへのダウングレード

NFC Wallet SDKを以前のバージョンにダウングレードするには、アプリケーションはローテーション証明構造体の最初の署名者として最も古い署名鍵が指定されていることを確認する必要があります。