Google Play 帳款服務 AIDL 參考資料

警告：目前已淘汰 AIDL，並將於日後推出的版本中移除。請使用 Google Play 帳款服務程式庫實作 Google Play 的結帳功能。

這份文件提供有關使用 Google Play 帳款服務 AIDL 的技術參考資料資訊。

伺服器回應代碼

下表列出從 Google Play 傳送至應用程式的所有伺服器回應代碼。Google Play 會在回應 Bundle 中以對應至 RESPONSE_CODE 的整數形式，同步傳送回應代碼。應用程式必須處理所有這些回應代碼。

表 1.Google Play 帳款服務 AIDL 呼叫的回應代碼匯總。

回應代碼 值 說明
BILLING_RESPONSE_RESULT_OK 0 成功
BILLING_RESPONSE_RESULT_USER_CANCELED 1 使用者按下了返回或取消對話方塊
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 網路連線中斷
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 要求的類型不支援 Google Play 帳款服務 AIDL 版本
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 要求的產品不提供購買。
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 提供給 API 的引數無效。這個錯誤也可能表示應用程式未正確簽署或設定結帳功能，或是在資訊清單中缺少必要的權限。
BILLING_RESPONSE_RESULT_ERROR 6 執行 API 操作期間發生嚴重錯誤
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 已擁有該商品，因此無法購買
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 尚未擁有該商品，因此無法使用

Google Play 帳款服務 AIDL 參考資料 - 支援

本節內容為取得有關應用程式中可用的付費支援類型內容的方法說明。

isBillingSupported() 方法

這種方法會指出：

  • 應用程式是否支援指定的 AIDL 版本。
  • Google Play 是否支援使用者所在國家/地區的帳款服務系統。
  • 應用程式套件是否已啟用 Google Play 的帳款服務系統。
  • 應用程式是否可以將指定類型的商品用來結帳。

表 2.isBillingSupported() 參數。

索引 類型 說明
apiVersion int 應用程式目前使用的 Google Play 帳款服務 AIDL 版本號碼。
packageName String 呼叫此方法的應用程式套件名稱。
type String 應用程式內產品的值必須為 inapp，訂閱項目的值必須為 subs。

這種方法適用於 Google Play 帳款服務 AIDL 第 3 版及更高版本。

isBillingSupportedExtraParams() 方法

這個方法與 isBillingSupported() 相同，但您可以傳遞第四個引數 Bundle（可包含額外的參數）。

表 3.isBillingSupportedExtraParams() 參數

索引 類型 說明
apiVersion int 應用程式目前使用的 Google Play 帳款服務 AIDL 版本號碼。
packageName String 呼叫此方法的應用程式套件名稱。
type String 應用程式內產品的值必須為 inapp，訂閱項目的值必須為 subs。
extraParams Bundle

一組額外參數，用於進一步指定應用程式支援的 Google Play 的帳款服務系統類型。

這個組合可含有一個名稱為 vr 的其他索引，其使用的是布林值。這個標記指定此應用程式是否支援虛擬實境 (VR) 購買流程。

這種方法適用於 Google Play 帳款服務 AIDL 第 7 版及更高版本。

Google Play 帳款服務 AIDL 參考資料 - 詳細資料

Google Play 帳款服務 AIDL 定義於 IInAppBillingService.aidl，這個檔案包含在第 3 版的範例應用程式中。

getSkuDetails() 方法

使用 getSkuDetails() 方法取得對應產品 ID 清單的產品詳細資料。

表 4.GetSkuDetails() 參數。

索引 類型 說明
apiVersion int 應用程式目前使用的 Google Play 帳款服務 AIDL 版本號碼。
packageName String 呼叫此方法的應用程式套件名稱。
type String 應用程式內的產品類型（一次性消費的值為「inapp」，訂閱項目的值為「subs」）。
skusBundle Bundle 一個包含索引為 ITEM_ID_LIST 的 StringArrayList SKU。

如果 getSkuDetails() 方法成功，Google Play 會傳送回應 Bundle。查詢結果儲存在與 DETAILS_LIST 索引對應的字串 ArrayList 內的 Bundle 中。詳細資料清單中的每個字串都以 JSON 格式包含單一產品的詳細資料。表 5 匯總了包含產品詳細資料的 JSON 字串中的欄位。

表 5.JSON 欄位的說明，其中含有來自 getSkuDetails() 要求所傳回的產品詳細資料。

索引 說明
productId 該產品的產品 ID。
type 應用程式內產品的值必須為 inapp，訂閱項目的值必須為 subs。
price 商品的既定價格（包括幣別符號）。價格不含稅。
price_amount_micros 以微量單位表示的價格，1,000,000 微量單位等於 1 單位的實際貨幣。舉例來說，如果 price 為 "€7.99"，則 price_amount_micros 為 "7990000"。這個值代表特定貨幣經過四捨五入後的當地價格。
price_currency_code price 的 ISO 4217 貨幣代碼。舉例來說，如果以英鎊指定 price，則 price_currency_code 為 "GBP"。
title 產品的標題。
description 產品的說明。
subscriptionPeriod 以 ISO 8601 格式指定的訂閱期。舉例來説，P1W 相當於一週、P1M 相當於一個月、P3M 相當於三個月、P6M 相當於六個月，而 P1Y 則相當於一年。

注意：系統只會為訂閱項目傳回此值。
freeTrialPeriod 在 Google Play 管理中心設定的試用期（以 ISO 8601 格式指定）。舉例來說，P7D 相當於 7 天。若要進一步瞭解免費試用資格，請參閱應用程式內訂閱項目。

注意：系統只會為已設定試用期的訂閱項目傳回此值。
introductoryPrice 訂閱項目的既定新用戶優惠，包括幣別符號（例如 €3.99）。價格不含稅。

注意：系統只會為已設定新用戶優惠期的訂閱項目傳回此值。
introductoryPriceAmountMicros 以微量單位指定的新用戶優惠。幣別與 price_currency_code 相同。

注意：系統只會為已設定新用戶優惠期的訂閱項目傳回此值。
introductoryPricePeriod 新用戶優惠的帳單週期（以 ISO 8601 格式指定）。

注意：系統只會為已設定新用戶優惠期的訂閱項目傳回此值。
introductoryPriceCycles 向使用者提供新用戶優惠的訂閱帳單週期數，例如 3。

注意：系統只會為已設定新用戶優惠期的訂閱項目傳回此值。

getBuyIntent() 方法

如實作 Google Play 帳款服務中所述，這種方法會傳回對應至 RESPONSE_CODE 索引的回應代碼整數，以及用於為對應至 BUY_INTENT 索引的應用程式內產品啟動購買流程的 PendingIntent。收到 PendingIntent 時，Google Play 會傳送回應 Intent 以及該訂購單的資料。表 6 匯總了回應 Intent 中傳回的資料。

注意：不建議您採用這種方法，而是使用可提供其他功能的 getBuyIntentExtraParams()。

表 6.Google Play 購買要求的回應資料。

索引 說明
RESPONSE_CODE 如果購買交易成功，值為 0，否則系統會顯示錯誤。
INAPP_PURCHASE_DATA 採用 JSON 格式的字串，其中包含訂購單的詳細資料。如需 JSON 欄位的説明，請參閲表 7。
INAPP_DATA_SIGNATURE 內容含有以開發人員私密金鑰簽署的交易資料簽章字串。資料簽章使用的是 RSASSA-PKCS1-v1_5 配置。

表 7 説明訂購單的回應資料中傳回的 JSON 欄位。

表 7.INAPP_PURCHASE_DATA 的 JSON 欄位說明。

欄位 說明
autoRenewing 表示訂閱項目是否自動續訂。如果為 true，則表示訂閲項目有效，並會在下次帳單日期自動續訂。如果為 false，則表示使用者已取消該訂閲項目。使用者在下次帳單日期前都能存取訂閱內容，屆時除非他們重新啟用自動續訂（或依據手動續訂中所述的方式手動續訂），否則將無法存取訂閱內容。如果您提供寬限期，只要寬限期尚未結束，系統會針對所有訂閲項目將此值設定爲 true。下次帳單日期每天都會動態延長，直到寬限期結束或使用者修正付款方式為止。
orderId 交易的專屬訂購單 ID。此 ID 與 Google 付款訂購單 ID 對應。
packageName 產生購買交易的應用程式套件。
productId 該商品的產品 ID。每項商品都有一個產品 ID，您必須在 Google Play 管理中心的應用程式產品清單中予以指定。
purchaseTime 產品的購買時間，以自 Epoch 紀元時間（1970 年 1 月 1 日）起的毫秒為單位。
purchaseState 訂購單的購買狀態。系統一律傳回 0（已購買）。
developerPayload 開發人員指定的字串，內容為有關訂購單的其他資訊。您可以在送出 getBuyIntent 要求時指定這個欄位的值。
purchaseToken 專門用來識別指定商品和使用者成對資料的購買交易權杖。

consumePurchase() 方法

使用與指定購買權杖所對應的購買內容。這將會造成商品從 getPurchases() 的所有後續回應中移除，並允許重新購買 SKU 相同的商品。

表 8.consumePurchase() 參數。

索引 類型 說明
apiVersion int 應用程式目前使用的 Google Play 帳款服務 AIDL 版本號碼。
packageName String 呼叫此方法的應用程式套件名稱。
purchaseToken String 購買資訊 JSON 中的權杖，用於識別要消費的購買交易。

消費成功時，這個方法會傳回 RESULT_OK(0)，失敗時則傳回適當的回應代碼。

getBuyIntentToReplaceSkus() 方法

這種方法用於將一項訂閱項目交易進行升級或降級。該方法與 getBuyIntent() 類似，差別在於它會取得一項清單，其中只包含一個已購買 SKU，用來被購買的 SKU 取代。使用者完成購買交易後，Google Play 會替換掉舊的 SKU，並將未使用的訂閲時間值按比例退還給使用者。Google Play 會將這筆抵免額套用到新的訂閱項目上，而且只有在抵免額用盡後，系統才會開始向使用者收取新訂閱項目的費用。

注意：不建議您採用這種方法，而是使用可提供其他功能的 getBuyIntentExtraParams()。

這個方法於 Google Play 帳款服務 AIDL 第 5 版時新增。若要確認系統是否會回報此方法，請傳送 isBillingSupported AIDL 要求。

注意：這種方法僅可用於購買訂閱項目。如果傳遞的 type 參數不是 "subs"，此方法會傳回 BILLING_RESPONSE_RESULT_DEVELOPER_ERROR。此外，傳遞的 SKU 不可包含按季訂閱項目的 SKU。

這種方法會傳回對應至 RESPONSE_CODE 索引的回應代碼整數，以及用於為對應至 BUY_INTENT 索引的應用程式內產品啟動購買流程的 PendingIntent。收到 PendingIntent 時，Google Play 會傳送回應 Intent 以及該訂購單的資料。表 9 匯總了回應 Intent 中傳回的資料。

表 9.Google Play 帳款服務 AIDL 第 5 版購買要求的回應資料。

索引 說明
RESPONSE_CODE 如果購買交易成功，值為 0。如果購買交易失敗，則會包含錯誤代碼。
INAPP_PURCHASE_DATA 採用 JSON 格式的字串，其中包含訂購單的詳細資料。如需 JSON 欄位的説明，請參閲表 6。
INAPP_DATA_SIGNATURE 內容含有開發人員以其私密金鑰簽署的交易資料簽章字串。資料簽章使用的是 RSASSA-PKCS1-v1_5 配置。

getBuyIntentExtraParams() 方法

這個方法會開始提出購買要求。此方法是 getBuyIntent() 方法的變化版本，需要額外的 extraParams 參數。這個參數是會影響方法運作、為選擇性索引和值的 Bundle，如表 10 所示。

表 10.getBuyIntentExtraParams() 額外參數。

索引 類型 說明
skusToReplace List<String> 選擇性清單，內容為使用者要將其升級或降級的一個 SKU。如果購買內容會將現有訂閱項目升級或降級，請傳遞這個欄位。指定的 SKU 會替換為使用者購買的 SKU。Google Play 會在下一個帳單週期開始時替換指定的 SKU。
replaceSkusProration boolean

指定是否應將使用者要升級或降級的 SKU 的未使用訂閲時間退款給使用者。如果將這個欄位設定為是，Google Play 會替換掉舊的 SKU，並將未使用的訂閲時間值按比例退還給使用者。Google Play 會將這筆抵免額套用到新的訂閱項目，而且只有在抵免額用盡後，系統才會開始向使用者收取新訂閱項目的費用。

如果將這個欄位設定為否，系統就不會將未使用的訂閲時間退還給使用者，並且週期日期保持不變。

預設值為是。如未傳遞 skusToReplace 則請忽略此值。
accountId String

經模糊處理的選擇性字串，只與應用程式中的使用者帳戶有關。如果傳遞此值，Google Play 可以利用此值來偵測異常活動，例如多個裝置在短時間內使用相同的帳戶購買產品。

這個欄位與 developerId 類似，代表的是一個單一使用者，但請注意，如果您有多個應用程式，同一使用者在每個應用程式可以有不同的 accountId，而 developerId 應可獨立用來識別所有應用程式中的一個使用者。

請勿在此欄位中使用 Google Play 管理中心的開發人員 ID 或使用者的 Google ID。此外，這個欄位不應包含明文形式的使用者 ID。建議您使用單向雜湊從使用者 ID 產生字串，並將雜湊字串儲存在這個欄位中。
developerId String

經模糊處理的選用字串，只與所有應用程式中的使用者帳戶有關。這個欄位與 accountId 類似，它代表一個使用者。不過，對於同一使用者，這個欄位在所有應用程式中應是相同的，而對於同一使用者，每個應用程式的 accountId 則是唯一的。

請勿在此欄位中使用 Google Play 管理中心的開發人員 ID 或使用者的 Google ID。此外，這個欄位不應包含明文形式的使用者 ID。建議您使用單向雜湊從使用者 ID 產生字串，並將雜湊字串儲存在這個欄位中。
vr boolean

指定提供的意圖是否代表開始虛擬實境 (VR) 購買流程。

注意：爲了讓這個額外參數對應用程式產生作用，您必須使用 Google Play 帳款服務 AIDL 第 7 版或更新的 API。

這種方法適用於 Google Play 帳款服務 AIDL 第 6 版及更高版本。

getPurchases() 方法

這種方法會傳回使用者擁有但目前未消耗的產品，包括購買的商品和透過兌換促銷代碼取得的商品。表 11 列出了 Bundle 中傳回的回應資料。

表 11.來自 getPurchases 要求的回應資料。

索引 說明
RESPONSE_CODE 如果要求成功，值為 0，否則系統會顯示錯誤。
INAPP_PURCHASE_ITEM_LIST StringArrayList，具有從這個應用程式購買的產品 ID 清單。
INAPP_PURCHASE_DATA_LIST StringArrayList，包含從這個應用程式的購買詳細資料。如要瞭解清單中的每個項目儲存的詳細資訊，請參閱表 13。
INAPP_DATA_SIGNATURE_LIST StringArrayList，其中含有從這個應用程式進行的交易簽章。
INAPP_CONTINUATION_TOKEN 含有用於擷取使用者擁有的下一組應用程式內產品的接續權杖字串。只有在使用者擁有的產品數量龐大時，Google Play 服務才會設定此字串。如果回應中有接續權杖，您必須再次呼叫 getPurchases 並傳遞您收到的接續權杖。後續的 getPurchases 呼叫會傳回更多購買交易，並可能傳回另一個接續權杖。

getPurchaseHistory() 方法

這種方法會傳回使用者針對各個 SKU 最近一次的購買交易，即使購買交易已過期、取消或消耗亦是如此。表 12 列出 Bundle 中傳回的回應資料：

表 12.來自 getPurchaseHistory 要求的回應資料。

索引 說明
RESPONSE_CODE 如果要求成功，值為 0，否則系統會顯示錯誤。
INAPP_PURCHASE_ITEM_LIST StringArrayList，其中含有從這個應用程式購買的產品 ID 清單。
INAPP_PURCHASE_DATA_LIST StringArrayList，包含從這個應用程式最近購買的詳細資料。如要瞭解清單中的每個 INAPP_PURCHASE_DATA 項目儲存的詳細資訊，請參閱表 6。
INAPP_DATA_SIGNATURE_LIST StringArrayList，其中含有從這個應用程式進行的交易簽章。
INAPP_CONTINUATION_TOKEN 含有用於擷取使用者擁有的下一組應用程式內產品的接續權杖字串。只有在使用者擁有的產品數量龐大時，Google Play 服務才會設定此字串。如果回應中有接續權杖，您必須再次呼叫 getPurchases 並傳遞您收到的接續權杖。後續的 getPurchases 呼叫會傳回更多購買交易，並可能傳回另一個接續權杖。

表 13.getPurchaseHistory() 傳回的購買記錄的 JSON 欄位說明。

欄位 說明
productId 該商品的產品 ID。每項商品都有一個產品 ID，您必須在 Google Play 管理中心的應用程式產品清單中予以指定。
purchaseTime 產品的購買時間，以自 Epoch 紀元時間（1970 年 1 月 1 日）起的毫秒為單位。
developerPayload 開發人員指定的字串，內容為有關訂購單的其他資訊。您可以在送出 getBuyIntent 要求時指定這個欄位的值。
purchaseToken 專門用來識別指定商品和使用者成對資料的購買交易權杖。

注意：getPurchaseHistory() 方法的負荷高於 getPurchases()，因為它必須呼叫 Google Play 伺服器。如果您並不需要使用者的購買記錄，應使用 getPurchases()。

這種方法適用於 Google Play 帳款服務 AIDL 第 6 版及更高版本。