Android新Billing Library：queryPurchaseHistoryAsync返回内容及参考咨询

Hey there! Let me break down everything you need to know about queryPurchaseHistoryAsync and the Purchase object's JSON structure in the Android Billing Library.

This method fetches the most recent purchase record for each product ID your app has ever handled—this includes both one-time products and subscriptions. Important note: it doesn't return all historical purchases, just the latest entry per product, even if that purchase is expired, canceled, or refunded.

In your callback, you'll get two parameters:

1. A BillingResult object to check if the request succeeded
2. A List<Purchase> containing the latest purchase entry for each relevant product

The Purchase object has a getOriginalJson() method that returns the raw JSON string from Google Play. This is the source of truth for the purchase data. Below are typical examples for both one-time products and subscriptions:

One-Time Product JSON Example #

{
  "orderId": "GPA.1234-5678-9012-34567",
  "packageName": "com.your.app.package",
  "productId": "premium_lifetime_access",
  "purchaseTime": 1699999999000,
  "purchaseState": 0,
  "purchaseToken": "abcdefghijklmnopqrstuvwxyz1234567890",
  "quantity": 1,
  "developerPayload": "user_123_custom_data",
  "acknowledged": true
}

Subscription JSON Example #

Subscriptions include additional fields related to renewal and timing:

{
  "orderId": "GPA.1234-5678-9012-34567",
  "packageName": "com.your.app.package",
  "productId": "monthly_pro_subscription",
  "purchaseTime": 1699999999000,
  "purchaseState": 0,
  "purchaseToken": "abcdefghijklmnopqrstuvwxyz1234567890",
  "quantity": 1,
  "developerPayload": "user_123_custom_data",
  "acknowledged": true,
  "autoRenewing": true,
  "priceCurrencyCode": "USD",
  "priceAmountMicros": 9990000,
  "startTimeMillis": 1699999999000,
  "expiryTimeMillis": 1702678399000,
  "cancelReason": 0,
  "userCancellationTimeMillis": 0
}

Key Field Explanations #

Let's clarify the most important fields:

• orderId: Unique ID generated by Google Play for the transaction
• productId: The ID you defined for the product in the Google Play Console
• purchaseState: Numeric code for purchase status:
  • 0: Purchased successfully
  • 1: Canceled (either by user or refunded)
  • 2: Pending (waiting for payment confirmation)
• purchaseToken: Unique token tied to this purchase—use this for verification, canceling subscriptions, or fetching details later
• acknowledged: Boolean indicating if your app has confirmed the purchase (critical for one-time products; unacknowledged purchases will be refunded after a few days)
• Subscription-specific fields:
  • autoRenewing: Whether the subscription is set to renew automatically
  • priceAmountMicros: Price in micro-units (e.g., 9990000 = $9.99)
  • expiryTimeMillis: Timestamp when the subscription will expire (or expired)
  • cancelReason: Why the subscription was canceled:
    • 0: User canceled
    • 1: Developer canceled
    • 2: System canceled (e.g., payment failure)

• Don't confuse queryPurchaseHistoryAsync with queryPurchasesAsync: The latter returns active, valid purchases (not expired/canceled ones), while the former gives the latest record per product regardless of status.
• For security, always verify the purchase data using the getOriginalJson() string and the getSignature() method with your Google Play public key—this ensures the data hasn't been tampered with.
• When testing, use Google Play's test accounts or static test product IDs like android.test.purchased to simulate purchases without real money.

内容的提问来源于stack exchange，提问作者1tSurge