概要

パートナーは、Google Wallet Passes API を使用して、交通機関のチケットを有効にするエンドポイントを指定できます。有効化が必要な場合は、[有効化] ボタンが表示されます。このボタンをタップすると、下記のパラメータで指定されたエンドポイントが呼び出されます。エンドポイントは、パスに有効なクーポン情報（バーコードまたは目視検査）が含まれていることを確認してから戻ります。エンドポイントが戻ると、ユーザーのウォレット内のパスが更新され、クーポン情報が表示されます。有効化の前に、既存のクーポン情報が表示されることはありません。

有効化 API

有効化エンドポイントは、交通機関クラスで activationOptions を使用して API で指定されます。パートナーは、有効化エンドポイントが適切な遅延で機能するよう維持する責任を負います。

  activationOptions: {
    activationUrl: string
  }

項目説明

項目	説明
`activationUrl`	`string` 有効化リクエスト時に呼び出されるパートナーエンドポイントの URL。URL は HTTPS でホストする必要があります。また、UserAgent:Google-Valuables によって URL パスにアクセスできるよう robots.txt を設定する必要があります。

activationUrl

string

有効化リクエスト時に呼び出されるパートナーエンドポイントの URL。URL は HTTPS でホストする必要があります。また、UserAgent:Google-Valuables によって URL パスにアクセスできるよう robots.txt を設定する必要があります。

有効化の状態は、activationStatus フィールドを使用してオブジェクトに保存されます。有効なステータスには NOT_ACTIVATED と ACTIVATED があります。有効化エンドポイントはオブジェクトのステータスを ACTIVATED に更新するとともに、バーコードや目視検査のパラメータなどの有効なクーポン情報がオブジェクトに含まれていることを確認する必要があります。deviceContext フィールドはデバイスの固定に使用できます。

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean

項目説明

項目	説明
`activationStatus`	`enum (ActivationStatus)` この交通機関オブジェクトの有効化ステータス。このステータスによってチケットの表示が変更され、ユーザーが対処できるようになります。たとえば、このステータスが `NOT_ACTIVATED` に設定されている場合、チケットの詳細に [有効化] ボタンがレンダリングされます。有効な値は次のとおりです。 `NOT_ACTIVATED` `ACTIVATED`
`deviceContext`	`object (DeviceContext)` オブジェクトを関連付けるデバイスのコンテキスト。設定すると、クーポン情報は所定のデバイスにのみ返されます。
`hasLinkedDevice`	`boolean` このオブジェクトが現在 1 つのデバイスにリンクされているかどうか。

activationStatus

enum (ActivationStatus)

この交通機関オブジェクトの有効化ステータス。このステータスによってチケットの表示が変更され、ユーザーが対処できるようになります。たとえば、このステータスが NOT_ACTIVATED に設定されている場合、チケットの詳細に [有効化] ボタンがレンダリングされます。

有効な値は次のとおりです。

NOT_ACTIVATED
ACTIVATED

deviceContext

object (DeviceContext)

オブジェクトを関連付けるデバイスのコンテキスト。設定すると、クーポン情報は所定のデバイスにのみ返されます。

hasLinkedDevice

boolean

このオブジェクトが現在 1 つのデバイスにリンクされているかどうか。

デバイスのコンテキスト

項目説明

項目	説明
`deviceToken`	`string` 設定すると、オブジェクトが有効になったときに、クーポン情報が所定のデバイスにのみ返されます。ユーザーのデバイスをトレースするための安定した識別子として使用することはできません。デバイスが同じでもパスが異なる場合や、デバイスが同じでも有効化が異なる場合は、設定が変わることがあります。これを設定する場合、呼び出し元は、有効にするオブジェクトに `hasLinkedDevice` も設定する必要があります。 `deviceToken` は、有効化パラメータの `deviceContext` フィールドから取得されます。

deviceToken

string

設定すると、オブジェクトが有効になったときに、クーポン情報が所定のデバイスにのみ返されます。ユーザーのデバイスをトレースするための安定した識別子として使用することはできません。デバイスが同じでもパスが異なる場合や、デバイスが同じでも有効化が異なる場合は、設定が変わることがあります。これを設定する場合、呼び出し元は、有効にするオブジェクトに hasLinkedDevice も設定する必要があります。

deviceToken は、有効化パラメータの deviceContext フィールドから取得されます。

デバイスの固定

デバイスの固定機能を使用すると、1 つのデバイスでチケットを有効にして、そのデバイスにのみチケットクーポン情報を表示できます。これは、ONE_USER_ONE_DEVICE の multipleDevicesAndHoldersAllowedStatus とは異なり、チケットの表示対象が 1 台のデバイスに限定されることはありません。デバイスの固定機能とともに、ステータス ONE_USER_ALL_DEVICES を使用することをおすすめします。

有効にする前に、自分のデバイスにチケットと有効化ボタンが表示されます。有効にしてデバイスに固定した場合、固定されたデバイスにはクーポン情報が表示されます。他のデバイスには有効化ボタンが表示され、ユーザーはチケットを別のデバイスに移動できるようになります。チケットを移動する機能は不要でも、いずれかのデバイスで有効にする必要がある場合は、デバイスの固定を使用せずに、有効にする際にチケットを ONE_USER_ONE_DEVICE に更新できます。

デバイスの固定機能を実装するには、有効化パラメータで受け取った deviceToken フィールドを使用してオブジェクトを更新し、同じ API 呼び出しで hasLinkedDevice を true に設定する必要があります。必要に応じて、以降の API 呼び出しで hasLinkedDevice を false に設定することで、チケットとデバイスのリンクを解除できます。

デバイスの固定のシーケンス図

有効化パラメータ

有効化エンドポイントへのリクエストには、次のパラメータが含まれます。

JSON の例:

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

識別情報	説明
`classId`	完全修飾のクラス ID。次の形式を使用します。 <issuer_id.class_id>
`objectIds`	次の形式を使用するオブジェクト ID の完全修飾配列。 <issuer_id.object_id>
`expTimeMillis`	有効期限はエポックからのミリ秒単位です。有効期限を経過したメッセージは無効とみなす必要があります。
`eventType`	常に `"activate"`。
`nonce`	重複配信を追跡するナンス。
`deviceContext`	ユーザーが操作するデバイスを表す、Google によって生成された一意の ID。この ID は、オブジェクトをデバイスに関連付ける更新を行う場合に使用します。この ID は、これ以降に特定のデバイスから行われたリクエストでは、変更される可能性があります。