APIでパーソナライズされたウォレットパスを発行する方法

ウォレットパスAPIを使うと、自社のバックエンドから顧客ごとに氏名、残高、バーコード、場所を入れたパスを作成し、データが変わるたびに更新できます。テンプレートを一度デザインし、ユーザーごとの個別の値を送れば、Apple Wallet用のインストールリンクまたはGoogle Wallet用の保存リンクが返ってきます。

すべてのチームにAPIが必要なわけではありません。この記事の例ではPushwooshのWallet passes APIを使います。各パスはUser IDにひも付き、同じUser IDでプッシュ通知、メール、カスタマージャーニーも動きます。API優先で設計されているため、ポイント台帳や会員基盤を自社で持つ日本のECアプリ、小売アプリ、金融アプリでも、既存システムに組み込みやすい構成です。

APIがビルダーより向いているケース

ビルダーは、パスのデザインや、小規模な配布、単発の配布に向いています。パスの内容が自社システムのデータに依存するようになったら、APIの出番です。

コードを書く前に、ジャーニーの列を確認してください。トリガーがPushwooshですでに計測している顧客行動であれば、Customer JourneyのIssue Wallet Pass（ウォレットパスの発行）ステップだけで済み、独自のコードが不要になることも少なくありません。

テンプレートと個別の値

仕組みは両プラットフォームで共通です。テンプレートにはレイアウト、ブランディング、フィールド構成を持たせます。発行時に、ユーザーごとの値でテンプレートを埋めます。

個別の値とは、顧客ごとに変わる情報です。氏名、会員番号、ポイント、会員ランク、バーコードの値、有効期限、最寄りの店舗などです。それ以外はすべてテンプレートから来るため、デザインを変更しても連携部分に手を入れずに、新しく発行するすべてのパスに反映されます。

ジャーニーでは、Issue Wallet PassステップにAppleとGoogleのパスキャンペーン（apple_campaign_id、google_campaign_id）と、埋め込むpersonal_valuesを指定します。1つのステップで、同じUser IDに両方のバージョンを発行できます。

Apple Walletのフロー

Appleのパスビルダーでできることは、すべてApple Wallet PassKit APIでも行えます。パスの作成、更新、一覧取得、ダウンロード、削除です。

典型的な連携は4つのステップで構成されます。

アプリケーションごとにPass Type ID証明書（.p12）と、Apple Developerアカウント（年額99ドル）が必要です。設定方法はiOS Wallet passの設定ドキュメントをご覧ください。iPhoneの利用率が高い日本市場では、まずこのAppleのフローから固めるのが現実的です。

Google Walletのフロー

Google Wallet APIは、Googleのパスについて同じライフサイクルをカバーします。

Google Pay & Wallet ConsoleのIssuer IDが必要で、発行者にPushwooshのサービスアカウントを招待しておきます。設定はアプリケーションごとに一度だけです。手順はGoogle Walletの設定ドキュメントに記載されています。

大規模に更新する

APIの真価が発揮されるのは更新です。ポイント台帳や予約システムが、値が変わった瞬間にパスを更新できるため、顧客のWalletにあるカードは常に自社の正しいデータと一致します。

大量の更新を安全に行うための3つのルールがあります。

• 現在のパスから始める。 Appleの更新はパスオブジェクト全体を受け取るため、パスを取得し、変わった値だけを変更します。Googleの更新はオブジェクトの部分的な変更（パッチ）です。
• 通知はフィールドごとに決める。 Appleでは、変更メッセージのあるフィールドだけがロック画面に通知を表示します。Googleでは、notifyOnUpdateでGoogle独自の通知を依頼できますが、通知が出るのはポイントカード、イベントチケット、搭乗券のパスだけで、1枚のパスにつき24時間で最大3件です。notifyMessageを使えば、どのパスタイプでも独自のAndroid通知テキストを送れます。
• 通知はパスに関する内容に限る。 AppleとGoogleが許可しているのはパスに関する通知であり、販促ではありません。

コードサンプル

どちらのAPIも、ベースURLはhttps://apple-passkit.svc-nue.pushwoosh.comで、Authorization: Token <api-token>ヘッダーにPushwooshのAPIアクセストークンを指定します。以下のリクエストボディは、APIリファレンスに掲載されている例です。

Apple Walletパスを作成する： POST /api/pass/create。レスポンスでパスのserialNumberが返されます。

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Google Walletパスを作成する： POST /api/google/pass/create。レスポンスでserialNumberとsaveLinkが返されます。

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

更新するには、シリアル番号を指定して新しい内容を送ります。AppleはPOST /api/pass/update/{serialNumber}、GoogleはPOST /api/google/pass/update/{serialNumber}です。

ビルダー、API、ジャーニー：使い分けの目安

デザインとテストにはビルダーを使います。会員登録や初回購入など、トリガーがすでにPushwooshにある顧客イベントであれば、ジャーニーのステップを使います。トリガーやデータが自社のバックエンドにある場合は、APIを使います。

多くのチームは最終的に3つすべてを使います。それで問題ありません。デザインはビルダー、ライフサイクルの節目はジャーニー、リアルタイムの残高やステータスはAPIです。失敗するのは、1つの手段にほかの役割まで無理に担わせたときです。

Pushwooshですべてのパスを大規模にパーソナライズする

Pushwooshは、ネイティブのApple WalletパスとGoogle Walletパスのためのビジュアルビルダー、ジャーニーのステップ、APIを提供します。間にパス専用のベンダーを挟む必要はありません。各パスはプッシュ通知、アプリ内メッセージ、メール、SMSと同じUser IDを共有するため、1つのデータですべてのチャネルを動かせます。ISO 27001:2022とSOC 2 Type 2の認証、GDPR準拠、EUと米国のデータセンターといった情報は、情報システム部門の審査資料としてそのまま提示できます。

大規模なパーソナライズに必要なのは、テンプレートを増やすことではありません。すべてのWalletのすべてのカードに反映される、1つの正しいデータです。

FAQ