> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/ja/implement-nfc-wallet/enroll-wallet.md).

# ウォレットを登録する

## 概要

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

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

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

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

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

## シーケンス図

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

<figure><img src="/files/0fa253ec8d2298e1fbd95b09bcad217e6d9ddb4f" alt=""><figcaption><p>ウォレット登録の高レベルフロー。</p></figcaption></figure>

{% hint style="info" %}
このフローは技術的には **ウォレットセキュア登録** 次に **NFC Wallet**.
{% endhint %}

## 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`の場合: 処理はエラーで失敗します。

ウォレット登録が正常に完了したら、次を続行します [カードをトークン化する](/nfc-wallet-sdk-android/ja/implement-nfc-wallet/tokenize-a-card.md).

```java
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](/nfc-wallet-sdk-android/ja/android-api.md) リファレンスで全コード一覧を確認してください。

#### `WalletSecureEnrollmentErrorCodes`

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

{% hint style="info" %}
呼び出します `SDKDataController.wipeAll()` 推奨がSDKのリセットである場合に実行します。
{% endhint %}

<details>

<summary>エラーコード表</summary>

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

</details>

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

で説明されているように [オンボーディング](/nfc-wallet-sdk-android/ja/get-started/configuration/2.-onboarding.md) では、 **アプリケーションバインディングキーを指定する必要があります。**

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

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

{% hint style="warning" %}

### 署名鍵のローテーション / 複数の署名者 <a href="#receive-this-from-the-thales-delivery-team" id="receive-this-from-the-thales-delivery-team"></a>

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

{% hint style="info" %}
**NFC Wallet SDKの以前のバージョンへのダウングレード**

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/ja/implement-nfc-wallet/enroll-wallet.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.