カードのデジタイゼーション状態を取得する

カードのデジタル化状態を取得する

このガイドを使用して、デバイス上の特定のウォレットでカードがすでにデジタル化されているかどうかを判定します。イシュアアプリケーションはこの状態を使用して、次のいずれかを表示するかどうかを判断します ウォレットに追加 または カードを有効化、または両方を非表示にします。

通常、この API は次のタイミングで呼び出します：

• イシュアアプリケーションの起動時、または
• エンドユーザーがカード詳細画面を開いたとき。

プッシュプロビジョニング全体のフローについては、次を参照してください。 デジタルウォレットへのプッシュを実装する.

概要

イシュアアプリケーションは D1 SDK を使用して、モバイルデバイス上のカードのトークン化状態を確認します。返された状態に基づいて、イシュアアプリケーションは UI を更新します：

• DIGITIZED – このデバイス上のウォレットでカードはすでにトークン化されています。次を非表示にします ウォレットに追加 と カードを有効化.
• NOT_DIGITIZED – カードはトークン化されていません。次を表示します ウォレットに追加.
• PENDING_IDV – デジタルカードは作成されていますが、ID&V の完了待ちです。次を表示します カードを有効化 アプリ内認証がサポートされている場合。

注意

• カードがまだ次の状態として表示される場合： NOT_DIGITIZED デジタル化後も、TSP ポータルでイシュアアプリケーションが正しく設定されていることを確認してください。
• Samsung Pay では、一部のイシュアはポータルに複数のイシュア名を登録する必要があります。API で使用するイシュア名がポータルに登録されている名前と一致していることを確認してください。完全一致のみが返されます。次を参照してください。 Samsung FAQ トラブルシューティングのヒント

フロー

プッシュプロビジョニングの前にカードのデジタル化状態を取得するための高レベルのフロー。

シーケンス図

前提条件

• Consumer アカウントとカードは D1 に登録済み
• SDK は正しく初期化されている
• イシュアアプリが D1 SDK のログイン API を呼び出している

ウォレットからカードのデジタル化状態を取得するための高レベルのシーケンス。

プラットフォーム連携

Android

Android では、D1 SDK は次を返します： CardDigitizationState 次を通じて getCardDigitizationState() 選択したウォレット（Google Pay や Samsung Pay など）向けの API。

考えられる状態は次のとおりです：

• DIGITIZED カードはすでにトークン化されています。メッセージや操作は不要です。
• NOT_DIGITIZED 次のいずれかを表示します： Google/Samsung Pay に追加 ボタン。詳細は Google Pay ブランドガイドラインを参照してください。次のステップは、次で説明するようにカードをウォレットにプッシュすることです。 デジタルウォレットにプッシュする.
• PENDING_IDV 次のいずれかを表示します： カードを有効化 イシュアアプリケーションの認証がサポートされている場合はボタン。認証に成功したら、次を呼び出します： activateDigitalCard() デジタルカードを有効化します。

イシュアアプリケーションで利用可能なカード識別子に一致する API を使用します：

• 次を使用 D1PushWallet.getCardDigitizationState(cardID, wallet) cardID がある場合。
• D1 SDK v4.4.0 以降では、次を使用します： PushProvisioningService.getCardDigitizationState(wallet, last4) カードのメタデータなどで下4桁しかない場合。

カード ID を使用

イシュアアプリケーションに次のものがある場合にこの API を使用します： cardID.

// Android バージョン 4.4.0 以降
fun checkCardDigitizationState_v4_4_0(d1Task: D1Task, cardID: String) {
    val pushProvisioningService = d1Task.pushProvisioningService
    val wallet = OEMPayType.GOOGLE_PAY // SAMSUNG_PAY も可
    activity.lifecycleScope.launch {
        try {
            val state = withContext(Dispatchers.IO) {
                pushProvisioningService.getCardDigitizationState(cardID, wallet).await()
            }
            // 状態値に基づいて UI を更新

            // ボタン「Google/Samsung Pay に追加」を非表示
            // ボタン「カードを有効化」を非表示
            when (state) {
                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.NOT_DIGITIZED -> {
                    // ボタン「Google/Samsung Pay に追加」を表示
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.PENDING_IDV -> {
                    // 1. ボタン「カードを有効化」を表示
                    // 2. エンドユーザーを認証
                    // 3. 有効化を実行: d1PushWallet.activateDigitalCard(cardID, wallet, callback)
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.DIGITIZED -> {
                    // ボタン「Google/Samsung Pay に追加」を非表示
                }

                else -> {
                    // 何もしない
                }
            }
        } catch (exception: D1Exception) {
            // D1 SDK Integration – エラー管理のセクションを参照
        }
    }
}

// Android バージョン 4.4.0 未満
fun checkCardDigitizationState_v2_4_0(d1Task: D1Task, cardID: String) {
    val d1PushWallet = d1Task.d1PushWallet
    val wallet = OEMPayType.GOOGLE_PAY // SAMSUNG_PAY も可

    val callback: D1Task.Callback<CardDigitizationState> = object : D1Task.Callback<CardDigitizationState> {

        override fun onSuccess(state: CardDigitizationState) {
            // 状態値に基づいて UI を更新

            // ボタン「Google/Samsung Pay に追加」を非表示
            // ボタン「カードを有効化」を非表示
            when (state) {
                NOT_DIGITIZED -> {
                    // ボタン「Google/Samsung Pay に追加」を表示
                }
                PENDING_IDV -> {
                    // 1. ボタン「カードを有効化」を表示
                    // 2. エンドユーザーを認証
                    // 3. 有効化を実行: d1PushWallet.activateDigitalCard(cardID, wallet, callback)
                }
                DIGITIZED -> {
                    // ボタン「Google/Samsung Pay に追加」を非表示
                }
                else -> {
                    // 何もしない
                }
            }
        }

        override fun onError(exception: D1Exception) {
            // D1 SDK Integration – エラー管理のセクションを参照
        }
    }
    d1PushWallet.getCardDigitizationState(cardID, wallet, callback)
}

下4桁を使用（推奨）

D1 SDK はデバイス上でローカルにデジタル化状態を確認し、ネットワーク呼び出しを必要としません。これによりレイテンシーが低減し、イシュアアプリケーションのパフォーマンスが向上します。

// Android バージョン 4.4.0 以降
fun checkCardDigitizationStateUsingLast4_v4_4_0(d1Task: D1Task, wallet: OEMPayType, last4: String) {
    activity.lifecycleScope.launch {
        try {
            val state = withContext(Dispatchers.IO) {
                d1Task.pushProvisioningService.getCardDigitizationState(wallet, last4).await()
            }
            // 状態値に基づいて UI を更新

            // ボタン「Google/Samsung Pay に追加」を非表示
            // ボタン「カードを有効化」を非表示
            when (state) {
                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.NOT_DIGITIZED -> {
                    // ボタン「Google/Samsung Pay に追加」を表示
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.PENDING_IDV -> {
                    // 1. ボタン「カードを有効化」を表示
                    // 2. エンドユーザーを認証
                    // 3. 有効化を実行: d1PushWallet.activateDigitalCard(cardID, wallet, callback)
                }

                com.thalesgroup.gemalto.d1.pushprovisioning.CardDigitizationState.DIGITIZED -> {
                    // ボタン「Google/Samsung Pay に追加」を非表示
                }

                else -> {
                    // 何もしない
                }
            }
        } catch (exception: D1Exception) {
            // D1 SDK Integration – エラー管理のセクションを参照
        }
    }
}

iOS

iOS では、D1 SDK は次を返します： CardDigitizationResult 次を含むオブジェクト：

• 次 CardDigitizationState、および
• 任意の PKPass オブジェクト（localPKPass と remotePKPass）を使用して、次のようなデバイス固有の情報を表示できます： deviceName.

考えられる状態は次のとおりです：

• デジタル化済み カードはすでにトークン化されています。次を非表示にします Apple Wallet に追加.
• 未デジタル化 次を表示します： PKAddPassButton。この状態は、少なくとも 1 つのデバイス（たとえば iPhone やペアリング済みの Apple Watch）がまだトークン化されていない場合に返されます。
• pendingIDVLocal / pendingIDVRemote トークン化は、電話（pendingIDVLocal）またはウォッチ（pendingIDVRemote）のいずれかで ID&V の完了待ちです。適切な 携帯電話/ウォッチで有効化 ボタンを表示し、イシュアアプリケーションでエンドユーザーを認証してから、次を呼び出します： activateDigitalCard().

イシュアアプリケーションで利用可能なカード識別子に一致する API を使用します：

• 次を使用 D1Task.cardDigitizationState(_:) 次を持っている場合： cardID.
• D1 SDK v4.4.0 以降では、次を使用します： PushProvisioningService.cardDigitizationState(withLast4:) カードのメタデータなどで下4桁しかない場合。

カード ID を使用

import PassKit
let digitizeCardButton = PKAddPassButton()
let activateCardButton = UIButton(type: .system)
let cardID = "" // たとえばサーバーから取得

// iOS バージョン 4.4.0 以降
do {
    let service = try d1Task.pushProvisioningService()
    let result = try await service.cardDigitizationState(cardID)
    // その後のフローを続行します。たとえば UI を更新します
    switch result.state {
    case .pendingIDVLocal:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("携帯電話で有効化 \(result.localPKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // エンドユーザーを認証した後、次のように有効化を実行できます：
        // 4.5.0 以降: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // 4.5.0 より前: self.d1Task.activateDigitalCard(cardID)
    case .pendingIDVRemote:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("携帯電話で有効化 \(result.remotePKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // エンドユーザーを認証した後、次のように有効化を実行できます：
        // 4.5.0 以降: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // 4.5.0 より前: self.d1Task.activateDigitalCard(cardID)
    case .notDigitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = false
    case .digitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = true
    }
} catch let d1Error as D1Error {
    // D1 SDK Integration – エラー管理のセクションを参照
} catch let error {
    // その他のエラーを処理
}

// iOS バージョン 4.4.0 未満
d1Task.cardDigitizationState(cardID) { result, error in
    if let error = error {
        // エラーを処理
    } else if let result = result {
        // その後のフローを続行します。たとえば UI を更新します
        switch result.state {
        case .pendingIDVLocal:
            activateCardButton.isHidden = false
            activateCardButton.setTitle("携帯電話で有効化 \(result.localPKPass?.deviceName ?? "")", for: .normal)
            digitizeCardButton.isHidden = true
            // エンドユーザーを認証した後、次のように有効化を実行できます: self.d1Task.activateDigitalCard(cardID)
        case .pendingIDVRemote:
            activateCardButton.isHidden = false
            activateCardButton.setTitle("携帯電話で有効化 \(result.remotePKPass?.deviceName ?? "")", for: .normal)
            digitizeCardButton.isHidden = true
            // エンドユーザーを認証した後、次のように有効化を実行できます: self.d1Task.activateDigitalCard(cardID)
        case .notDigitized:
            activateCardButton.isHidden = true
            digitizeCardButton.isHidden = false
        case .digitized:
            activateCardButton.isHidden = true
            digitizeCardButton.isHidden = true
        }
    }
}

下4桁を使用（推奨）

D1 SDK はデバイス上でローカルにデジタル化状態を確認し、ネットワーク呼び出しを必要としません。これによりレイテンシーが低減し、イシュアアプリケーションのパフォーマンスが向上します。

import PassKit

let digitizeCardButton = PKAddPassButton()
let activateCardButton = UIButton(type: .system)
let last4 = "" // たとえば cardMetadata API から取得
do {
    let service = try d1Task.pushProvisioningService()
    let result = try await service.cardDigitizationState(withLast4: last4)
    // その後のフローを続行します。たとえば UI を更新します
    switch result.state {
    case .pendingIDVLocal:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("携帯電話で有効化 \(result.localPKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // エンドユーザーを認証した後、次のように有効化を実行できます：
        // 4.5.0 以降: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // 4.5.0 より前: self.d1Task.activateDigitalCard(cardID)
    case .pendingIDVRemote:
        activateCardButton.isHidden = false
        activateCardButton.setTitle("携帯電話で有効化 \(result.remotePKPass?.deviceName ?? "")", for: .normal)
        digitizeCardButton.isHidden = true
        // エンドユーザーを認証した後、次のように有効化を実行できます：
        // 4.5.0 以降: try await d1Task.digitalCardService().activateDigitalCard(cardID)
        // 4.5.0 より前: self.d1Task.activateDigitalCard(cardID)
    case .notDigitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = false
    case .digitized:
        activateCardButton.isHidden = true
        digitizeCardButton.isHidden = true
    }
} catch let d1Error as D1Error {
    // D1 SDK Integration – エラー管理のセクションを参照
} catch let error {
    // その他のエラーを処理
}

D1 SDK の詳細については、次を参照してください。 API リファレンス.