本指南說明如何使用 Google Play Developer API,為 Play 應用程式建立及管理產品目錄。
如要透過 Google Play 結帳系統在應用程式中販售產品,您必須設定目錄,並納入所有希望讓使用者購買的產品。您可以透過 Play 管理中心完成這項作業,也可以使用 Google Play Developer API 自動管理目錄。自動化功能有助於確保目錄隨時保持最新狀態,並可用於規模龐大、不便手動協調的目錄。本指南將說明如何使用 Play Developer API,為 Play 應用程式建立及管理產品目錄。請參閱準備工作指南,瞭解如何設定 Google Play Developer API 以便進行後端整合。
目錄管理 API
如要瞭解可透過 Google Play 結帳系統銷售的各種產品類型,請參閱「瞭解各種應用程式內商品類型和目錄注意事項」一文。Google 提供兩組主要的 API,用於管理 Play 上的目錄,對應兩個主要產品類別:
- 一次性產品
- 訂閱產品
一次性產品
inappproducts
端點可讓您從後端管理一次性產品。包括建立、更新和刪除產品,以及管理價格和供應情形。視您處理一次性產品購買交易的方式而定,您會模擬消耗性產品 (可依需求購買多次) 或永久授權 (同一位使用者無法購買兩次)。您可以決定哪些一次性產品應為消耗性產品,或非消耗性產品。
訂閱產品
monetization.subscriptions
端點可協助您管理開發人員後端的訂閱產品。您可以建立、更新和刪除訂閱項目,或控管訂閱項目的區域供應情形和價格。除了 monetization.subscriptions
端點之外,我們也提供 monetization.subscriptions.basePlans
和 monetization.subscriptions.basePlans.offers
,分別用於管理訂閱項目的基本方案和優惠。
批次方法
inappproducts
和 monetization.subscriptions
端點提供多種批次方法,可讓您同時擷取或管理同一個應用程式中的最多 100 個實體。
當批次方法與啟用的延遲容許值搭配使用時,可支援更高的吞吐量,對於需要建立大型目錄或進行目錄比對的開發人員來說特別實用。
更新傳播延遲時間與傳輸量
產品建立或修改要求完成後,由於網路或後端處理作業延遲,使用者可能無法立即在裝置上看到變更。根據預設,所有產品修改要求都會受到延遲影響。這表示系統已針對快速傳播後端系統的情況進行最佳化,通常會在幾分鐘內反映在使用者裝置上。不過,這類修改要求的數量有每小時限制。如果需要建立或更新大量產品 (例如在初始大型目錄建立期間),您可以使用批次方法,並將 latencyTolerance
欄位設為 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
。這麼做可大幅提升更新傳輸量。延遲容許值更新最多可能需要 24 小時才會傳送至使用者裝置。
配額設定
使用 Play Developer API 管理產品目錄時,請留意以下幾項配額限制:
- Google Play Developer API 的預設查詢上限為每天 200,000 次。這個配額限制適用於所有端點 (包括目錄管理 API) 的用量匯總。
- 產品修改端點也會強制執行每小時 7,200 次查詢的限制。這項限制適用於一次性產品和訂閱項目,以及所有修改要求 (包括建立、更新、啟用和刪除)。無論包含的個別要求數量或延遲時間敏感度為何,批次修改方法呼叫都會計為這項配額的一次查詢。
- 延遲敏感性修改作業的每小時修改次數上限為 7,200 次。針對批次方法,每個巢狀修改要求都會單獨計算,以便計算這項配額。這個配額只會對執行延遲敏感更新的批次 API 使用者產生實際影響,因為在其他情況下,配額 2 會在這個配額之前或同時用盡。
以下列舉幾個示例,說明如何瞭解不同要求的配額使用情形:
- 單一
get
要求會耗用 1 個配額 1 符記,但不會耗用配額 2 和 3 的符記 (因為這兩個配額只與修改端點有關)。 - 若要擷取最多 100 項商品的批次
get
要求,也會使用 1 個配額 1 權杖,但不會使用配額 2 和 3 的權杖。 - 針對單一項目的單一
modification
要求,會耗用 1 個配額 1 符記和 1 個配額 2 符記。如果要求對延遲時間較為敏感,也會消耗 1 個符記的配額 3。由於配額 C 的限制與配額 2 相同,因此對於只使用單一修改方法的使用者而言,沒有實際影響。 - 針對 100 個延遲容許值商品的批次
modification
要求,會耗用 1 個配額 1 的符記和 1 個配額 2 的符記。這個配額設定應可提供充足的空間,讓目錄保持更新,但如果演算法未注意到這個配額,且超過這個比率,每次額外呼叫都可能會傳回錯誤。 - 針對 100 個延遲敏感項目提出的批次
modification
要求,會耗用 1 個配額 1 權杖、1 個配額 2 權杖和 100 個配額 3 權杖。
Catalog Management API 使用建議
遵守這些規範,即可最佳化與 API 的互動,確保目錄管理體驗順暢又有效率。
監控使用情況
請注意耗用大量資源的程序。舉例來說,在整合初期,目錄管理端點可能會消耗更多配額來建立完整的初始目錄,如果您接近整體用量限制,這可能會影響其他端點 (例如購買狀態 API) 的實際用量。您必須監控配額用量,確保不會超過 API 配額。您可以透過多種方式監控使用情形。舉例來說,您可以使用 Google Cloud API 配額資訊主頁,或任何其他自行開發或第三方 API 監控工具。
最佳化 API 配額用量
強烈建議您盡量減少費率用量,以降低 API 發生錯誤的機率。如要有效實作這項功能,建議您:
- 選擇合適的產品目錄管理策略。瞭解 API 配額後,您必須為應用程式選擇合適的策略,才能有效達成目錄管理目標。
- 請只呼叫必要的最低次數,以反映您的變更。
- 請勿向 API 傳送多餘或不必要的修改呼叫。這可能需要您在後端目錄中保留變更記錄。
- 每小時的產品修改查詢次數不得超過 7,200 次。建議你建立同步處理程序,以便在短時間內大量修改產品 (例如建立初始目錄)。如果這些程序會超過每小時限制,請視需要實作等待時間,將用量降至安全的程度。建議您使用可容許延遲的更新功能,以便使用批次方法提高總處理量。
- 主動準備擴充。隨著應用程式規模擴大,您可能需要增加 API 和各種端點的用量。請參閱 Google Play Developer API 配額說明文件,進一步瞭解如何在配額即將用盡時增加配額。
- 有策略地安排繁重程序。請盡量在使用量高峰時段安排繁重的目錄程序,例如避免在週內的銷售高峰時段執行完整目錄同步作業。
新增配額錯誤處理邏輯
無論您建構目錄管理邏輯的效率如何,由於每日配額會由整合項目中獨立模組使用的端點共用,因此您應讓目錄管理邏輯能因應意外的配額限制。請務必在錯誤處理中加入配額節流錯誤,並實作適當的等待時間。每個對 Google Play 開發人員 API 的呼叫都會產生回應。如果呼叫失敗,您會收到失敗回應,其中包含 HTTP 回應狀態碼和 errors
物件,可提供錯誤網域和偵錯訊息的詳細資訊。舉例來說,如果您超過每日上限,可能會遇到類似以下的錯誤:
{
"code" : 403,
"errors" : [ {
"domain" : "usageLimits",
"message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
"reason" : "dailyLimitExceeded",
"extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
} ],
}
目錄管理導入
開發人員可使用 Google Play Developer API 產品發布端點,讓後端和 Google Play 之間的目錄保持同步。確保 Google Play 目錄隨時與後端目錄的最新資訊保持一致,可帶來更優質的使用者體驗。例如:
- 您可以查看可用優惠的完整清單,並管理優惠和基本方案標記,以影響自己的資格條件和優惠顯示邏輯。
- 你可以查看使用者在各平台上看到的不同價格和產品詳細資料,確保這些資訊一致。
- 處理新購買交易時,您將在後端取得產品詳細資料,無須在使用者關鍵流程中額外呼叫 Google Play Developer API,進而增加延遲和失敗風險。
在 Google Play 建立產品目錄時,請注意特定限制和注意事項。瞭解這些限制並決定要如何建構目錄後,請決定同步處理策略。
目錄同步處理策略
您可以透過 Google Play Developer API 發布端點,在發生變更時更新目錄。有時,您可能需要採用定期更新方式,在同一程序中傳送一系列變更。每種方法都需要不同的設計選項。每種同步處理策略都較適合某些用途,而您可能會根據情況需要同時使用這兩種策略。有時你可能會在發現新變更時立即更新產品,例如處理緊急的產品更新 (例如盡快修正錯誤的價格)。其他時候,您可以使用定期背景同步功能,確保後端和 Play 目錄一律保持一致。請參閱一些常見的使用情境,瞭解您可能需要實作這些不同的目錄管理策略。
當本機目錄發生變更時,何時傳送更新
理想情況下,只要後端產品目錄有任何變更,就應立即進行更新,以盡量減少差異。
在下列情況下,這類更新是理想的選擇:
- 請務必確保產品資料一律處於最新狀態。
- 你需要每天對產品進行一些變更。
- 你必須更新已投入生產及銷售的產品。
這個方法實作起來更簡單,可讓你以最少的差異時間範圍保持目錄同步。
使用定期更新功能的時機
定期更新會在後端以非同步方式執行產品版本,在下列情況下,這會是理想的做法:
- 您不必確保產品能在短時間內更新。
- 您需要規劃大量更新或調節程序。
- 您已擁有內容或目錄管理系統來處理數位產品,且該系統會持續更新目錄
如果目錄很大,建議使用批次方法搭配延遲容許更新,以便達到最高的傳輸量。
建立產品目錄
如果要上傳大量目錄到 Google Play,建議您自動執行初始載入作業。搭配定期策略和延遲容許的批次方法,這類繁重程序才能發揮最佳效能。
建立一次性產品
如要建立初始的一次性大型產品目錄,建議使用 inappproducts.batchUpdate
方法,並將 allowMissing
欄位設為 true
,將 latencyTolerance
欄位設為 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
。這樣一來,就能在配額限制內盡可能縮短目錄建立時間。
如果目錄較小,您可以使用 inapp_products.insert
方法。或者,您也可以使用 inappproducts.update
方法搭配 allowMissing
參數,如「產品更新」一節所述。這種做法的好處是,您不必為指令碼建立狀態,而且在發生任何錯誤時,可以從頭重新啟動。
建立訂閱產品
如要建立初始的大型訂閱目錄,建議使用 monetization.subscriptions.batchUpdate
方法,並將 allowMissing
欄位設為 true
,將 latencyTolerance
欄位設為 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
。這樣一來,就能在配額限制內盡可能縮短目錄建立時間。
如果訂閱目錄較小,Play Developer API 會提供 monetization.subscriptions.create
方法。或者,您也可以使用 monetization.subscriptions.patch
方法搭配 allowMissing
參數建立訂閱項目,詳情請參閱「產品更新」一節。
上述所有方法都會建立訂閱項目,並附帶基本方案 (在 Subscription 物件中提供)。這些基本方案一開始是停用的。如要管理基本方案的狀態,您可以使用 monetization.subscriptions.basePlans
端點,包括啟用基本方案,讓使用者可以購買。此外,monetization.subscriptions.basePlans.offers
端點可讓您建立及管理商品。
產品最新消息
您可以使用下列方法,有效率地修改現有產品,確保產品符合最新調整內容。
更新一次性產品
你可以透過三種方式更新現有的一次性產品。
inappproducts.patch
:修補端點用於部分更新資源。這表示您可以更新要求主體中指定的特定欄位。您通常只會在需要更新資源的幾個欄位時,才會使用修補端點。inappproducts.update
:更新端點用於更新整個資源。也就是說,您必須在要求主體中傳送整個資源物件。更新端點通常用於更新資源中的所有欄位。如果allowMissing
參數設為true
,且系統無法找到所提供的產品 ID,端點會插入產品,而不會失敗。inappproducts.batchUpdate
:這是更新端點的批次版本,可讓您透過單一查詢修改多個產品。搭配latencyTolerance
欄位 (設為PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
) 使用,可提高傳輸量。
更新訂閱產品
如要更新現有訂閱項目,您可以使用 monetization.subscriptions.patch
方法。這個方法會採用下列必要參數:
packageName
:訂閱項目所屬應用程式的套件名稱。productId
:訂閱項目的專屬產品 ID。regionsVersion
:區域設定版本。
除非您是使用 allowMissing
參數建立新訂閱項目,否則必須提供 updateMask
參數。這個參數是以半形逗號分隔的欄位清單,用於更新欄位。
舉例來說,如果您只想更新訂閱產品的產品資訊,請將 listings
欄位指定為 updateMask
參數。
您可以使用 monetization.subscriptions.batchUpdate
同時更新多個訂閱項目。搭配 latencyTolerance
欄位 (設為 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
) 使用,可提高傳輸量。
如要啟用、停用、刪除基本方案,或將訂閱者遷移至最新的基本方案價格版本,請使用 monetization.subscriptions.basePlans
端點。
此外,您也可以使用 monetization.subscriptions.basePlans.offers.patch
方法更新基本方案的優惠。
目錄對帳
無論您選擇在後端目錄變更時更新 Google Play 目錄,還是定期更新,如果您有 Google Play 目錄以外的目錄管理系統或資料庫,可能會發生目錄與 Play 上應用程式設定中的目錄不同步的情況。這可能是因為管理中心發生緊急手動目錄變更、目錄管理系統中斷,或是您遺失最新資料。
您可以建立目錄比對程序,避免差異時間過長。
差異比較系統考量
建議您建構差異比較系統,以便偵測不一致之處,並調和這兩個系統。建立差異系統時,請考量下列事項,以便保持目錄同步:
- 瞭解資料模型:第一步是瞭解開發人員 CMS 和 Google Play Developer API 的資料模型。這包括瞭解各系統中儲存的不同類型資料,以及不同資料元素如何彼此對應。
- 定義差異比較規則:瞭解資料模型後,您需要定義差異比較規則。這些規則會決定如何比較兩個系統中的資料。舉例來說,您可能需要比對產品 ID,並比較訂閱方案及其相關基本方案和優惠的關鍵屬性。
- 實作差異比較演算法:定義差異比較規則後,您需要實作差異比較演算法。這項演算法會從兩個系統取得資料,並根據您定義的規則進行比較。如要從 Google Play 取得目錄資料,您可以使用
inappproducts.list
、inappproducts.batchGet
、monetization.subscriptions.list
和monetization.subscriptions.batchGet
方法。 - 產生差異比較報表:差異比較演算法會產生差異比較報表。這份報表會顯示兩個系統之間的差異。
- 比對差異:產生差異報表後,您需要解決差異。這可能包括更新 CMS 中的資料,或是使用開發人員 API 目錄管理端點更新 Google Play 端的資料,具體取決於您通常更新目錄的方式。如要協調不同步的產品,請使用「產品更新」一節所述的更新端點。
產品淘汰
Google Play Developer API 提供多種方法,協助開發人員淘汰產品:inappproducts.delete
和 inappproducts.batchDelete
適用於一次性產品,monetization.subscriptions.delete
適用於訂閱。在許多情況下,您可能需要淘汰產品,例如:
- 誤建立。
- 停用功能或服務。
建議你將產品淘汰納入目錄管理策略。
淘汰一次性產品
如要使用 Google Play Developer API 刪除一次性產品,您必須使用 inappproducts.delete
或 inappproducts.batchDelete
方法。
淘汰訂閱產品
您可以使用 monetization.subscriptions.delete
方法刪除訂閱項目。至少啟用一個基本方案後,就無法移除訂閱項目。