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

本主題列出並描述您可從 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,
  "testNotification": TestNotification
}

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

屬性名稱 值 說明
version string 這則通知的版本。一開始會是「1.0」。此版本與其他版本欄位不同。
packageName string 與這則通知相關的應用程式套件名稱 (例如「com.some.thing」)。
eventTimeMillis long 事件發生時的時間戳記 (以從 Epoch 紀元時間算起的毫秒數表示)。
subscriptionNotification SubscriptionNotification 如有這個欄位，這則通知便與訂閱相關，且本欄位包含有關訂閱的其他資訊。請注意，此欄位與 oneTimeProductNotification、voidedPurchaseNotification 和 testNotification 互斥。
oneTimeProductNotification OneTimeProductNotification 如果有這個欄位，這則通知便與一次性消費相關，且本欄位包含有關該筆消費的其他資訊。請注意，此欄位與 subscriptionNotification、voidedPurchaseNotification 和 testNotification 互斥。
voidedPurchaseNotification VoidedPurchaseNotification 如果有這個欄位，這則通知便與作廢的交易相關，且本欄位包含有關該筆交易的其他資訊。請注意，此欄位與 oneTimeProductNotification、subscriptionNotification 和 testNotification 互斥。
testNotification TestNotification 如果有這個欄位，則這則通知與測試發布相關。這些內容只會透過 Google Play 管理中心傳送。請注意，此欄位與 oneTimeProductNotification、subscriptionNotification 和 voidedPurchaseNotification 互斥。

SubscriptionNotification

SubscriptionNotification 包含下列欄位：

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "subscriptionId": 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 - 訂閱項目已到期。
  • (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - 未完成交易 已取消 個訂閱項目的訂閱。
purchaseToken string 購買訂閱項目時提供給使用者裝置的權杖。
subscriptionId string 所購買訂閱項目的產品 ID (例如「monthly001」)。

範例

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

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

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 string 購買產品時提供給使用者裝置的權杖。
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：顯示作廢交易的退款類型。

如果只需為授權調整作業找出正確的交易和訂單，現階段您已取得所需的一切資訊。如要瞭解如何取得作廢交易的其他資訊，請使用 Google Play Voided Purchases API，這種提取模型可根據指定時間戳記，提供相應期間作廢交易的額外資料。

如果是部分作廢的多件購買交易，則 refundableQuantity 欄位 由 purchases.products 提供 已購買且尚未作廢的產品數量。

TestNotification

TestNotification 包含下列欄位：

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

範例

以下是測試通知範例：

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