本文說明如何整合 Play 結帳服務程式庫 API,以便在符合資格的應用程式中提供外部付款方式。如要進一步瞭解這項計畫,請參閱計畫規定。
Play 帳款服務程式庫設定
請將 Play 帳款服務程式庫依附元件新增至您的 Android 應用程式。您需要採用 8.3 以上版本,才能使用外部付款系統 API。如需從舊版遷移至新版,請先按照遷移指南的指示操作,再開始整合。
初始化帳單用戶端
整合程序的前幾個步驟如同 Google Play 帳款服務整合指南所述,但初始化 BillingClient 的做法有些改變:
- 您需要呼叫新的
enableBillingProgram(EnableBillingProgramParams)方法,指出想提供外部付款方式。 - 您需要註冊
DeveloperProvidedBillingListener,才能處理使用者選擇在您的網站或付款應用程式中付款的情況。
以下範例說明如何透過變更後的做法初始化 BillingClient:
Kotlin
val purchasesUpdatedListener =
PurchasesUpdatedListener { billingResult, purchases ->
// Handle new Google Play purchase.
}
val developerProvidedBillingListener =
DeveloperProvidedBillingListener { details ->
// Handle user selection for developer provided billing option.
}
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build()
Java
private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
@Override
public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
// Handle new Google Play purchase.
}
};
private DeveloperProvidedBillingListener developerProvidedBillingListener =
new DeveloperProvidedBillingListener() {
@Override
public void onUserSelectedDeveloperBilling(
DeveloperProvidedBillingDetails details) {
// Handle user selection for developer provided billing option.
}
};
private BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build();
連線至 Google Play
初始化 BillingClient 後,請按照「連結至 Google Play」一文的說明,連線至 Google Play。
檢查使用者資格
連結至 Google Play 後,您可以呼叫 isBillingProgramAvailableAsync() 方法,確認使用者是否符合外部付款計畫的資格。如果使用者符合資格,這個方法會傳回 BillingResponseCode.OK。以下範例說明如何檢查資格:
Kotlin
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
object : BillingProgramAvailabilityListener {
override fun onBillingProgramAvailabilityResponse(
billingProgram: Int, billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return
}
// External payments are available. Can proceed with generating an
// external transaction token.
})
Java
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
new BillingProgramAvailabilityListener() {
@Override
public void onBillingProgramAvailabilityResponse(
int billingProgram, BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return;
}
// External payments are available. Can proceed with generating an external transaction token.
}
});
如要進一步瞭解應用程式應如何回應其他回應代碼,請參閱「回應處理」一節。如果您使用 Kotlin 擴充功能,可以採用 Kotlin 協同程式,因此不需定義單獨的事件監聽器。
顯示可購買的產品
您可以按照整合 Google Play 結帳系統的做法,向使用者顯示可購買的產品。當使用者看到可購買的產品,並選取想買的商品時,請根據「啟動外部付款流程」一節的說明啟動外部付款流程。
準備外部交易憑證
如要向 Google Play 回報外部交易,您必須擁有 Play 帳款服務程式庫產生的外部交易憑證。每當使用者透過外部付款系統 API 造訪外部網站或應用程式時,系統都必須產生新的外部交易權杖。只要呼叫 createBillingProgramReportingDetailsAsync API,即可進行確認。應在呼叫 launchBillingFlow 之前立即產生權杖。
Kotlin
val params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build()
billingClient.createBillingProgramReportingDetailsAsync(
params,
object : BillingProgramReportingDetailsListener {
override fun onCreateBillingProgramReportingDetailsResponse(
billingResult: BillingResult,
billingProgramReportingDetails: BillingProgramReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
billingProgramReportingDetails?.externalTransactionToken
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
})
Java
BillingProgramReportingDetailsParams params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build();
billingClient.createBillingProgramReportingDetailsAsync(
params,
new BillingProgramReportingDetailsListener() {
@Override
public void onCreateBillingProgramReportingDetailsResponse(
BillingResult billingResult,
@Nullable BillingProgramReportingDetails
billingProgramReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
billingProgramReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
});
如果您使用 Kotlin 擴充功能,可以採用 Kotlin 協同程式,因此不必定義單獨的事件監聽器。
啟動外部付款流程
呼叫 launchBillingFlow() 啟動外部付款流程,做法與啟動購買流程類似,但須額外提供 DeveloperBillingOptionParams 參數,指出應用程式要為這筆交易啟用外部付款流程。
DeveloperBillingOptionParams 必須包含下列項目:
billingProgram已設為EXTERNAL_PAYMENTS結帳系統計畫linkURI設為連結目的地launchMode設為LAUNCH_IN_EXTERNAL_BROWSER_OR_APP,表示連結應由 Google Play 啟動;設為CALLER_WILL_LAUNCH_LINK,表示連結應由您的應用程式啟動。
當應用程式呼叫 launchBillingFlow() 並提供 DeveloperBillingOptionParams 時,Google Play 結帳系統會執行下列檢查:
- 系統會檢查使用者的 Google Play 國家/地區是否支援外部付款 (如果支援的話,即為支援的國家/地區)。如果使用者的 Google Play 國家/地區受到支援,Google Play 會檢查外部付款是否已根據 BillingClient 的設定啟用,以及是否提供
DeveloperBillingOptionParams。- 如果已啟用外部付款系統,購買流程會顯示使用者自選 UX。
- 如果未啟用外部付款,購買流程會顯示標準 Google Play 結帳系統的使用者體驗,而且使用者無法選擇結帳系統。
- 如果使用者的 Google Play 國家/地區不受支援,購買流程會顯示標準 Google Play 結帳系統的使用者體驗,而且使用者無法選擇結帳系統。
使用者的 Play 國家/地區受到支援 |
使用者的 Play 國家/地區不受支援 |
|
已啟用外部付款 (BillingClient 設定和 launchBillingFlow) |
顯示可供自選的使用者體驗 |
顯示標準 Google Play 結帳系統的使用者體驗 |
未啟用外部付款系統 (在設定 BillingClient 時未啟用,或未提供 DeveloperBillingOptionParams 來啟動 launchBillingFlow) |
顯示標準 Google Play 結帳系統的使用者體驗 |
顯示標準 Google Play 結帳系統的使用者體驗 |
下列程式碼片段示範如何建構 DeveloperBillingOptionParams:
Kotlin
val developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri("https://www.example.com/external/purchase")
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build()
Java
DeveloperBillingOptionParams developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri("https://www.example.com/external/purchase")
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build();
依使用者選擇的結帳系統處理購買流程
請視情況以不同方式處理剩餘的購買流程,實際做法取決於使用者選擇 Google Play 結帳系統或在您的網站上付款。
使用者選擇在你的網站或付款應用程式中付款
如果使用者選擇在您的網站上付款,Google Play 會呼叫 DeveloperProvidedBillingListener,通知應用程式使用者選擇在您的網站或付款應用程式上付款。具體來說,系統會呼叫 onUserSelectedDeveloperBilling() 方法。
如果應用程式將 launchMode 設為 LAUNCH_IN_EXTERNAL_BROWSER_OR_APP,Google Play 就會啟動連結。如果 launchMode 設為 CALLER_WILL_LAUNCH_LINK,應用程式會負責啟動連結。將使用者連結至付款應用程式時,您有責任確認使用者裝置上已安裝付款應用程式。
請按照後端整合指南的說明,使用此權杖回報這項選擇產生的所有交易。
使用者選擇 Google Play 結帳系統
如果使用者選擇 Google Play 結帳系統,就會透過 Google Play 繼續購買商品。
處理訂閱項目異動
如果開發人員採用外部付款方式,就需要透過 Google Play 結帳系統處理購買交易,或是以 externalTransactionId 回報交易,具體做法視使用者的選擇而異。原先透過開發人員網站處理的現有訂閱項目到期前,您可以透過相同的結帳系統變更這類訂閱項目。
本節將說明如何處理常見的訂閱項目異動情形。
升級與降級流程
建議您視情況以不同方式處理訂閱方案變更 (包括升級與降級流程),實際做法取決於使用者原本透過 Google Play 結帳系統或開發人員網站購買訂閱項目。
如果加購內容與現有訂閱項目相關聯,且使用相同的付款方式,並採用一致的週期性收費,系統會將其視為升級。對於其他加購內容,使用者應該要能依需求選擇結帳系統。如要啟動新的購買流程,請使用 launchBillingFlow(),詳情請參閱啟動外部付款流程。
透過開發人員網站或付款應用程式購買的訂閱項目
如果使用者做出選擇後原本是以開發人員的網站或付款應用程式購買訂閱項目,要求升級或降級時就不必重新選擇,而是應該透過開發人員的網站或付款應用程式操作。
如要採取上述做法,請在使用者要求升級或降級時呼叫 launchBillingFlow()。請勿在 SubscriptionUpdateParams 物件下指定其他參數,而是要改用 setOriginalExternalTransactionId() 提供原始購買交易的外部交易 ID。
您也必須在這項呼叫中提供 DeveloperBillingOptionParams。這種做法不會顯示使用者選擇畫面,因為升級與降級流程將沿用使用者為原始交易選擇的結帳系統。您必須為這筆交易產生新的外部交易憑證,詳情請參閱這篇文章。
如果使用者透過開發人員的網站或付款應用程式完成升級或降級流程,您需要回報新交易,做法是使用先前呼叫新訂閱項目購買交易時所取得的外部交易憑證。
透過 Google Play 結帳系統購買的訂閱項目
同樣地,如果使用者選擇以 Google Play 結帳系統購買現有訂閱項目,開發人員也應為他們顯示標準 Google Play 結帳流程。呼叫 launchBillingFlow 時,不得設定 DeveloperBillingOptionParams。
取消與恢復訂閱
使用者應該要隨時都能取消訂閱。如果使用者取消訂閱,系統可能會延後到付費週期結束時才終止授權。舉例來說,若使用者在某月中旬取消按月訂閱,在存取權遭移除前,他們大約還有 2 週的時間能夠繼續存取服務。在這段期間,訂閱項目嚴格來說仍處於有效狀態,因此使用者可以存取服務。
使用者在訂閱項目依然有效的期間,通常不會決定撤銷取消作業。在本指南中,復原取消作業的行為稱作「恢復」訂閱。以下各節將說明如何在外部付款 API 整合程序中,處理恢復訂閱的情況。
透過開發人員網站購買的訂閱項目
如有已取消訂閱項目的外部交易 ID,就不必呼叫 launchBillingFlow() 恢復訂閱,因此這個方法不應該用於這類啟用作業。若使用者在已取消訂閱項目依然有效的期間恢復訂閱,這時不會進行任何交易;您可以直接在當前週期結束及下次續訂時,繼續回報續訂交易。這包括使用者在恢復訂閱時享有抵免額或特殊續訂價格的情況,例如開發人員提供促銷優惠鼓勵使用者繼續訂閱。
透過 Google Play 結帳系統購買的訂閱項目
一般來說,使用者可以在 Google Play 結帳系統中恢復訂閱。 如果取消的訂閱項目原本是以 Google Play 結帳系統購得,使用者可選擇在訂閱項目依然有效的期間,透過 Google Play 的重新訂閱功能復原取消操作。在此情況下,您會在後端收到 SUBSCRIPTION_RESTARTED 即時開發人員通知,但系統不會核發新的購買憑證,而是使用原先的憑證繼續訂閱。如要瞭解如何在 Google Play 結帳系統中管理恢復訂閱事宜,請參閱訂閱管理指南的「復原」一節。
您也可以呼叫 launchBillingFlow(),從應用程式中觸發 Google Play 結帳系統的恢復訂閱作業。如要瞭解相關做法,請參閱「訂閱到期前 - 應用程式內」。如果使用者原先購買訂閱項目 (現已取消但依然有效) 時曾選擇結帳系統,系統會自動偵測他們當時的選擇,並顯示用來還原購買交易的使用者介面。使用者需要確認透過 Google Play 重新購買訂閱項目,但不必再次選擇結帳系統。在此情況下,系統會為使用者核發新的購買憑證。您的後端會收到 SUBSCRIPTION_PURCHASED 即時開發人員通知,而新交易狀態的 linkedPurchaseToken 值也會按照訂閱項目升級或降級的情況,使用已取消訂閱項目的舊有購買憑證進行設定。
重新訂閱
如果訂閱項目完全過期,無論是因為取消訂閱或付款遭拒而未復原 (超過帳戶保留期),使用者都必須重新訂閱才能再次啟動授權程序。
您也可以採取類似標準註冊流程的處理方式,透過應用程式啟用重新訂閱功能。使用者應該要能依需求選擇結帳系統。在此情況下,您可以按照「啟動外部付款流程」的說明呼叫 launchBillingFlow()。
回應處理
發生錯誤時,方法 isBillingProgramAvailableAsync()、createBillingProgramReportingDetailsAsync()、launchBillingFlow() 可能會提供 BillingResponseCode.OK 以外的 BillingResponseCode。建議您按照下列方式處理這些回應碼:
BillingResponseCode.ERROR:這是內部錯誤。請勿繼續交易或開啟外部網站。再次呼叫 API 即可重試。BillingResponseCode.FEATURE_NOT_SUPPORTED:目前裝置的 Play 商店不支援外部付款 API。請勿繼續交易或開啟外部網站。BillingResponseCode.DEVELOPER_ERROR:要求出錯。請先使用偵錯訊息找出並修正錯誤,然後再繼續操作。BillingResponseCode.USER_CANCELED:請勿繼續開啟外部網站或應用程式。再次呼叫launchBillingFlow(),在下次嘗試將使用者導向應用程式外部時,向他們顯示資訊對話方塊。BillingResponseCode.BILLING_UNAVAILABLE:交易不符合外部付款資格,因此無法透過本計畫使用開發人員結帳服務。這是因為使用者不在本計畫適用的國家/地區,或是您的帳戶未成功註冊加入計畫。如果原因是後者,請前往 Play 管理中心查看註冊狀態。BillingResponseCode.NETWORK_ERROR、BillingResponseCode.SERVICE_DISCONNECTED、BillingResponseCode.SERVICE_UNAVAILABLE:這些是暫時性錯誤,應使用適當的重試政策處理。當出現SERVICE_DISCONNECTED時,請在重試前重新建立與 Google Play 的連線。
測試外部付款連結
請使用授權測試人員測試外部付款整合。 系統不會針對授權測試人員帳戶發起的交易開立月結單。如要進一步瞭解如何設定授權測試人員,請參閱「透過應用程式授權來測試應用程式內結帳服務」。
後續步驟
完成應用程式內整合作業後,即可開始整合後端。