(Google官方中文文檔)添加實時開發者通知

添加實時開發者通知

概覽

Google Play 結算服務提供服務器推送通知，讓您可以監控受 Play 管理的訂閱項目的狀態變化。啓用實時開發者通知後，只要現有訂閱項目有更新，您就會直接從 Cloud Pub/Sub 收到購買令牌。

實時開發者通知並不提供與訂閱項目狀態有關的完整信息，例如用戶目前是否有權訪問訂閱內容。收到令牌後，您應該始終使用購買令牌查詢 Google Play Developer API，以獲取完整信息，並根據用戶當前的權限狀態更新後端。

通知類型未來可能會發生變化。您應該能夠處理無法識別的通知類型，並且您應該始終依賴 Google Play Developer API 來處理關鍵業務邏輯。

要啓用此功能，請執行以下操作：

1. 使用您自己的 Google Cloud Platform (GCP) 項目設置 Cloud Pub/Sub。
2. 爲您的 Android 應用啓用實時開發者通知。

設置 Cloud Pub/Sub

Cloud Pub/Sub 是一種完全託管式的實時消息傳遞服務，允許您在獨立應用之間收發消息。它提供低延遲且持久的消息傳遞功能，可以幫助您快速集成託管在 Google Cloud Platform 以及外部的系統。

Google Play 結算服務使用 Cloud Pub/Sub 發佈與您訂閱的主題相關的推送通知。

滿足前提條件

要使用 Cloud Pub/Sub，您必須在 Google Cloud Platform (GCP) 上擁有一個項目，並啓用 Cloud Pub/Sub API。如果您不熟悉 GCP 和 Cloud Pub/Sub，請參閱快速入門指南。

要接收推送通知，您必須創建安全的後端服務器以使用發送到您主題的消息。您的服務器可以使用 Cloud Pub/Sub 客戶端庫來使用這些消息。

創建主題

要開始接收通知，您需要創建一個主題，以便 Google Play 結算服務向其發佈通知。要創建主題，請執行以下操作：

1. 閱讀創建主題中的說明。
2. 使用 Google Cloud Platform Console 創建主題。

創建 Pub/Sub 訂閱項目

要接收發布到主題的消息，您必須針對該主題創建 Pub/Sub 訂閱項目。要創建 Pub/Sub 訂閱項目，請執行以下操作：

1. 閱讀 Cloud Pub/Sub 訂閱者指南，以確定是將訂閱項目配置爲“推送訂閱”還是“提取訂閱”。提取訂閱要求您的安全後端服務器向 Cloud Pub/Sub 服務器發起請求以檢索消息。推送訂閱要求 Cloud Pub/Sub 向您的安全後端服務器發起請求以傳遞消息。
2. 閱讀添加訂閱中的說明。
3. 使用 Google Cloud Platform Console 創建訂閱項目。

針對您的主題授予發佈權限

Cloud Pub/Sub 要求您按照以下步驟授予 Google Play 結算服務向您的主題發佈通知的權限：

1. 打開 Google Cloud Console。

2. 選擇您的項目，然後在左側導航欄中點擊 Pub/Sub。

3. 找到您的主題，然後打開權限詳細信息。

4. 
   圖 1. 訪問主題的“權限”配置。

5. 添加服務帳號

   [email protected]
   

   ，然後授予其 Pub/Sub 發佈商的角色。

   
   圖 2. 將 Google Play 服務帳號添加爲 Pub/Sub 發佈商。

6. 保存以完成主題設置。

   
   圖 3. 主題配置完成。

爲您的應用啓用實時開發者通知

要爲您的應用啓用實時開發者通知，請執行以下操作：

1. 打開 Google Play 管理中心。

2. 選擇您的 Android 應用。

3. 依次轉到開發工具 > 服務和 API 頁面。

4. 滾動到頁面底部的實時開發者通知部分。

   
   圖 4. “實時開發者通知”部分。

5. 在主題名稱字段中，輸入您之前配置的完整 Cloud Pub/Sub 主題名稱。主題名稱應採用 projects/{project_id}/topics/{topic_name} 格式，其中 project_id 是項目的唯一標識符，topic_name 是之前創建的主題的名稱。

6. 點擊發送測試消息以發送測試消息。進行發佈測試有助於確保一切均已正確設置和配置。如果測試消息發佈成功，則系統會顯示一條消息，表明測試發佈已成功。如果您針對該主題運行了訂閱者，則該訂閱者應該會收到此測試消息。

   如果發佈失敗，則系統會顯示錯誤。請確保主題名稱正確，並且 [email protected] 服務帳號擁有對該主題的 Pub/Sub 發佈商訪問權限。

7. 點擊更新主題。

更改主題名稱

要更改主題名稱而不丟失消息，請執行以下步驟：

1. 創建並配置新的主題和訂閱項目。
2. 開始閱讀和處理髮布到新主題的消息。
3. 在 Play 管理中心內更新該應用的主題名稱。
4. 藉助 Stackdriver 或 Cloud Developer Console，等待舊主題停止接收消息，同時確保新主題在接收消息。
5. 在舊主題停止接收消息後將其刪除。

刪除主題

要刪除主題，請執行以下操作：

1. 通過 Google Play 管理中心移除應用的主題名稱。
2. 在停止接收消息後，通過 Google 或 Google Cloud Platform Console 刪除相應的 Pub/Sub 主題。

注意：如果先在 Pub/Sub 中刪除主題，然後再移除名稱，可能會導致消息丟失。您必須使用 Pub/Sub 重新設置該主題才能解決此問題。

調整通知處理方式

由於可能會發送到 Pub/Sub 主題的通知種類繁多，因此對所有通知採用單一的二進制處理方式可能並不現實。在決定如何調整通知處理方式時，有多種選項可供研究。這些選項包括：

• 使用推送和提取式通知。
• 爲主題設置多個訂閱項目。
• 將通知消息重新發布到其他 Pub/Sub 項目。

例如，單個訂閱項目可以擁有多個從此訂閱項目中提取消息的進程。來自此訂閱項目的消息會在讀取器之間自動分配。然後，每個這樣的進程都可以處理通知，或將請求路由到更專用的服務。

隨着時間的推移，可能會添加新的通知類型。訂閱者應該在新通知出現後對其進行恰當的處理，方法通常是確認收到的消息。

注意：如果您選擇使用推送訂閱，請先註冊端點，然後再添加推送端點。有關詳情，請參閱註冊端點。

有關詳情，請參閱 Pub/Sub 訂閱者概覽。

監控通知流量

要監控通知流量，請使用 Google Stackdriver 服務。藉助此服務，您可以監控主題的流量，並針對特定條件設置提醒。例如，如果您的未確認消息計數過高（可能意味着訂閱者出問題了）或發佈計數過低（可能意味着發佈到主題時出錯了），您便可以發出提醒。

確定定價和配額

要詳細瞭解定價和配額，請參閱定價和配額。

估算流量消耗

訂閱通知的流量大約爲每個請求 1KB 的流量。每次發佈和提取通知都需要一個單獨的請求，即每個通知大約 2KB 的流量。每月的通知數量取決於您的結算週期和用戶的行爲。在一個結算週期內，每個用戶應至少有一個通知。

服務等級協議 (SLA)

實時開發者通知服務並不提供官方延遲 SLA。不過，大多數通知都應該在事件發生後的幾秒鐘內發佈。您應該在 Stackdriver 頁面中監控流量消耗指標（例如未確認的消息數量），以確保您能夠及時處理所有消息。

JSON 規範

發佈到 Pub/Sub 主題的每個消息都包含一個以 base64 編碼的 DeveloperNotification，其中包含以下字段：

{
  "version": string,
  "packageName": string
  "eventTimeMillis": long
  "subscriptionNotification": SubscriptionNotification
  "testNotification": TestNotification
}

屬性名稱	值	說明
version	string	此通知的版本。最初，此值將爲“1.0”。此版本與其他版本字段不同。
packageName	string	與此通知相關的應用的軟件包名稱（例如，com.some.thing）。
eventTimeMillis	long	事件發生的時間戳，以從公元紀年開始計算的毫秒數表示。
subscriptionNotification	SubscriptionNotification	如果此字段存在，則此通知與某個訂閱項目相關。它包含與此訂閱項目相關的其他信息。此字段與 testNotification 互斥。
testNotification	TestNotification	如果此字段存在，則此通知與某個測試發佈相關。這些通知只通過 Play 管理中心發送。此字段與 subscriptionNotification 互斥。

SubscriptionNotification 包含以下字段：

{
  "version": string
  "notificationType": int
  "purchaseToken": string
  "subscriptionId": string
}

屬性名稱	值	說明
version	string	此通知的版本。最初，此值將爲“1.0”。此版本與其他版本字段不同。
notificationType	int	通知的類型。它可以具有以下值： (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 - 訂閱已過期。
purchaseToken	string	購買訂閱時向用戶設備提供的令牌。
subscriptionId	string	所購買訂閱的 ID（例如“monthly001”）。

注意：系統僅針對需要更改用戶權限的事件發送通知。例如，Refund API 並不會更改用戶權限，因此不會觸發通知。

TestNotification 包含以下字段：

{
  "version": string
}

屬性名稱	值	說明
version	string	此通知的版本。最初，此值將爲“1.0”。 此版本與其他版本字段不同。

示例

以下是訂閱購買通知的示例：

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

以下是測試通知的示例：

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