Lưu ý: Kể từ ngày 2 tháng 8 năm 2022, tất cả các ứng dụng mới phải sử dụng Thư viện Billing phiên bản 4 trở lên. Chậm nhất vào ngày 1 tháng 11 năm 2022, tất cả các bản cập nhật cho ứng dụng hiện có đều phải sử dụng Thư viện Billing phiên bản 4 trở lên. Tìm hiểu thêm.

Hướng dẫn về các thay đổi đối với gói thuê bao tháng 5 năm 2022

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 thực hiện giao dịch bán chúng trong ứng dụng cũng như quản lý 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 Tìm hiểu về các gói thuê bao. Khi ứng dụng của bạn chỉ sử dụng queryProductDetailsAsync() và khi chưa có ứng dụng phiên bản nào cũ 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ý cho các sản phẩm và thuê bao mua một lần, vì vậy bạn không cần thực hiện bất kỳ thay đổi nào 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 Bảng điều khiển, 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 Bảng điều khiển, 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 của Phát hành gói thuê bao mới. Các điểm cuối monetization.subscriptions, monetization.subscriptions.baseplansmonetization.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 và hàm SkuDetails 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ã đăng ký 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 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 chuyển đến BillingClient.launchBillingFlow() được định cấu hình bằng cách sử dụng các đối tượng ProductDetailsParams, bao gồm ProductDetailsString đại diện cho mã thông báo ưu đãi cụ thể cho ưu đãi sau khi được mua hàng, 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 trong 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 đại diện cho 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 không còn chứa subscriptionId (ID thuê bao). Nếu dựa vào trường này để xác định sản phẩm thuê bao, bạn nên cập nhật lấy thông tin này từ trạng thái đăng ký bằng cách sử dụng purchases.subscriptionv2:get một khi bạn nhận được thông báo.

API giao dịch mua gói thuê bao: theo dõi 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ó.

Các trường dành cho SubscriptionPurchaseV2

Chúng tôi đã thêm các trường mới để hỗ trợ các gói trả trước, 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 họ đăng ký 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 nạp tiền để gia hạn gói trả trước khi người dùng được phép nạp tiền không tiêu thụ một lần.
  • [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, PENDING hoặc CANCELED.
  • lineItems[0].expiryTime: Trường này luôn biểu thị cho 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ị cho các gói trả trước, vì trường này chỉ áp dụng cho những người dùng hủy gói thuê bao.
  • lineitems[0].productId: Trường này thay thế cho subscriptionId từ 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ị cho các sản phẩm đã có được khi mua hàng
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ỉ biểu 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ỉ biểu 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ỉ biểu thị trong giao dịch mua thử nghiệm đượ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:
  • Khoản thanh toán đang chờ xử lý:
    • SUBSCRIPTION_STATE_PENDING (giao dịch mua mới đang chờ xử lý)
    • SUBSCRIPTION_STATE_IN_GRACE_PERIOD
    • SUBSCRIPTION_STATE_ON_HOLD
  • Thanh toán đã được nhận:
    • SUBSCRIPTION_STATE_ACTIVE
  • Dùng thử miễn phí:
    • (không có trường tương đương); sắp ra mắt
  • Tạm hoãn nâng cấp/hạ cấp:
    • SUBSCRIPTION_STATE_PENDING
cancelReason, userCancellationTimeMillis, cancelSurveyResult canceledStateContext
linkedPurchaseToken linkedPurchaseToken (không có thay đổi)
purchaseType Thử nghiệm: thông qua testPurchase
Khuyến mãi: (không có trường tương đương); sắp ra mắt
priceChange (không có trường tương đương); sắp ra mắt
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 được 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.