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. 発行者 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 で作成するパス クラスでは、汎用パスの柔軟性を活かし、ID バッジとチャレンジ ポイント トラッカーの両方として機能するオブジェクトを作成します。このクラスからパス オブジェクトを作成すると、次の図のようになります。

パスクラスは、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. チェックアウト アクティビティのレイアウト ファイル（app/src/main/res/layout/activity_checkout.xml）に add_to_google_wallet_button.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 ウォレット 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 にエンコードされます。JWT を参照するクライアント アプリに、[Google ウォレットに追加] ボタンがレンダリングされます。ユーザーがボタンを選択すると、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 へのリクエストが認証されるため、認証情報をクライアント アプリに保存する必要がなくなります。

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

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

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

  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.root

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 の前提条件をご覧ください。