Hệ thống thanh toán của Google Play là một dịch vụ cho phép bạn bán các sản phẩm và nội dung kỹ thuật số trong ứng dụng Android của mình. Với bản phát hành tháng 5 năm 2022, chúng tôi đã thay đổi cách xác định các sản phẩm thuê bao và điều này ảnh hưởng đến cách các sản phẩm đó được bán trong ứng dụng và được quản lý trên phần phụ trợ của bạn. Nếu đây là lần đầu tiên tích hợp với Google Play Billing, bạn có thể bắt đầu tích hợp bằng cách đọc phần Chuẩn bị.
Nếu đang bán gói thuê bao qua Google Play Billing trước tháng 5 năm 2022, bạn cần hiểu cách sử dụng các tính năng mới trong khi vẫn duy trì gói thuê bao hiện có.
Điều đầu tiên cần biết là tất cả các gói thuê bao, ứng dụng và dịch vụ tích hợp phụ trợ hiện có của bạn đều hoạt động giống như trước thời điểm phát hành tháng 5 năm 2022. Bạn không cần thực hiện bất kỳ thay đổi nào ngay lập tức và có thể áp dụng các tính năng mới này theo thời gian. Mỗi bản phát hành chính của Thư viện Google Play Billing được hỗ trợ trong hai năm sau khi phát hành. Các công cụ tích hợp hiện có thông quaAPI Nhà phát triển Google Play sẽ tiếp tục hoạt động như trước đây.
Dưới đây là thông tin tổng quan về nội dung cập nhật tháng 5 năm 2022:
- Google Play Console mới cho phép bạn tạo và quản lý gói thuê bao, gói cơ bản và ưu đãi. Quy định này áp dụng cho cả các gói thuê bao mới và đã di chuyển.
- API Nhà phát triển Play chứa các bản cập nhật để hỗ trợ chức năng mới trên giao diện người dùng của Google Play Console ở dạng API. Đáng chú ý là có một phiên bản mới của API Giao dịch mua gói thuê bao. Dùng API này để kiểm tra trạng thái của gói thuê bao và quản lý các giao dịch mua gói thuê bao.
- Thư viện Play Billing phiên bản 5 mới cho phép ứng dụng của bạn hưởng lợi từ tất cả tính năng của thuê bao mới. Khi bạn đã sẵn sàng nâng cấp lên phiên bản 5, hãy làm theo hướng dẫn trong hướng dẫn di chuyển.
Cấu hình gói thuê bao
Quản lý gói thuê bao qua Google Play Console
Kể từ tháng 5 năm 2022, bạn sẽ nhận thấy một số điểm khác biệt trong Google Play Console.
Một gói thuê bao hiện có thể có nhiều gói cơ bản vàưu đãi. Các SKU gói thuê bao được tạo trước đây hiện đã xuất hiện trong Play Console dưới dạng các đối tượng thuê bao, gói cơ bản và ưu đãi mới. Hãy xem qua Những thay đổi gần đây đối với các gói thuê bao trong Play Console để biết nội dung về các đối tượng mới, bao gồm cả chức năng và cấu hình của chúng nếu bạn chưa xem. Tất cả sản phẩm thuê bao hiện có của bạn sẽ xuất hiện trong Google Play Console ở định dạng mới này. Mỗi SKU hiện được biểu thị bằng một đối tượng gói thuê bao có chứa một gói cơ bản và ưu đãi tương thích ngược (nếu có).
Vì các tích hợp cũ hơn dự trù mỗi gói thuê bao sẽ bao gồm một ưu đãi duy nhất, do một đối tượng SkuDetails biểu thị, mỗi gói thuê bao có thể có một gói cơ bản hoặc ưu đãi tương thích ngược.
Gói cơ bản hoặc ưu đãi tương thích ngược sẽ được trả về trong SKU cho những ứng dụng đang dùng phương thức querySkuDetailsAsync() hiện không được dùng nữa.
Để biết thêm thông tin về cách định cấu hình và quản lý các ưu đãi tương thích ngược, hãy xem bài viết Tìm hiểu về các gói thuê bao. Khi ứng dụng của bạn chỉ dùng queryProductDetailsAsync() và khi chưa có phiên bản cũ nào của ứng dụng mua hàng, bạn không cần sử dụng ưu đãi tương thích ngược nữa.
Quản lý gói thuê bao thông qua API xuất bản gói thuê bao
API Nhà phát triển Play chứa các chức năng mới để mua gói thuê bao. API inappproducts để quản lý SKU tiếp tục hoạt động như trước đây, bao gồm cả việc xử lý các gói thuê bao và sản phẩm mua hàng một lần. Vì vậy, bạn không cần thay đổi gì ngay lập tức để duy trì việc tích hợp.
Tuy nhiên, điều quan trọng cần lưu ý là Google Play Console chỉ sử dụng các thực thể thuê bao mới. Một khi đã bắt đầu chỉnh sửa gói thuê bao trong Console, bạn sẽ không thể sử dụng API inappproducts cho gói thuê bao được nữa.
Nếu bạn đã sử dụng API phát hành trước tháng 5 năm 2022, thì mọi gói thuê bao hiện tại sẽ xuất hiện ở trạng thái chỉ đọc trong Google Play Console để tránh bất kỳ sự cố nào. Nếu bạn tìm cách thực hiện các thay đổi, bạn có thể sẽ nhận được cảnh báo giải thích về giới hạn này. Trước khi chỉnh sửa thêm gói thuê bao trong Console, bạn nên cập nhật tích hợp phụ trợ của mình để sử dụng điểm cuối Phát hành gói thuê bao mới. Các điểm cuối monetization.subscriptions, monetization.subscriptions.baseplans và monetization.subscriptions.offers cho phép bạn quản lý tất cả các gói cơ bản và ưu đãi hiện có. Bạn có thể xem cách các trường khác nhau ánh xạ từ thực thể InAppProduct sang các đối tượng mới trong monetization.subscriptions ở bảng dưới đây:
| InAppProduct | Gói thuê bao |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
Trang thông tin |
defaultPrice |
Không tương đương |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
Bản cập nhật API bắt buộc này chỉ áp dụng cho API phát hành (Quản lý SKU).
Thay đổi đối với Thư viện Play Billing
Để hỗ trợ di chuyển dần dần, Thư viện Play Billing bao gồm tất cả các phương thức và đối tượng có trong các phiên bản trước.
Các đối tượng SkuDetails và những hàm như querySkuDetailsAsync() vẫn tồn tại để bạn có thể nâng cấp sử dụng chức năng mới mà không phải cập nhật ngay mã thuê bao hiện có.
Bạn cũng có thể kiểm soát những ưu đãi nào có sẵn thông qua các phương thức này bằng cách đánh dấu các ưu đãi đó tương thích ngược.
Ngoài việc giữ lại các phương thức cũ, Play Billing 5 hiện còn có một đối tượng ProductDetails mới và một phương thức queryProductDetailsAsync() tương ứng để xử lý các thực thể và chức năng mới. ProductDetails hiện cũng hỗ trợ các sản phẩm trong ứng dụng (mua hàng một lần và hàng tiêu dùng).
Đối với gói thuê bao, ProductDetails.getSubscriptionOfferDetails() sẽ trả về danh sách tất cả các gói cơ bản và ưu đãi người dùng đủ điều kiện mua.
Điều này có nghĩa là bạn có thể truy cập vào tất cả các gói cơ bản và ưu đãi đủ điều kiện cho người dùng, bất kể khả năng tương thích ngược.
getSubscriptionOfferDetails() trả lại null cho các sản phẩm không đăng ký thuê bao. Đối với giao dịch mua hàng một lần, bạn có thể sử dụng getOneTimePurchaseOfferDetails().
Thư viện Play Billing 5 cũng bao gồm cả phương thức mới và phương thức cũ để bắt đầu quy trình mua. Nếu đối tượng BillingFlowParams chuyển đến BillingClient.launchBillingFlow() được định cấu hình bằng đối tượng SkuDetails, hệ thống sẽ trích xuất thông tin ưu đãi để bán từ gói cơ bản tương thích ngược hoặc ưu đãi tương ứng với SKU. Nếu đối tượng BillingFlowParams truyền vào BillingClient.launchBillingFlow() được định cấu hình bằng cách sử dụng các đối tượng ProductDetailsParams, bao gồm ProductDetails và String biểu thị mã thông báo ưu đãi cụ thể cho ưu đãi đang được mua, hệ thống sẽ sử dụng thông tin đó để xác định sản phẩm người dùng đang mua.
queryPurchasesAsync() trả về tất cả giao dịch mua của người dùng. Để cho biết loại sản phẩm được yêu cầu, bạn có thể truyền giá trị BillingClient.SkuType như trong các phiên bản cũ hoặc đối tượng QueryPurchasesParams chứa giá trị BillingClient.ProductType biểu thị thực thể thuê bao mới.
Bạn nên sớm cập nhật ứng dụng của mình lên phiên bản 5 của thư viện để có thể bắt đầu tận dụng các tính năng thuê bao mới này.
Quản lý trạng thái của gói thuê bao
Phần này mô tả những thay đổi chính đối với các thành phần phụ trợ của tích hợp hệ thống thanh toán Google Play cần được triển khai để di chuyển sang phiên bản 5.
Thông báo theo thời gian thực dành cho nhà phát triển
Đối tượng SubscriptionNotification sắp không còn chứa subscriptionId. Nếu dựa vào trường này để xác định sản phẩm thuê bao, bạn cần cập nhật để có được thông tin như vậy từ trạng thái của gói thuê bao bằng cách sử dụng purchases.subscriptionv2:get sau khi nhận được thông báo. Mỗi phần tử SubscriptionPurchaseLineItem trong tập hợp lineItems được trả về ở trạng thái mua sẽ bao gồm productId tương ứng.
Subscription Purchases API (API Giao dịch mua gói thuê bao): nhận trạng thái gói thuê bao
Trong các phiên bản trước của API Giao dịch mua gói thuê bao, bạn có thể truy vấn trạng thái đăng ký bằng cách sử dụng purchases.subscriptions:get.
Điểm cuối này không thay đổi và tiếp tục hoạt động cho các giao dịch mua gói thuê bao tương thích ngược. Điểm cuối này không hỗ trợ bất kỳ chức năng mới nào được phát hành vào tháng 5 năm 2022.
Trong phiên bản mới của API Giao dịch mua gói thuê bao, hãy sử dụng purchases.subscriptionsv2:get để nhận trạng thái mua gói thuê bao. API này tương thích với các gói thuê bao đã di chuyển, các gói thuê bao mới (cả trả trước và tự động gia hạn) cũng như các giao dịch mua dưới mọi hình thức. Bạn có thể sử dụng điểm cuối này để kiểm tra trạng thái của gói thuê bao khi nhận được thông báo. Đối tượng được trả về SubscriptionPurchaseV2 chứa các trường mới, nhưng vẫn bao gồm dữ liệu cũ cần thiết để tiếp tục hỗ trợ các gói thuê bao hiện có.
Trường SubscriptionPurchaseV2 cho gói trả trước
Chúng tôi đã thêm các trường mới để hỗ trợ gói trả trước. Đây là gói được người dùng tự mua thêm thay vì tự động gia hạn. Tất cả các trường sẽ áp dụng cho các gói trả trước như khi áp dụng cho gói thuê bao tự động gia hạn, trừ những trường hợp ngoại lệ sau:
- [Trường mới] lineItems[0].prepaid_plan.allowExtendAfterTime: biểu thị việc người dùng được phép mua một khoản nạp tiền khác để gia hạn gói trả trước, vì mỗi lần người dùng chỉ được có một khoản nạp tiền không sử dụng.
- [Trường mới] SubscriptionState: chỉ định trạng thái của đối tượng gói thuê bao.
Đối với các gói trả trước, giá trị này luôn là
ACTIVE,PENDINGhoặcCANCELED. - lineItems[0].expiryTime: Trường này luôn hiển thị đối với các gói trả trước.
- pause_state_context: Trường này không bao giờ xuất hiện, vì các gói trả trước không thể tạm dừng.
- lineItems[0].auto_refreshing_plan: Không áp dụng cho các gói trả trước.
- canceled_state_context: Không hiển thị đối với các gói trả trước, vì trường này chỉ áp dụng cho những người dùng chủ động huỷ gói thuê bao.
- lineitems[0].productId: Trường này thay thế cho
subscriptionIdtừ các phiên bản trước.
Trường SubscriptionPurchaseV2 cho các gói thuê bao định kỳ
purchases.subscriptionv2 chứa các trường mới cung cấp thêm thông tin về đối tượng thuê bao mới. Bảng sau đây cho thấy cách các trường từ điểm cuối của gói thuê bao liên kết đến các trường tương ứng trong purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (không có trường tương đương) | lineItems (danh sách SubscriptionPurchaseLineItem) biểu thị các sản phẩm có được khi mua hàng |
| (không có trường tương đương) | lineItems.offerDetails.basePlanId |
| (không có trường tương đương) | lineItems.offerDetails.offerId |
| (không có trường tương đương) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (mỗi gói thuê bao có được trong giao dịch mua đều có expiryTime riêng) |
| (không có trường tương đương) | subscriptionState (cho biết trạng thái của gói thuê bao) |
| (không có trường tương đương) | pausedStateContext (chỉ hiển thị nếu trạng thái của gói thuê bao là SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (không có trường tương đương) | canceledStateContext (chỉ hiển thị nếu trạng thái của gói thuê bao là SUBSCRIPTION_STATE_CANCELED) |
| (không có trường tương đương) | testPurchase (chỉ hiển thị trong giao dịch mua kiểm thử được cấp phép) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode, priceAmountMicros, introductoryPriceInfo |
(không có trường tương đương) Bạn có thể tìm thấy thông tin này trong basePlan/offer cho từng gói thuê bao đã mua. |
| developerPayload | (không có trường tương đương) trọng tải dành cho nhà phát triển đã không còn được dùng nữa |
| paymentState | (không có trường tương đương) Bạn có thể dự đoán trạng thái thanh toán từ subscriptionState:
|
cancelReason, userCancellationTimeMillis, cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (không có thay đổi) |
purchaseType |
Kiểm thử: thông qua testPurchaseKhuyến mãi: (không có trường tương đương); sắp ra mắt |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName emailAddress, givenName, familyName, profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType, promotionCode |
(không có trường tương đương); sắp ra mắt |
externalAccountId, obfuscatedExternalAccountId, obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Các chức năng quản lý gói thuê bao khác
Trong khipurchases.subscriptions:get đã được nâng cấp lên purchases.subscriptionsv2:get, các chức năng quản lý thuê bao còn lại của nhà phát triển hiện vẫn không thay đổi trong điểm cuốipurchases.subscriptions để bạn có thể tiếp tục sử dụng purchases.subscriptions:acknowledge .purchases.subscriptions:cancel .purchases.subscriptions:defer .purchases.subscriptions:refund, và purchases.subscriptions:revoke như đã làm trước đó.
API Giá
Sử dụng điểm cuối monetization.convertRegionPrices để tính giá theo khu vực như bạn sẽ thực hiện thông qua Play Console. Phương thức này chấp nhận một mức giá duy nhất bằng bất kỳ loại tiền tệ nào mà Play hỗ trợ và trả về giá đã quy đổi (bao gồm thuế suất mặc định nếu có) cho tất cả các khu vực Google Play hỗ trợ giao dịch mua.