Welcome to our new developer portal! Use the "Ask" button to chat with our AI Agent.
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Apple Wallet拡張機能

Apple Wallet 拡張機能

Apple Wallet 拡張機能を使用すると、イシュアアプリケーションに加えて、エンドユーザーが Apple Wallet アプリケーションから直接カードを検出してプロビジョニングできるようになります。

アプリケーション拡張を介して、イシュアアプリケーションの外部でカスタム機能やコンテンツを公開し、エンドユーザーが Apple Wallet やシステムとやり取りしている間にそれらを利用できるようにできます。

Apple Wallet アプリケーション内でのカードのプロビジョニングは、支払いカードの詳細を手動で入力する必要を回避することで、アプリ内の体験を向上させます。

次を参照してください Apple 拡張機能の概要 iOS 拡張機能に関する一般情報については。

ユーザーエクスペリエンス

エンドツーエンドの Apple Wallet 拡張フローには主に 2 つのフェーズがあります:

  1. Apple Wallet はイシュアアプリケーションにプロビジョニング可能なカードがあることを検出します。

  2. エンドユーザーが認証して追加するカードを選択すると、Apple Wallet は D1 SDK を介してイシュアアプリケーションからプロビジョニングペイロードを要求します。

検出と認証

Apple Wallet showing issuer application option for adding a card
カードがプロビジョニング可能な場合、Apple Wallet はイシュアアプリケーションをオプションとして表示します。
1

Apple Wallet でイシュアアプリケーションを検出する

Apple Wallet はイシュアアプリケーションにカードが利用可能かどうかを確認します。カードが利用可能な場合、イシュアアプリケーションがオプションの一覧に表示されます。

2

エンドユーザーがイシュアアプリケーションを選択する

エンドユーザーがイシュアアプリケーションを選択すると、Apple Wallet はイシュアアプリケーションの UI 拡張をトリガーしてエンドユーザーを認証します。

3

エンドユーザーを認証する

イシュアアプリケーションの UI 拡張は、メインのイシュアアプリケーションと同じ認証情報と方法(例えば、手動ログインや生体認証)を使用してエンドユーザーを認証します。

カードの選択とプロビジョニング

Apple Wallet showing available cards from the issuer application
Apple Wallet はイシュアアプリケーションから利用可能なカードを取得して表示します。
1

Apple Wallet が利用可能なカードを取得する

Apple Wallet は非 UI 拡張を通じてイシュアアプリケーションに利用可能なカードの一覧を要求します。エンドユーザーは追加するカードの一覧を確認できます。

2

カード詳細を表示する

エンドユーザーはカードを追加する前にカードの詳細(例えば、カードデザイン、商品タイトル、下4桁)を確認できます。

3

利用規約に同意する

エンドユーザーはイシュアおよび決済ネットワークの利用規約を確認して同意します。

4

プロビジョニングペイロードとトークン化

選択された各カードについて、Apple Wallet はイシュアアプリケーションからプロビジョニングペイロードを要求し、その後決済ネットワーク TSP とともにトークン化フローを開始します。

拡張機能

Apple Wallet 統合には、イシュアアプリケーションから 2 種類の拡張機能が必要です:

  • 非 UI 拡張 拡張フローとカードの可用性のステータスを報告します。これはカードの検出およびプロビジョニングペイロードのステップをカバーします。D1 SDK のベースクラスを拡張して実装されます D1IssuerProvisioningExtensionHandler.

  • UI 拡張 エンドユーザーを認証します。これはイシュアアプリケーションと同じログイン認証情報を使用する別の画面です。次を実装します D1IssuerProvisioningExtensionAuthorizationProviding プロトコル。

Apple Wallet 拡張機能はイシュアアプリケーションと同時にインストールされます。Apple Wallet が追加可能なパスを検出して拡張機能を表示するには、エンドユーザーが少なくとも一度イシュアアプリケーションを起動する必要があります。

D1 SDK は非 UI 拡張のためのベース実装を提供するため、完全なロジックを自身で実装する必要はありません。イシュアアプリケーションは次を呼び出します D1Task.configure() とともに WalletExtensionConfig アプリケーション起動時に拡張機能とカード詳細を共有するために。インストール後にこの構成は一度だけ必要ですが、カード情報を最新に保つために毎回のアプリ起動時に呼び出すことを推奨します。

High-level flow for configuring the Apple Wallet extension via D1 SDK
ハイレベルフロー: イシュアアプリケーションが D1 SDK を構成して Apple Wallet がカードを検出できるようにします。

UI 拡張での認証が成功した後、イシュアアプリケーションは次を呼び出す必要があります D1IssuerProvisioningExtensionAuthorizationProviding.login() SDK が非 UI 拡張のステップを続行できるようにするためです。

シーケンス図

1. Apple Wallet がイシュアアプリケーションのボタンを表示する

Sequence diagram showing how Apple Wallet discovers the issuer application
Apple Wallet はイシュアアプリケーションにプロビジョニング可能なカードがあることを検出します。

2. エンドユーザーの認証

Sequence diagram showing Apple Wallet triggering issuer UI extension for authentication
Apple Wallet は認証のためにイシュアアプリケーションの UI 拡張を起動します。

3. 利用可能なカードが表示される

Sequence diagram showing Apple Wallet requesting card list from issuer
Apple Wallet は利用可能なカードの一覧を要求してエンドユーザーに表示します。

4. トークン化

Sequence diagram showing Apple Wallet requesting provisioning payload and tokenizing
Apple Wallet はプロビジョニングペイロードを要求し、選択されたカードをトークン化します。

D1 SDK を介して Apple Wallet を統合する

SDK 構成

次を実行するとき iOS SDK の初期化イシュアアプリケーションは次も呼び出す必要があります configure(ConfigParams.walletExtensionConfig(...)) および次を提供します:

cardParamsList

単一の consumerId および単一の issuerId:

  • cardParamsList を持つ場合にこのバリアントを使用します – カード ID、カードデザイン、商品タイトル、および下4桁の一覧。カードデザインと商品タイトルは Apple Wallet に表示されます。

  • appGroupID – D1 SDK がイシュアアプリケーションとその拡張機能の間でデータを共有できるようにする共有コンテナ ID。

issuerParamsList

複数の組み合わせの issuerId および consumerId:

  • issuerParamsList をサポートする場合はこのバリアントを使用します – 一覧 cardParamsList と対応する issuerId および consumerId.

  • appGroupID – D1 SDK がイシュアアプリケーションとその拡張機能の間でデータを共有できるようにする共有コンテナ ID。

次の使用を強く推奨します last4 パラメータ。

なしでは last4SDK は共有デバイスのシナリオでトークン化の状態を誤解する可能性があります。例えば、ユーザー A がカードをトークン化し、その後同じデバイスでユーザー B が同じイシュアアプリケーションにログインした場合、SDK は誤ってユーザー B のトークン化が既に完了していると判断するかもしれません。

App Group ID

デフォルトでは、イシュアアプリケーションとその拡張機能はストレージを共有しません。app group を使用してそれらの間でストレージを共有してください。詳細は次を参照してください。 Apple 拡張機能の概要 より詳しい情報。

appGroupID はイシュアアプリケーションとその拡張機能の間の共有コンテナを識別します。Xcode の次の設定で構成します Capabilities.

Xcode configuration for app groups used by issuer application and extensions
イシュアアプリケーションとその拡張機能のために Xcode で app group を構成する例。

を使用する前に App Group ID が正しく Xcode に追加されていることを確認してください。 configure(ConfigParams.walletExtensionConfig(...))そうしないと、D1 SDK は次のエラーを返します invalidAppGroupID エラー。

Apple Pay 権限(entitlement)

アプリ内の Apple Pay プロビジョニングと同様に、UI と非 UI 拡張ターゲットの両方に次の権限を追加する必要があります com.apple.developer.payment-pass-provisioning オンボーディングの詳細については、Apple Wallet のプロビジョニングドキュメントまたは次を参照してください ウォレット向けプッシュプロビジョニングのオンボーディング.

UI 拡張

UI 拡張を作成する

Xcode dialog for creating an intents UI extension
Apple Wallet の UI 拡張用に Xcode で Intents UI Extension ターゲットを作成します。
1

Xcode に新しいターゲットを追加し、タイプを次に設定します Intents UI Extension.

2

新しいターゲットでは、イシュアアプリケーションと同じ App Group ID と権限の値を有効にします。App Group ID が異なる場合、 login API は次を返します walletExtensionAppGroupIDNotFound エラー。

3

拡張機能の Info.plist を更新する 次を設定します:

  • NSExtensionPointIdentifier 設定します com.apple.PassKit.issuer-provisioning.authorization.

  • NSExtensionPointIdentifier NSExtensionPrincipalClass に、次に準拠するクラスを設定します D1IssuerProvisioningExtensionAuthorizationProviding.

例: 権限と拡張機能の構成:

UI 拡張のために SDK を統合する

D1 SDK は次の D1IssuerProvisioningExtensionAuthorizationProviding プロトコルを提供します。これは Apple の PKIssuerProvisioningExtensionAuthorizationProviding を拡張し、次の login API を追加します。

UI 拡張では、次に準拠するビューコントローラを実装し、エンドユーザーを認証して、を呼び出します D1IssuerProvisioningExtensionAuthorizationProvidingD1 のアクセス トークン(例えばバックエンドからの JWT)を使用して。 login トークン生成についてはあなたの SDK のログイン ドキュメントを参照してください。

単一の issuerId でログインする

複数の issuerIds でログイン

カードが同じ issuerId を共有するが、異なる consumerId 値を持つ場合、単一の issuerToken を生成する そのための issuerId.

非 UI 拡張

非 UI エクステンションを作成する

Xcode dialog for creating an intents extension without UI
Apple Wallet の非 UI エクステンション用に Xcode で Intents Extension ターゲットを作成します。
1

Xcode に新しいターゲットを追加し、タイプを次に設定します Intents Extension. クリア UI エクステンションを含める 以前に UI エクステンションが作成されているため。

2

新しいターゲットでは、イシュアアプリケーションと同じ App Group ID と権限値を有効にします。App Group ID が異なると、D1 SDK の操作は walletExtensionAppGroupIDNotFound エラー。

3

拡張機能の Info.plist を更新する 次を設定します:

  • NSExtensionPointIdentifier 設定します com.apple.PassKit.issuer-provisioning.

  • NSExtensionPointIdentifier NSExtensionPrincipalClass を拡張するクラスへ D1IssuerProvisioningExtensionHandler.

例: 権限と拡張機能の構成:

非 UI エクステンション向けに SDK を統合する

D1 SDK は基底クラスを提供します D1IssuerProvisioningExtensionHandler、これは Apple の PKIssuerProvisioningExtensionHandler を拡張し、必要な API を実装します。ほとんどの場合、このクラスを拡張するだけで済みます。

エラー処理

オプションで、 errorEncountered(_:) を非 UI エクステンションでオーバーライドして、エクステンションフロー中に受け取ったエラーをログまたは追跡できます。

典型的なエラーケースには次のものが含まれます:

  • The appGroupID は無効であるか見つかりません。

  • D1 バックエンドがエラーを返します。

Apple の機能要件

Apple の機能要件に合わせるため、D1 SDK D1IssuerProvisioningExtensionHandler とイシュアアプリケーションは次の慣行を採用します:

  • カードデザインとカード所有者の名前を表示する。

  • Apple が API を呼び出してから 100 ms 以内にカードが利用可能かどうか(有効性)を判断する。

  • カードデザインとアプリアイコンは角が四角のものを提供する。

  • UI エクステンションでの認証には手動ログインと生体認証の両方をサポートする。

FAQ

イシュアアプリケーションは、エンドユーザーがログインする前に Apple Wallet にカードの利用可能性をどのように提供できますか?

エンドユーザーは少なくとも一度イシュアアプリケーションにログインする必要があります。そうすることでエクステンションはカードの状態で更新できます。イシュアアプリケーションは configure(ConfigParams.walletExtensionConfig()) を呼び出して D1 SDK にカードのリストを提供します。

ログインに失敗した場合、エラーはどこに表示されますか?

ログインエラーは UI エクステンションのログイン画面に直接表示することを推奨します。UI エクステンションはイシュアアプリケーションのログインと同じ UX ガイドラインに従うべきです。

カード画像のサイズと解像度の要件は何ですか?

デジタルカード画像は Apple の機能要件に従うべきです:

  • PNG(推奨)またはベクタ PDF として画像を提供する。

    • ウォレットエクステンションはメインアプリよりも厳しいメモリ制限があります。

    • PDF ファイルは OS がそれらを PNG に変換するためメモリ使用量を増やします。

  • 解像度は 1536 × 969 を使用してください。

  • 画像サイズが 4 MB 未満であることを確認してください。

  • 角は丸めず四角(角が丸いものではない)を使用してください。

  • 物理カード専用の要素(例:PAN、エンボス文字、ホログラム、チップ接点)を除外してください。

  • 横向きの向きを使用してください。物理カードが縦向きの場合は横向きに再配置してください。

  • NFC 支払いがサポートされている場合は、オプションでコンタクトレスインジケータを追加してください。

エクステンションには新しいバンドル識別子が必要ですか?

はい。新しいバンドル識別子は必ず associatedApplicationIdentifier に支払ネットワークオペレータ(PNO)によって含まれている必要があります。iOS はワイルドカードのバンドル識別子をサポートします。

イシュアは PNO API を使用して Apple Wallet 内の既存のパスも更新する必要があります。バンドル ID が含まれていない場合、Apple Wallet エクステンションを通じて追加されたカードはイシュアアプリケーションからアクセスできません(例:デジタル化状態の確認など)。

イシュアアプリのアイコンが Apple Wallet に表示されない場合、何が問題でしょうか?

次を確認してください:

  • イシュアアプリがインストールされ、少なくとも一度開かれている。

  • イシュアアプリケーションが configure(ConfigParams.walletExtensionConfig()) を呼び出してカードリストを更新している。

  • イシュアアプリケーションと両方のエクステンションが同じ appGroupIDconfigure(ConfigParams.walletExtensionConfig()) と Xcode の機能で使用している。

Apple Wallet エクステンションを動作させるためにアプリ内プロビジョニングは必要ですか?

はい。イシュアアプリケーションは Apple Wallet エクステンションを追加する前に、まずウォレットへのアプリ内プッシュプロビジョニングを実装する必要があります。

最終更新

役に立ちましたか?