デジタルカードを表示する

概要

の後、 トークン化、あなたの デジタルウォレットアプリケーション 表示する必要があります エンドユーザー そのデジタルカード。

一覧表示と詳細表示を提供します。

カードのステータス、カードアート、メタデータを使用して UI を構成します。

SDK 連携

使用する DigitalizedCardManager

の後、 トークン化 完了したら、 DigitalizedCardManager にアクセスするために NFC Wallet SDK 永続データにアクセスしてデジタルカードを取得します。

DigitalizedCardManager 非同期呼び出しとブロッキング呼び出しをサポートします:

• AsyncHandler：コールバックで結果を受け取ります。

• AsyncToken：処理が完了するまで呼び出し元スレッドをブロックします。

AsyncToken 呼び出し元スレッドをブロックします。UI スレッドでは使用しないでください。

カード一覧を取得

の後、 トークン化 完了したら、 DigitalizedCardManager.getAllCards() すべての トークン化されたカード ID.

識別子の違いについては、 トークン化されたカード ID とデジタルカード ID の違い.

以下の例では、を使用してトークン化されたカード ID を取得する方法を示します AsyncHandler と AsyncToken.

AsyncHandler

AsyncHandler を使用してトークン化されたカード ID を取得する

// UI スレッドでの作業を避けるため、HandlerThread をインスタンス化します。
val cardDisplayThread = HandlerThread("getAllCards")
cardDisplayThread.start()

val looper = cardDisplayThread.looper

val handler = object : AbstractAsyncHandler<Array<String>>(looper) {
    override fun onComplete(result: AsyncResult<Array<String>>) {
        if (result.isSuccessful) {
            val tokenizedCardIds = result.result
            // TODO: カードを表示する
        } else {
            // TODO: エラー処理
        }
    }
}

DigitalizedCardManager.getAllCards(handler)

AsyncToken

AsyncToken を使用してトークン化されたカード ID を取得する

val token = DigitalizedCardManager.getAllCards(null)
val result = token.waitToComplete()

if (result.isSuccessful) {
    val tokenizedCardIds = result.result
    // UI にカードを表示する
} else {
    // エラーを処理する
}

トークン化されたカード ID とデジタルカード ID の違い

DigitalizedCardManager 次を使用してカードを一覧表示し、取得します トークン化カード ID.

DigitalizedCard.getTokenizedCardID() は トークン化されたカード ID を返します。

この識別子は、次とは異なります。 デジタルカード ID.

この NFC Wallet SDK は、同じカードに対して 2 つの識別子を使用します:

• トークン化されたカード ID：セキュアなプロビジョニング中に生成されます。CPS トークン ID とも呼ばれます。参照： プロビジョニングをトリガーする.

• デジタルカードID: デジタル化時に生成されます。MGカードIDとも呼ばれます。参照 カードをデジタル化する.

識別子を変換するには、次のヘルパーメソッドを使用します:

• DigitalizedCardManager.getDigitalCardId(): トークン化されたカードIDからデジタルカードIDを取得します。

• DigitalizedCardManager.getTokenizedCardId(): デジタルカードIDからトークン化されたカードIDを取得します。

TSPは独自のデジタルカード識別子も提供します。

で取得します カードメタデータ.

TSP（VTS/MDES）でトラブルシューティングする際に使用します。

この識別子は、トークン化されたカードIDおよびデジタルカードIDとは異なります。

デジタルカード情報を取得する

使用する DigitalizedCard

DigitalizedCard デジタル化されたカードを表し、次のようなカードデータを公開します:

• DigitalizedCardStatus

  • カード状態: ACTIVE, SUSPENDED

  • 支払いキーのステータス: 補充の必要性を検出するために使用します。

• DigitalizedCardDetails

  • getLastFourDigits() : FPANの下4桁。

  • getLastFourDigitsOfDPAN() : DPANの下4桁。

  • getPANExpiry() : FPANの有効期限。

  • getScheme(): 決済ネットワーク（Visa、Mastercard、PURE）。

• DigitalizedCard.getPaymentAccountReference()

  • 主たる非接触カードのPayment Account Reference（PAR）。

取得する DigitalizedCard から DigitalizedCardManager を使用して トークン化カード ID.

// DigitalizedCardインスタンスを取得
val digitalizedCard = DigitalizedCardManager.getDigitalizedCard(tokenizedCardId)

// カード状態を取得
val statusToken = digitalizedCard.getCardState(null)
val statusResult = statusToken.waitToComplete()

if (statusResult.isSuccessful) {
    val status = statusResult.result
    
    // カード状態にはACTIVEとSUSPENDEDが含まれます
    // ACTIVE: カードは支払いに使用できます
    // SUSPENDED: カードは支払い前に有効化が必要です
    val state = status.state
    
    // 支払いキー情報
    val numberOfPaymentsLeft = status.numberOfPaymentsLeft
    val needsReplenishment = status.needsReplenishment()
    val expiryDate = status.expiryDate // LUKの有効期限（SUKではnull）
}

// カード詳細を取得
val detailsToken = digitalizedCard.getCardDetails(null)
val detailsResult = detailsToken.waitToComplete()

if (detailsResult.isSuccessful) {
    val details = detailsResult.result
    
    // カードのメタデータ
    val lastFourDigits = details.lastFourDigits // FPAN の下4桁
    val lastFourDigitsOfDPAN = details.lastFourDigitsOfDPAN // DPAN の下4桁
    val panExpiry = details.panExpiry // FPAN の有効期限
    val scheme = details.scheme // 決済ネットワーク: Visa、Mastercard、PURE
}

// 主要カードの PAR を取得します
try {
    val paymentAccountReference = digitalizedCard.paymentAccountReference
    // 非接触データが利用できない場合、または PAR が存在しない場合は null を返します
} catch (e: InternalComponentException) {
    // エラーを処理する
}

補助カード情報を取得する

カードがコブランドの場合は、以下から追加のプロパティを取得できます DigitalizedCard:

• DigitalizedCard.hasAuxiliaryScheme()：返します true カードに補助スキームがある場合。

• DigitalizedCardDetails

  • getAuxiliaryLastFourDigitsOfDPAN() : 補助 DPAN の下4桁。

  • getAuxiliaryScheme() : 補助カードの決済ネットワーク。

• DigitalizedCard.getAuxiliaryPaymentAccountReference(): 補助の非接触カードの Payment Account Reference (PAR)。

カードがコブランドでない場合、これらのプロパティは null.

// カードに補助スキームがあるか確認します
val hasAuxiliaryScheme = digitalizedCard.hasAuxiliaryScheme()

if (hasAuxiliaryScheme) {
    // 補助カードの詳細を取得
    val detailsToken = digitalizedCard.getCardDetails(null)
    val detailsResult = detailsToken.waitToComplete()
    
    if (detailsResult.isSuccessful) {
        val details = detailsResult.result
        
        // 補助スキーム情報
        val auxiliaryScheme = details.auxiliaryScheme // 補助決済ネットワーク
        val auxiliaryLastFourDigitsOfDPAN = details.auxiliaryLastFourDigitsOfDPAN // 補助 DPAN の下4桁
    }
    
    // 補助の支払いキー情報を取得
    val statusToken = digitalizedCard.getCardState(null)
    val statusResult = statusToken.waitToComplete()
    
    if (statusResult.isSuccessful) {
        val status = statusResult.result
        
        // 補助カードの残り支払い回数
        val auxiliaryNumberOfPaymentsLeft = status.auxiliaryNumberOfPaymentsLeft
    }
    
    // 補助カードの PAR を取得
    try {
        val auxiliaryPaymentAccountReference = digitalizedCard.auxiliaryPaymentAccountReference
        // 次の場合は null を返します:
        // - カードに補助スキームがない
        // - 非接触データが利用できない
        // - 非接触データに PAR がない
    } catch (e: InternalComponentException) {
        // エラーを処理する
    }
}

// 注: カードがコブランドでない場合、補助プロパティは null を返します

カードメタデータ

使用する MGCardEnrollmentService.getCardMetaData() および デジタルカード ID を使って、次のようなカードのメタデータを取得します:

• TSP イシュア名

• TSP ID (VTS、MDES、または他の識別子)

• PAR (payment account reference)

• TSP デジタルカード ID (tokenId)

すべてのフィールドを網羅するには、SDK API リファレンスを参照してください。

TSP デジタルカード ID (tokenId) は次に対応します:

• マスターカード（MDES）： トークンの一意参照

• Visa（VTS）: トークン参照ID

カードアート

使用する MobileGatewayManager.getCardArt() および デジタルカード ID 取得するには カードアート.

使用する CardArt.getBitmap() これらの画像を取得するには:

• 金融機関_ロゴ: イシュアのロゴ

• CARD_BACKGROUND: カードの背景

• CARD_BACKGROUND_COMBINED: カードの背景と決済ネットワークを組み合わせたもの

• CARD_ICON: カードアイコン

カードアートの取得はネットワークリクエストを発生させます。パフォーマンスを向上させるため、デジタルウォレットアプリケーション内で画像をキャッシュしてください。

サンプルアプリケーションでは、シンプルなローカルキャッシュの方法を示しています：

カードアートをローカルにキャッシュする

fun getCardArt(context: Context, digitalCardId: String) {
    // まず、画像がローカルにすでにあるか確認する
    val imageBytes = readFromFile(context, digitalCardId)
    if (imageBytes.isNotEmpty()) {
        val image = BitmapDrawable(
            context.resources,
            BitmapFactory.decodeByteArray(imageBytes, 0, imageBytes.size)
        )
        // キャッシュされた画像をUIで使用する
        return
    }

    // バックエンドからカードアートデータをダウンロードする
    val gatewayManager = MobileGatewayManager.INSTANCE
    try {
        val cardArt = gatewayManager.getCardArt(digitalCardId)
        cardArt.getBitmap(
            CardArtType.CARD_BACKGROUND_COMBINED,
            object : MGAbstractAsyncHandler<CardBitmap>() {
                override fun onComplete(result: MGAsyncResult<CardBitmap>) {
                    if (result.isSuccessful) {
                        val value = result.result
                        // 将来の使用のためにデータを保存
                        writeToFile(context, digitalCardId, value.resource)
                        val image = BitmapDrawable(
                            context.resources,
                            BitmapFactory.decodeByteArray(
                                value.resource,
                                0,
                                value.resource.size
                            )
                        )
                        // ダウンロードした画像をUIで使用します
                    }
                }
            }
        )
    } catch (exception: NoSuchCardException) {
        // エラーを処理します - カードが見つかりません
    }
}