Hướng dẫn tham khảo về thông báo theo thời gian thực dành cho nhà phát triển

Chủ đề này liệt kê và mô tả các loại Thông báo theo thời gian thực dành cho nhà phát triển mà bạn có thể nhận được từ Google Play.

Mã hoá

Mỗi lượt phát hành được tạo cho một chủ đề Cloud Pub/Sub, trong đó chứa một trường dữ liệu được mã hoá base64.

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

Sau khi bạn giải mã trường dữ liệu được mã hoá base64, DeveloperNotification sẽ chứa các trường sau:

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "testNotification": TestNotification
}

Các trường này được mô tả trong bảng sau.

Tên thuộc tính Giá trị Mô tả
version string Phiên bản của thông báo này. Ban đầu, đây là phiên bản "1.0". Phiên bản này khác với các trường của phiên bản khác.
packageName string Tên gói của ứng dụng mà thông báo này có liên quan (ví dụ: "com.some.thing").
eventTimeMillis long Dấu thời gian khi sự kiện diễn ra, tính bằng mili giây kể từ Thời gian bắt đầu của hệ thống.
subscriptionNotification SubscriptionNotification Nếu có trường này thì thông báo này liên quan đến một gói thuê bao và chứa thông tin bổ sung liên quan đến gói thuê bao đó. Xin lưu ý rằng bạn không thể dùng cùng lúc trường này với các trường oneTimeProductNotification, voidedPurchaseNotification và testNotification.
oneTimeProductNotification OneTimeProductNotification Nếu có trường này thì thông báo này liên quan đến giao dịch mua hàng một lần và trường này chứa thông tin bổ sung liên quan đến giao dịch mua đó. Xin lưu ý rằng bạn không thể dùng cùng lúc trường này với các trường subscriptionNotification, voidedPurchaseNotification và testNotification.
voidedPurchaseNotification VoidedPurchaseNotification Nếu có trường này thì thông báo này liên quan đến một giao dịch mua vô hiệu và trường này chứa thông tin bổ sung liên quan đến giao dịch mua vô hiệu đó. Xin lưu ý rằng bạn không thể dùng cùng lúc trường này với các trường oneTimeProductNotification, subscriptionNotification và testNotification.
testNotification TestNotification Nếu có trường này thì thông báo này liên quan đến một hoạt động kiểm thử phát hành. Thông báo này chỉ được gửi qua Google Play Console. Xin lưu ý rằng bạn không thể dùng cùng lúc trường này với các trường oneTimeProductNotification, subscriptionNotification và voidedPurchaseNotification.

SubscriptionNotification

SubscriptionNotification chứa các trường sau:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string
}
Tên thuộc tính Giá trị Mô tả
version string Phiên bản của thông báo này. Ban đầu, đây là phiên bản "1.0". Phiên bản này khác với các trường của phiên bản khác.
notificationType int notificationType cho một gói thuê bao có thể có các giá trị sau:
  • (1) SUBSCRIPTION_RECOVERED – Gói thuê bao được khôi phục từ tài khoản bị tạm ngưng.
  • (2) SUBSCRIPTION_RENEWED – Gói thuê bao đang hoạt động được gia hạn.
  • (3) SUBSCRIPTION_CANCELED – Gói thuê bao bị huỷ theo cách tự nguyện hoặc không tự nguyện. Đối với trường hợp huỷ tự nguyện, nội dung này được gửi khi người dùng huỷ.
  • (4) SUBSCRIPTION_PURCHASED – Người dùng mua một gói thuê bao mới.
  • (5) SUBSCRIPTION_ON_HOLD – Gói thuê bao đã chuyển sang trạng thái tạm ngưng tài khoản (nếu đã bật).
  • (6) SUBSCRIPTION_IN_GRACE_PERIOD – Gói thuê bao đã bước vào thời gian gia hạn (nếu được bật).
  • (7) SUBSCRIPTION_RESTARTED – Người dùng đã khôi phục gói thuê bao trên Play > Account > Subscriptions (Play > Tài khoản > Gói thuê bao). Gói thuê bao đã bị huỷ nhưng chưa hết hạn khi người dùng khôi phục. Để biết thêm thông tin, hãy xem phần Khôi phục.
  • (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED (KHÔNG DÙNG NỮA) – Người dùng đã xác nhận thành công việc thay đổi giá gói thuê bao.
  • (9) SUBSCRIPTION_DEFERRED – Thời gian đăng ký định kỳ của gói thuê bao đã được kéo dài.
  • (10) SUBSCRIPTION_PAUSED – Gói thuê bao đã bị tạm dừng.
  • (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED – Lịch biểu tạm dừng gói thuê bao đã thay đổi.
  • (12) SUBSCRIPTION_REVOKED – Người dùng đã thu hồi gói thuê bao trước thời gian hết hạn.
  • (13) SUBSCRIPTION_EXPIRED – Gói thuê bao đã hết hạn.
  • (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED – Giao dịch đang chờ xử lý của một gói thuê bao đã bị huỷ.
  • (19) SUBSCRIPTION_PRICE_CHANGE_UPDATED – Thông tin chi tiết về việc thay đổi giá của một mục trong gói thuê bao đã được cập nhật.
purchaseToken string Mã thông báo được cung cấp cho thiết bị của người dùng khi người dùng mua gói thuê bao.

Ví dụ

Dưới đây là ví dụ về thông báo giao dịch mua gói thuê bao mới:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN"
  }
}

OneTimeProductNotification

OneTimeProductNotification chứa các trường sau:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "sku": string
}
Tên thuộc tính Giá trị Mô tả
version string Phiên bản của thông báo này. Ban đầu, phiên bản này sẽ là "1.0". Phiên bản này khác với các trường của phiên bản khác.
notificationType int Loại thông báo. Thuộc tính này có thể có các giá trị sau:
  • (1) ONE_TIME_PRODUCT_PURCHASED – Người dùng đã mua thành công sản phẩm tính phí một lần.
  • (2) ONE_TIME_PRODUCT_CANCELED - Người dùng đã huỷ giao dịch mua sản phẩm tính phí một lần đang chờ xử lý.
purchaseToken string Mã thông báo được cung cấp cho thiết bị của người dùng khi họ thực hiện giao dịch mua.
sku string Mã sản phẩm tính phí một lần (ví dụ: "sword_001")

Ví dụ

Dưới đây là ví dụ về thông báo cho giao dịch mua hàng một lần mới:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "oneTimeProductNotification":
  {
    "version":"1.0",
    "notificationType":1,
    "purchaseToken":"PURCHASE_TOKEN",
    "sku":"my.sku"
  }
}

VoidedPurchaseNotification

VoidedPurchaseNotification chứa các trường sau:

Tên thuộc tính

Giá trị

Mô tả

purchaseToken

string

Mã thông báo này liên kết với giao dịch mua hàng đã bị vô hiệu. Thông tin này được cung cấp cho nhà phát triển khi có một giao dịch mua hàng mới diễn ra.

orderId

string

Mã đơn hàng duy nhất được liên kết với giao dịch đã bị vô hiệu. Đối với giao dịch mua hàng một lần, mã này đại diện cho mã đơn hàng duy nhất được tạo cho giao dịch đó. Đối với các gói thuê bao tự động gia hạn, một mã đơn hàng mới sẽ được tạo cho mỗi giao dịch gia hạn.

productType

int

productType của một giao dịch mua vô hiệu có thể có các giá trị sau:

  • (1) PRODUCT_TYPE_SUBSCRIPTION – Giao dịch mua gói thuê bao đã bị vô hiệu.
  • (2) PRODUCT_TYPE_ONE_TIME – Giao dịch mua hàng một lần đã bị vô hiệu.

refundType

int

refundType của một giao dịch mua vô hiệu có thể có các giá trị sau:

  • (1) REFUND_TYPE_FULL_REFUND – Giao dịch mua đã bị vô hiệu hoàn toàn.
  • (2) REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND – Giao dịch mua đã bị vô hiệu một phần do hoàn tiền một phần theo số lượng, chỉ áp dụng cho giao dịch mua số lượng nhiều. Một giao dịch mua có thể bị vô hiệu một phần nhiều lần.

Lưu ý khi tổng số lượng còn lại của một giao dịch mua nhiều số lượng được hoàn tiền, refundType sẽ là REFUND_TYPE_FULL_REFUND.

Ví dụ

Dưới đây là ví dụ về thông báo cho một giao dịch mua mới bị vô hiệu:

{
  "version":"1.0",
  "packageName":"com.some.app",
  "eventTimeMillis":"1503349566168",
  "voidedPurchaseNotification":
  {
    "purchaseToken":"PURCHASE_TOKEN",
    "orderId":"GS.0000-0000-0000",
    "productType":1
    "refundType":1
  }
}

Sử dụng VoidedPurchaseNotification

Khi máy khách RTDN của bạn nhận được một VoidedPurchaseNotification, hãy lưu ý thông tin sau:

  • packageName: Mã này giúp xác định ứng dụng.
  • eventTimeMillis: Mã này cho nhà phát triển biết về thời gian diễn ra thay đổi trạng thái.
  • purchaseToken: Mã thông báo được cung cấp cho thiết bị của người dùng khi sản phẩm được mua.
  • orderId: Mã này xác định đơn đặt hàng liên kết với giao dịch vô hiệu.
  • productType: Mã này cho bạn biết giao dịch mua vô hiệu là giao dịch mua hàng trong ứng dụng hay gói thuê bao.
  • refundType: Mã này cho bạn biết loại khoản hoàn tiền đã vô hiệu hoá giao dịch mua.

Nếu tất cả những gì bạn cần làm để điều chỉnh quyền là tìm giao dịch mua hàng và đơn đặt hàng thích hợp, thì tức là bạn đã có mọi thông tin cần thiết tại thời điểm này. Để tìm hiểu cách lấy thêm thông tin về giao dịch mua vô hiệu, hãy xem Voided Purchases API trên Google Play. Đây là một mô hình kéo giúp cung cấp thêm dữ liệu cho các giao dịch mua vô hiệu trong một dấu thời gian nhất định.

Đối với các giao dịch mua nhiều sản phẩm bị vô hiệu một phần, trường refundableQuantity do purchases.products cung cấp sẽ chứa số lượng sản phẩm đã mua còn lại chưa bị vô hiệu.

TestNotification

TestNotification chứa các trường sau:

{
  "version": string
}
Tên thuộc tính Giá trị Mô tả
version string Phiên bản của thông báo này. Ban đầu, đây là phiên bản "1.0". Phiên bản này khác với các trường của phiên bản khác.

Ví dụ

Dưới đây là ví dụ về một thông báo kiểm thử:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}