Google Wallet API を使用して Android でパスを作成する

1. はじめに

概要

Google Wallet API を使用すると、ポイントカード、クーポン、ギフトカード、イベント チケット、乗車券、搭乗券など、さまざまなタイプのパスを通じてユーザーに働きかけることができます。各パスタイプ（パスクラス）には、ユースケース固有のフィールドと機能が用意されており、ユーザー エクスペリエンスを向上させることができます。

ただし、すべてのユースケースに適合するとは限りません。よりカスタマイズされたエクスペリエンスを作成するには、汎用パスタイプを使用します。汎用パスタイプのユースケースの例を次に示します。

  • 駐車パス
  • 図書館カード
  • ストアドバリュー型クーポン
  • ジムの会員カード
  • 予約

汎用パスは、次のようなユースケースで使用できます。

  • 最大 3 行の情報
  • （省略可）バーコード グラフィック
  • （省略可）詳細セクション

Google ウォレットに追加のプロビジョニング フローを示す Android デバイス

Google Wallet API の詳細、または Android アプリに [Google ウォレットに追加] ボタンを追加する方法について詳しくは、Google ウォレットのデベロッパー向けドキュメントをご覧ください。

クラスとオブジェクトを渡す

Google Wallet API は、次のものを作成するためのメソッドを公開します。

タイプ

説明

パスクラス

個々のパス オブジェクトのテンプレート。このクラスに属するすべてのパス オブジェクトに共通する情報が含まれます。

パス オブジェクト

ユーザー ID に固有のパスクラスのインスタンスで、

この Codelab について

この Codelab では、次のタスクを行います。

  1. デモモードで新しい発行者アカウントを作成する
  2. パスの発行用のサービス アカウントを作成する
  3. 新しい汎用パスクラスを作成する
  4. 新しいパス オブジェクトを作成する
  5. パスを保存するための [Google ウォレットに追加] ボタンを作成する
  6. Android アプリにボタンを表示する
  7. パスの保存結果を処理する

前提条件

目標

この Codelab を完了すると、次のことができるようになります。

  • Android アプリに Google ウォレット SDK を追加する
  • Android デバイスで Google Wallet API が使用可能かどうかを確認する
  • [Google ウォレットに追加] ボタンを作成する

サポート

Codelab で行き詰まった場合は、google-pay/wallet-android-codelab GitHub リポジトリに完全なソリューションが用意されていますので、参照してください。

2. セットアップ

このステップでは、デモモードで発行者アカウントを作成します。これにより、ユーザーのウォレットに追加できるパスクラスとオブジェクトを作成できます。次に、Google Cloud プロジェクトとサービス アカウントを作成します。これらは、バックエンド サーバーと同じ方法で、プログラムによってパスクラスとオブジェクトを作成するために使用されます。最後に、Google Cloud サービス アカウントに、Google ウォレットの発行者アカウントでパスを管理する権限を付与します。

Google Wallet API 発行者アカウントを登録する

Google ウォレットのパスを作成して配布するには、発行者アカウントが必要です。登録には、Google Pay & Wallet Console を使用します。最初は、デモモードでパスを作成できます。つまり、作成したパスを追加できるのは、特定のテストユーザーのみです。テストユーザーは Google Pay & ウォレット コンソールで管理できます。

デモモードの詳細については、汎用パスの前提条件をご覧ください。

  1. Google Pay & ウォレット コンソールを開きます。
  2. 画面上の手順に沿ってカード発行会社アカウントを作成します。
  3. [Google Wallet API] を選択します。
  4. 利用規約とプライバシー ポリシーを理解していることを確認する
  5. [Issuer ID] の値をテキスト エディタまたは別の場所にコピーします。
  6. [管理] タブで [テスト用アカウントを設定] を選択します。
  7. この Codelab で使用するメールアドレスを追加します。

Google Wallet API を有効にする

  1. Google Cloud コンソールにログインします。
  2. Google Cloud プロジェクトがない場合は、ここで作成します（詳細については、プロジェクトの作成と管理をご覧ください）。
  3. プロジェクトで Google Wallet API（Google Pay for Passes API とも呼ばれます）を有効にする

サービス アカウントとサービス アカウント キーを作成する

Google Wallet API を呼び出すには、サービス アカウントとサービス アカウント キーが必要です。サービス アカウントは、Google Wallet API を呼び出す ID です。サービス アカウント キーには、アプリケーションをサービス アカウントとして識別するための秘密鍵が含まれています。このキーは機密情報であるため、秘密にしてください。

サービス アカウントを作成する

  1. Google Cloud コンソールで [サービス アカウント] を開きます。
  2. サービス アカウントの名前、ID、説明を入力します。
  3. [作成して続行] を選択します。
  4. [完了] を選択します。

サービス アカウント キーを作成する

  1. サービス アカウントを選択します。
  2. [KEYS] メニューを選択します。
  3. [鍵を追加]、[新しい鍵を作成] の順に選択します。
  4. キータイプとして [JSON] を選択します。
  5. [作成] を選択します。

鍵ファイルをローカル ワークステーションに保存するよう求められます。場所を覚えておいてください。

GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定する

GOOGLE_APPLICATION_CREDENTIALS 環境変数は、Google SDK がサービス アカウントとして認証し、Google Cloud プロジェクトのさまざまな API にアクセスするために使用します。

  1. Google Cloud サービス アカウント キーのドキュメントの手順に沿って、GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定します。
  2. 新しいターミナル（macOS/Linux）またはコマンドライン（Windows）セッションで環境変数が設定されていることを確認します（すでにセッションが開いている場合は、新しいセッションを開始する必要があります）。
    echo $GOOGLE_APPLICATION_CREDENTIALS

サービス アカウントを承認する

最後に、Google ウォレット パスを管理する権限をサービス アカウントに付与する必要があります。

  1. Google Pay & ウォレット コンソールを開きます。
  2. [ユーザー] を選択します。
  3. [ユーザーを招待する] を選択します。
  4. サービス アカウントのメールアドレスを入力します（例: test-svc@myproject.iam.gserviceaccount.com）
  5. [アクセスレベル] プルダウン メニューから [開発元] または [管理者] を選択します。
  6. [招待] を選択します。

3. 汎用パスクラスを作成する

このステップでは、パスのベースクラスを作成します。ユーザーに新しいパスが作成されるたびに、パスクラスで定義されたプロパティが継承されます。

この Codelab で作成するパスクラスは、汎用パスの柔軟性を利用して、身分証明書バッジとチャレンジ ポイント トラッカーの両方として機能するオブジェクトを作成します。このクラスからパス オブジェクトが作成されると、次の図のようになります。

パスクラスは、Google Pay & ウォレット コンソールで直接作成することも、Google Wallet API を使用して作成することもできます。この Codelab では、API を使用して汎用パスクラスを作成します。これは、プライベート バックエンド サーバーがパスクラスの作成に使用するプロセスに沿っています。

  1. google-pay/wallet-android-codelab GitHub リポジトリのクローンをローカル ワークステーションに作成します。
    git clone https://github.com/google-pay/wallet-android-codelab.git
  2. ターミナルまたはコマンドライン プロンプトでクローンを作成したリポジトリを開きます。
  3. backend ディレクトリに移動します（これらのスクリプトはバックエンド サーバー アクションを模倣します）。
    cd backend
  4. Node.js 依存関係をインストールする
    npm install .
  5. backend ディレクトリで generic_class.js を開きます。
  6. issuerId の値は、Google Pay & ウォレット コンソールの発行者 ID に置き換えます。
    // TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
  7. ターミナルまたはコマンドライン プロンプトで generic_class.js スクリプトを実行します。
    node generic_class.js

コードが実行されると、新しいパスクラスが作成され、クラス ID が出力されます。クラス ID は、発行者 ID とデベロッパー定義の接尾辞で構成されます。この場合、接尾辞は codelab_class に設定されます（クラス ID は 1234123412341234123.codelab_class に似ています）。出力ログには、Google Wallet API からのレスポンスも含まれます。

4. Android Studio でプロジェクトを開きます。

クローンを作成した GitHub リポジトリには、空のアクティビティを含む Android プロジェクトが含まれています。このステップでは、このアクティビティで編集して、商品ページに [Google ウォレットに追加] ボタンを追加します。

  1. Android Studio を開く
  2. [ファイル]、[開く] の順に選択します。
  3. リポジトリ内の android ディレクトリを選択します。
  4. [開く] を選択します。

アプリに Google ウォレット SDK を追加する

  1. モジュール レベルの Gradle ビルドファイル（android/app/build.gradle）を開きます。
  2. dependencies セクションに Google ウォレット SDK を追加する
    // TODO: Add the "com.google.android.gms:play-services-pay" dependency to
//       use the Google Wallet API
implementation "com.google.android.gms:play-services-pay:16.0.3"
  3. ファイルを保存します。
  4. [File]、[Sync Project with Gradle Files] の順に選択します。

5. [Google ウォレットに追加] ボタンを作成する

このステップでは、[Google ウォレットに追加] ボタンを作成し、既存のアクティビティに追加します。ボタンのアセットはすでにプロジェクトに含まれています。ボタンを含めるには、個別のレイアウト ファイルを作成します。追加すると、ボタンは次のようになります。

[Google ウォレットに追加] ボタン

  1. 新しいレイアウト ファイルを作成します。app/src/main/res/layout/add_to_google_wallet_button.xml
  2. 新しいレイアウト ファイルに次の内容を追加します。
    <?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="48sp"
    android:background="@drawable/add_to_google_wallet_button_background_shape"
    android:clickable="true"
    android:contentDescription="@string/add_to_google_wallet_button_content_description"
    android:focusable="true">
  <ImageView
      android:layout_width="227dp"
      android:layout_height="26dp"
      android:layout_gravity="center"
      android:duplicateParentState="true"
      android:src="@drawable/add_to_google_wallet_button_foreground" />
</FrameLayout>
  3. add_to_google_wallet_button.xml レイアウトを購入手続きアクティビティのレイアウト ファイル（app/src/main/res/layout/activity_checkout.xml）に含める
    <!--
    TODO: Create the button under `add_to_google_wallet_button.xml`
          and include it in your UI
-->
<include
    android:id="@+id/addToGoogleWalletButton"
    layout="@layout/add_to_google_wallet_button"
    android:layout_width="match_parent"
    android:layout_height="48dp"
    android:layout_marginTop="10dp" />

6. Google Wallet API が利用可能かどうかを確認する

Google Wallet API をサポートしていないデバイスでユーザーがアプリを開いた場合、パスを追加しようとすると不快なエクスペリエンスになる可能性があります。ユーザーのデバイスが Google ウォレット API に対応していない場合は、[Google ウォレットに追加] ボタンを非表示にすると、混乱を避けることができます。API を使用できない理由としては、Android または Google Play 開発者サービスのバージョンが古い、ユーザーの国で現在 Google ウォレットが利用できない、などが考えられます。

このステップでは、デバイスで Google Wallet API が使用可能かどうかを確認するロジックをアプリに追加します。有効な場合は、ボタンがアクティビティにレンダリングされます。それ以外の場合、ボタンは非表示になります。

  1. app/src/main/java/com/google/android/gms/samples/wallet/activity/ で CheckoutActivity.kt ファイルを開きます。
  2. PayClient インスタンスのクラス プロパティを作成する
    // TODO: Create a client to interact with the Google Wallet API
private lateinit var walletClient: PayClient
  3. onCreate メソッドで PayClient プロパティをインスタンス化します。
    // TODO: Instantiate the client
walletClient = Pay.getClient(this)
  4. デバイスで Google Wallet SDK と API が使用可能かどうかを確認し、結果を処理するメソッドを作成する
    // TODO: Create a method to check for the Google Wallet SDK and API
private fun fetchCanUseGoogleWalletApi() {
  walletClient
    .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
    .addOnSuccessListener { status ->
      if (status == PayApiAvailabilityStatus.AVAILABLE)
        layout.passContainer.visibility = View.VISIBLE
    }
    .addOnFailureListener {
      // Hide the button and optionally show an error message
    }
}
  5. onCreate メソッドで fetchCanUseGoogleWalletApi メソッドを呼び出して、Google Wallet API が使用可能かどうかを確認する
    // TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()

アプリを実行すると、UI に [Google ウォレットに追加] ボタンが表示されます。

アプリのアクティビティに [Google ウォレットに追加] ボタンが表示される

7. 汎用パス オブジェクトを作成する

Google Wallet API が使用可能であることを確認できたので、パスを作成して、ウォレットに追加するようユーザーに求めるメッセージを表示できます。ユーザーのパス オブジェクトを作成するには、2 つのフローがあります。

バックエンド サーバーでパス オブジェクトを作成する

このアプローチでは、パス オブジェクトがバックエンド サーバーで作成され、署名付き JWT としてクライアント アプリに返されます。ユーザーの利用率が高い場合に適しています。ユーザーがウォレットに追加しようとする前に、オブジェクトが存在することを確認できます。

ユーザーがウォレットにパスを追加したときにパス オブジェクトを作成する

このアプローチでは、パス オブジェクトが定義され、バックエンド サーバーで署名付き JWT にエンコードされます。クライアント アプリに [Google ウォレットに追加] ボタンがレンダリングされ、JWT が参照されます。ユーザーがボタンを選択すると、JWT を使用してパス オブジェクトが作成されます。これは、パス オブジェクトが作成されても使用されないため、ユーザーの利用状況が変動する場合や不明な場合に最適です。このアプローチは Codelab で使用されます。

  1. backend/generic_pass.js ファイルを開きます。
  2. issuerId の値を、Google Pay & ウォレット コンソールの発行者 ID に置き換えます。
    // TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
  3. ターミナルまたはコマンドライン プロンプトで、generic_pass.js ファイルを実行します。
    node generic_pass.js
  4. 出力トークンをクリップボードまたはテキスト エディタにコピーします。

コードが実行されると、新しいパス オブジェクトが定義され、JWT に埋め込まれます。次に、JWT は、前に作成したサービス アカウント キーで署名されます。これにより、Google Wallet API へのリクエストが認証されるため、認証情報をクライアント アプリに保存する必要がなくなります。

本番環境では、バックエンド システムが JWT を作成してクライアントに返します。この Codelab では、generic_pass.js スクリプトがこの動作をエミュレートし、クライアント アプリで使用できるトークンを「返します」。

8. Google ウォレットにパスを追加する

Google Wallet API が使用可能であることを確認して署名付き JWT を作成したので、パスをウォレットに追加するようユーザーにプロンプトを表示できます。このステップでは、[Google ウォレットに追加] ボタンにリスナーを追加します。このリスナーは、Google Wallet API を使用してユーザーのウォレットにパスを保存します。

  1. app/src/main/CheckoutActivity.kt ファイルを開きます。
  2. token の値は、前に作成した JWT に置き換えます。
    // TODO: Save the JWT from the backend "response"
private val token = "TOKEN"
  3. リクエスト コードを格納するクラス プロパティを作成する
    // TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000
  4. [Google ウォレットに追加] ボタンのリスナーを設定する
    // TODO: Set an on-click listener on the "Add to Google Wallet" button
addToGoogleWalletButton = layout.addToGoogleWalletButton.

addToGoogleWalletButton.setOnClickListener {
  walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
}

ユーザーが [Google ウォレットに追加] ボタンを選択すると、walletClient.savePassesJwt メソッドが呼び出されます。このメソッドは、新しいパス オブジェクトを Google ウォレットに追加するようユーザーに求めるプロンプトを表示します。

9. savePassesJwt の結果を処理する

この Codelab の最後のステップでは、walletClient.savePassesJwt オペレーションの結果を処理するようにアプリを構成します。

  1. app/src/main/CheckoutActivity.kt ファイルを開きます。
  2. 次のコードを含めるように onActivityResult メソッドをオーバーライドします。
    // TODO: Handle the result
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

  if (requestCode == addToGoogleWalletRequestCode) {
    when (resultCode) {
      RESULT_OK -> {
        // Pass saved successfully. Consider informing the user.
      }

      RESULT_CANCELED -> {
        // Save canceled
      }

      PayClient.SavePassesResult.SAVE_ERROR ->
        data?.let { intentData ->
          val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
          // Handle error. Consider informing the user.
          Log.e("SavePassesResult", errorMessage.toString())
        }

      else -> {
        // Handle unexpected (non-API) exception
      }
    }
  }
}

これで、アプリは次のシナリオを処理できるようになりました。

  • パスの追加が完了しました
  • お客様からのキャンセル
  • 予期しないエラー

アプリを実行して、パスを追加して結果を想定どおりに処理できることを確認します。

10.完了

汎用パス オブジェクトの例。

これで、Google Wallet API の Android への統合が完了しました。

その他の情報

統合の全体については、google-pay/wallet-android-codelab GitHub リポジトリをご覧ください。

パスを作成し、本番環境へのアクセスをリクエストする

本番環境で独自のパスを発行する準備ができたら、Google Pay & ウォレット コンソールにアクセスして本番環境へのアクセスをリクエストし、Android アプリを承認します。

詳細については、Android SDK の前提条件をご覧ください。