新增及刪除回呼

本指南說明如何透過 Google Wallet API 使用回呼。建立或刪除票證時，Google 可以對您選擇的 HTTPS 端點執行回呼。 這個回呼是類別專屬，包含事件的相關資料，例如類別、物件和事件類型。這項資訊可用於追蹤使用者新增和刪除次數。舉例來說，您可以設定回呼，將事件傳送至數據分析應用程式，追蹤宣傳活動期間的顧客參與度。

必要條件

開始之前，請先詳閱下列必要條件：

  • 設定負責處理 POST 要求的 HTTPS 端點。請注意，這個端點必須設為公開端點。
  • 透過程式按類別更新回呼端點。請參閱 REST API 說明文件中按照類別列出的 callbackOptions 屬性。
  • 建議：使用 Tink 程式庫驗證簽名。

實作回呼

每當使用者新增或刪除物件時，Google 都會對商家進行回呼，並透過各類別網址提供新增或刪除作業的詳細資料。商家必須先使用公開金鑰驗證訊息的真實性，回呼作業驗證訊息後，即可將回呼用於下游作業。

驗證簽名

實作 HTTPS 端點時，建議您使用 Tink 程式庫來驗證訊息簽名。Tink 程式庫提供 PaymentMethodTokenRecipient。這項公用程式可自動驗證簽名，並在驗證成功時傳回訊息的實際內容。

以下範例說明如何使用 Tink 程式庫實作 PaymentMethodTokenRecipient：

import java.io.IOException;
import javax.servlet.http.*;
import com.google.common.io.CharStreams;
import com.google.crypto.tink.apps.paymentmethodtoken.*;

// Replace ISSUER_ID with your issuer id
private static final String RECIPIENT_ID = "ISSUER_ID";

private static final String PUBLIC_KEY_URL = "https://pay.google.com/gp/m/issuer/keys";
private static final String SENDER_ID = "GooglePayPasses";
private static final String PROTOCOL = "ECv2SigningOnly";

private static final GooglePaymentsPublicKeysManager keysManager = new GooglePaymentsPublicKeysManager.Builder()
        .setKeysUrl(PUBLIC_KEY_URL)
        .build();

public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
  try {
    // Extract signed message with signature from POST request body.
    String signedMessage = CharStreams.toString(request.getReader());
    PaymentMethodTokenRecipient recipient =
            new PaymentMethodTokenRecipient.Builder()
                    .protocolVersion(PROTOCOL)
                    .fetchSenderVerifyingKeysWith(keysManager)
                    .senderId(SENDER_ID)
                    .recipientId(RECIPIENT_ID)
                    .build();

    String serializedJsonMessage = recipient.unseal(signedMessage);

    // Use serializedJsonMessage to extract the details
  } catch (Exception e) {
    // Handle the error
  }
}

訊息格式規定

訊息格式為 JSON 經過序列化而產生的字串，當中包含以下屬性：

ID 說明
classId

完全符合規定的類別 ID，所用格式如下：

<issuer_id.class_id>
objectId

完全符合規定的物件 ID，所用格式如下：

<issuer_id.object_id>
expTimeMillis 自 Epoch 紀元時間起算的到期時間 (以毫秒為單位)。到期時間屆滿之後，系統就會將訊息視為無效。
eventType 可以是 del 或 save，代表 DELETE 和 SAVE。
nonce 隨機值，可用於追蹤任何重複的訊息傳送作業。

處理 Google 伺服器發出的要求

傳送至回呼端點的要求包含多個欄位，以下列出要求標頭的主要欄位：

  • User-Agent: Googlebot
  • Content-Type：application/json

請為伺服器選用合適的設定，以免伺服器拒絕要求。如要這麼做，請在 robots.txt 中設定下列項目：

User-agent: Googlebot
Disallow:

重試

回呼會儘可能履行您的要求。如果回呼端點沒有回應或間歇性中斷，Google 會使用常見的重試策略來確保系統穩定運作，並逐步減少重試次數。

重複傳送訊息

在某些情況下，系統可能會重複傳送訊息。建議您使用 nonce 來排除重複傳送的情形。