即時開發人員通知參考指南

本文列出並說明您可從 Google Play 收到的 即時開發人員通知類型。

編碼

每次發布至 Cloud Pub/Sub 主題的發布內容都會包含一個 Base64 編碼的資料欄位。

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

將 Base64 編碼的資料欄位解碼後，DeveloperNotification 會包含以下欄位：

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "pendingRefundReviewNotification": PendingRefundReviewNotification,
  "testNotification": TestNotification
}

下表提供這些欄位的說明。

屬性名稱 值 說明
version string 這則通知的版本。一開始會是「1.0」。此版本與其他版本欄位不同。
packageName string 與這則通知相關的應用程式套件名稱 (例如「com.some.thing」)。
eventTimeMillis long 事件發生時的時間戳記 (以從 Epoch 紀元時間算起的毫秒數表示)。
subscriptionNotification SubscriptionNotification

如有這個欄位，這則通知便與訂閱相關，且本欄位包含有關訂閱的其他資訊。

請注意，此欄位與 pendingRefundReviewNotification、oneTimeProductNotification、voidedPurchaseNotification 和 testNotification 互斥。
oneTimeProductNotification OneTimeProductNotification

如有這個欄位，這則通知便與一次性消費相關，且本欄位包含有關該筆消費的其他資訊。

請注意，此欄位與 pendingRefundReviewNotification、subscriptionNotification、voidedPurchaseNotification 和 testNotification 互斥。
voidedPurchaseNotification VoidedPurchaseNotification

如有這個欄位，這則通知便與作廢的交易相關，且本欄位包含有關該筆交易的其他資訊。

請注意，此欄位與 pendingRefundReviewNotification、oneTimeProductNotification、subscriptionNotification 和 testNotification 互斥。
pendingRefundReviewNotification PendingRefundReviewNotification

如有這個欄位，則這則通知與退款要求相關，您可以建議解決方案。呼叫 `ReviewRefund` API 回應這則通知。

請注意，此欄位與 subscriptionNotification、oneTimeProductNotification、voidedPurchaseNotification 和 testNotification 互斥。
testNotification TestNotification

如果有這個欄位，則這則通知與測試發布相關。這些內容只會透過 Google Play 管理中心傳送。

請注意，此欄位與 pendingRefundReviewNotification、oneTimeProductNotification、subscriptionNotification 和 voidedPurchaseNotification 互斥。

SubscriptionNotification

SubscriptionNotification 包含下列欄位：

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string
}
屬性名稱 值 說明
version string 這則通知的版本。一開始會是「1.0」。此版本與其他版本欄位不同。
notificationType int 訂閱項目的 notificationType 可能具有下列值：
  • (1) SUBSCRIPTION_RECOVERED - 訂閱項目已從帳戶保留狀態恢復，或從暫停狀態恢復。
  • (2) SUBSCRIPTION_RENEWED - 目前的訂閱項目已續訂。
  • (3) SUBSCRIPTION_CANCELED - 訂閱項目遭自願取消或非自願取消。如果是自願取消的情況，會在使用者取消時傳送此值。
  • (4) SUBSCRIPTION_PURCHASED - 使用者已購買新的訂閱項目。
  • (5) SUBSCRIPTION_ON_HOLD - 訂閱項目已進入帳戶保留狀態 (如果已啟用)。
  • (6) SUBSCRIPTION_IN_GRACE_PERIOD - 訂閱項目已進入寬限期 (如果已啟用)。
  • (7) SUBSCRIPTION_RESTARTED - 使用者已從「Play」>「帳戶」>「訂閱」還原訂閱項目。訂閱項目已取消，但在使用者還原時尚未到期。詳情請參閱「還原」。
  • (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED (已淘汰) - 使用者已成功確認訂閱項目價格異動。
  • (9) SUBSCRIPTION_DEFERRED - 訂閱項目的週期時間已延長。
  • (10) SUBSCRIPTION_PAUSED - 訂閱項目已暫停。
  • (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED - 訂閱暫停時間表已變更。
  • (12) SUBSCRIPTION_REVOKED - 使用者在訂閱到期前已取消訂閱項目。
  • (13) SUBSCRIPTION_EXPIRED - 訂閱項目已到期。
  • (17) SUBSCRIPTION_ITEMS_CHANGED - 訂閱組合中的項目已變更。
  • (18) SUBSCRIPTION_CANCELLATION_SCHEDULED - 分期付款訂閱方案已排定在承諾期結束時取消。
  • (19) SUBSCRIPTION_PRICE_CHANGE_UPDATED - 訂閱項目價格異動詳細資料已更新。
  • (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - 訂閱項目的待處理交易已取消。
  • (22) SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED - 訂閱項目的價格逐步調漲同意期限已開始，或使用者已同意價格逐步調漲。只有在需要調漲價格的區域，系統才會針對訂閱項目傳送這項 RTDN。
purchaseToken string 購買訂閱項目時提供給使用者裝置的權杖。

範例

以下是新的訂閱項目購買交易的通知範例：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN"
  }
}

OneTimeProductNotification

OneTimeProductNotification 包含下列欄位：

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "sku": string
}
屬性名稱 值 說明
version string 這則通知的版本。一開始會是「1.0」。此版本與其他版本欄位不同。
notificationType int 通知類型，可能具有下列值：
  • (1) ONE_TIME_PRODUCT_PURCHASED - 使用者已成功購買一次性產品。
  • (2) ONE_TIME_PRODUCT_CANCELED - 使用者已取消待處理的一次性產品購買交易。
purchaseToken 字串 購買產品時提供給使用者裝置的權杖。
SKU string 所購買一次性產品的 ID (例如「sword_001」)

範例

如有新的一次性消費時，通知內容如下所示：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "oneTimeProductNotification":
  {
    "version":"1.0",
    "notificationType":1,
    "purchaseToken":"PURCHASE_TOKEN",
    "sku":"my.sku"
  }
}

VoidedPurchaseNotification

VoidedPurchaseNotification 包含下列欄位：

屬性名稱 值 說明

purchaseToken

string

與消費相關聯的權杖已經作廢。如有新的交易，系統會將這項資訊提供給開發人員。

orderId

string

與作廢交易相關聯的專屬訂單 ID。如為一次性消費，這會是該次交易產生的唯一訂單 ID。如為自動續約型訂閱項目，每筆續訂交易都會產生新的訂單 ID。

productType

int

就作廢的交易而言，productType 可能包含下列值：

  • (1) PRODUCT_TYPE_SUBSCRIPTION：訂閱交易已作廢。
  • (2) PRODUCT_TYPE_ONE_TIME：一次性消費交易已作廢。

refundType

int

就作廢的交易而言，refundType 可能包含下列值：

  • (1) REFUND_TYPE_FULL_REFUND：交易已完全作廢。
  • (2) REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND：依數量提供部分退款的功能已部分作廢交易，這項功能僅適用於購買多件商品的情況。購買交易可多次部分取消。

請注意，如果多件商品交易的剩餘總數量全數退款，refundType 會變成 REFUND_TYPE_FULL_REFUND。

範例

如有新的作廢交易，通知內容如下所示：

{
  "version":"1.0",
  "packageName":"com.some.app",
  "eventTimeMillis":"1503349566168",
  "voidedPurchaseNotification":
  {
    "purchaseToken":"PURCHASE_TOKEN",
    "orderId":"GS.0000-0000-0000",
    "productType":1
    "refundType":1
  }
}

使用 VoidedPurchaseNotification

當 RTDN 用戶端收到 VoidedPurchaseNotification 時，請留意下列資訊：

  • packageName：用於識別應用程式。
  • eventTimeMillis：通知您狀態變更的時間。
  • purchaseToken：購買產品時提供給使用者裝置的權杖。
  • orderId：用於識別與作廢交易相關聯的訂單。
  • productType：指出作廢的交易是購買應用程式內商品或訂閱項目。
  • refundType：指定導致交易作廢的退款類型。

PendingRefundReviewNotification

如果使用者要求針對購買交易申請退單，且該要求需要開發人員審查，系統就會傳送 PendingRefundReviewNotification。收到這類通知後，請評估要求，並在 24 小時內呼叫 ReviewRefund API，提供退款建議和購買使用情況證據。

PendingRefundReviewNotification 包含下列欄位：

{
  "version": string,
  "pendingRefundToken": string,
  "orderId": string,
  "refundReason": int,
  "obfuscatedAccountId": string,
  "obfuscatedProfileId": string
}
屬性名稱 值 說明
version string 這則通知的版本。一開始會是「1.0」。此版本與其他版本欄位不同。
pendingRefundToken 字串 這是專屬權杖，可識別審查中的待處理退款要求。呼叫 ReviewRefund API 時，請傳遞這個權杖。
orderId 字串 待處理退款審查的購買交易訂單 ID。
refundReason int 申請退款的原因。待處理的評論僅支援 CHARGEBACK (7) 做為退款原因。您的程式碼應處理新原因。
obfuscatedAccountId 字串 (如適用) 購買時提供的開發人員指定使用者帳戶 ID (經模糊處理)。
obfuscatedProfileId 字串 (如適用) 購買時提供的開發人員指定設定檔 ID (經過模糊處理)。

範例

以下是待處理退款審查通知的範例：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "pendingRefundReviewNotification":
  {
    "version":"1.0",
    "pendingRefundToken":"example-token",
    "orderId":"GPA.1234-5678-9012-34567",
    "refundReason":7,
    "obfuscatedAccountId":"user-account-id",
    "obfuscatedProfileId":"user-profile-id"
  }
}

TestNotification

TestNotification 包含下列欄位：

{
  "version": string
}
屬性名稱 值 說明
version string 這則通知的版本。一開始會是「1.0」。此版本與其他版本欄位不同。

範例

以下是測試通知範例：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}