From b5e00e5c3db7fc7121aeff6dc7d20b21740d47e5 Mon Sep 17 00:00:00 2001 From: Andrew Solovay Date: Mon, 26 Jan 2015 19:35:37 -0800 Subject: docs: Documented new IABv5 sub upgrade/downgrade and manual renewal Documented new support for users upgrading/downgrading subscriptions in the middle of a sub period, and for users manually renewing before the subscription period ends. Also updated testing docs to reflect that sandbox now supports testing subscriptions, and documented new "autoRenewing" field in INAPP_PURCHASE_DATA. See first comment for doc stage location. bug: 18982828 bug: 18916814 bug: 18951608 bug: 18908756 Change-Id: I530b57d840ed5aeefe4c6a688a2e59aec41ec7d0 --- docs/html/google/play/billing/billing_reference.jd | 113 ++++++++++++++++++--- .../google/play/billing/billing_subscriptions.jd | 74 +++++++++++++- docs/html/google/play/billing/billing_testing.jd | 50 +++++---- docs/html/google/play/billing/index.jd | 11 +- docs/html/google/play/billing/versions.jd | 22 +++- 5 files changed, 222 insertions(+), 48 deletions(-) diff --git a/docs/html/google/play/billing/billing_reference.jd b/docs/html/google/play/billing/billing_reference.jd index da9178d27a00..01e680fd54b6 100644 --- a/docs/html/google/play/billing/billing_reference.jd +++ b/docs/html/google/play/billing/billing_reference.jd @@ -12,6 +12,7 @@ parent.link=index.html
  1. getSkuDetails()
  2. getBuyIntent()
    3. +
  3. getBuyIntentToReplaceSkus()
  4. getPurchases()
@@ -107,8 +108,8 @@ parent.link=index.html {@code type} - Value must be “inapp” for an in-app product or "subs" for -subscriptions. + Value must be “inapp” for an in-app product or + "subs" for subscriptions. {@code price} @@ -140,7 +141,17 @@ does not include tax.

The getBuyIntent() method

-

This method returns a response code integer mapped to the {@code RESPONSE_CODE} key, and a {@code PendingIntent} to launch the puchase flow for the in-app item mapped to the {@code BUY_INTENT} key. When it receives the {@code PendingIntent}, Google Play sends a response {@code Intent} with the data for that purchase order. The data that is returned in the response {@code Intent} is summarized in table 3.

+

+ This method returns a response code integer mapped to the {@code + RESPONSE_CODE} key, and a {@link android.app.PendingIntent} to launch the + purchase flow for the in-app item mapped to the {@code BUY_INTENT} key, as + described in Purchasing an + Item. When it receives the {@link android.app.PendingIntent}, Google Play + sends a response {@code Intent} with the data for that purchase order. The + data that is returned in the response {@code Intent} is summarized in table + 3. +

Table 3. Response data from an In-app Billing Version 3 purchase request.

@@ -151,7 +162,7 @@ does not include tax. {@code RESPONSE_CODE} - 0 if the purchase was success, error otherwise. + Value is 0 if the purchase was success, error otherwise. {@code INAPP_PURCHASE_DATA} @@ -175,10 +186,23 @@ RSASSA-PKCS1-v1_5 scheme. Field Description + + + {@code autoRenewing} + Indicates whether the subscription renews automatically. If + true, the subscription is active, and will + automatically renew on the next billing date. If false, + indicates that the user has canceled the subscription. The user has + access to subscription content until the next billing date and will + lose access at that time unless they re-enable automatic renewal + (or manually renew, as described in + Manual + Renewal). {@code orderId} - A unique order identifier for the transaction. This corresponds to the Google Wallet Order ID. + A unique order identifier for the transaction. This identifier + corresponds to the Google Wallet Order ID. {@code packageName} @@ -194,7 +218,8 @@ RSASSA-PKCS1-v1_5 scheme. {@code purchaseState} - The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), or 2 (refunded). + The purchase state of the order. Possible values are 0 + (purchased), 1 (canceled), or 2 (refunded). {@code developerPayload} @@ -202,20 +227,80 @@ RSASSA-PKCS1-v1_5 scheme. {@code purchaseToken} - A token that uniquely identifies a purchase for a given item and user - pair. This token may be up to 1,000 characters long. - Pass this entire token to other methods, such as when you consume the - purchase (as described in -Consume - a Purchase). Do not abbreviate or truncate this token. + A token that uniquely identifies a purchase for a given item and user pair.

+

The getBuyIntentToReplaceSkus() + method

+ +

This method is used to upgrade or downgrade a subscription purchase. The method +is similar to getBuyIntent(), except +that it takes a list of already-purchased SKUs that are to be +replaced with the SKU being purchased. When the user completes the purchase, +Google Play cancels the old SKUs and credits the user with the unused value of +their subscription time on a pro-rated basis. Google Play applies this credit +to the new subscription, and does not begin billing the user for the new +subscription until after the credit is used up.

+ +

This method was added with version 5 of the in-app billing API. To verify +that the method is reported, send an isBillingSupported AIDL +request.

+ +

Note: You can only use this method for +subscription purchases. If the passed type parameter is anything +other than "subs", the method returns +BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. +Furthermore, the passed SKUs may not include SKUs for seasonal +subscriptions.

+ +

+ This method returns a response code integer mapped to the {@code + RESPONSE_CODE} key, and a {@link android.app.PendingIntent} to launch the + purchase flow for the in-app subscription mapped to the {@code BUY_INTENT} + key, as described in Purchasing an + Item. When it receives the {@link android.app.PendingIntent}, Google Play + sends a response {@code Intent} with the data for that purchase order. The + data that is returned in the response {@code Intent} is summarized in table + 5. +

+ +

+Table 5. Response data from an In-app Billing Version 5 purchase request.

+ + + + + + + + + + + + + + + + + +
KeyDescription
{@code RESPONSE_CODE}Value is 0 if the purchase succeeds. If the purchase fails, contains an error + code.
{@code INAPP_PURCHASE_DATA} + A String in JSON format that contains details about the purchase order. + See table 4 for a description of the JSON fields. +
{@code INAPP_DATA_SIGNATURE}String containing the signature of the purchase data that the developer + signed with their private key. The data signature uses the + RSASSA-PKCS1-v1_5 scheme.
+

+ +

+

The getPurchases() method

This method returns the current un-consumed products owned by the user. Table 5 lists the response data that is returned in the {@code Bundle}.

-Table 5. Response data from a {@code getPurchases} request.

+Table 6. Response data from a {@code getPurchases} request.

@@ -223,7 +308,7 @@ RSASSA-PKCS1-v1_5 scheme. - + diff --git a/docs/html/google/play/billing/billing_subscriptions.jd b/docs/html/google/play/billing/billing_subscriptions.jd index b9b77df493dd..8f55354e5b6d 100644 --- a/docs/html/google/play/billing/billing_subscriptions.jd +++ b/docs/html/google/play/billing/billing_subscriptions.jd @@ -1,4 +1,4 @@ -page.title=In-App Subscriptions +page.title=In-app Subscriptions parent.title=In-app Billing parent.link=index.html page.metaDescription=Subscriptions let you sell content or features in your app with automated, recurring billing. @@ -21,6 +21,11 @@ meta.tags="monetization, inappbilling, subscriptions" Developer API.
  • Users purchase your subscriptions from inside your apps, rather than directly from Google Play.
    • +
  • Users can renew their subscriptions while a current subscription is + active.
    • +
  • Users can upgrade or downgrade a subscription in the middle of a + subscription period. The old subscription's cost is pro-rated, and the + unused portion is applied to the replacement subscription.
  • You can defer billing for a particular user's subscription, to manage accounts or offer rewards.
    • @@ -206,6 +211,65 @@ app to notify your backend servers of subscription purchases, tokens, and any billing errors that may occur. Your backend servers can use the server-side API to query and update your records and follow up with customers directly, if needed.

    +

    Manual Renewal

    + +

    With version 5 of the In-app Billing API, users can renew a subscription +during its active period even if the subscription is not set to +automatically renew. If the user purchases a subscription while the subscription +is active, it is extended by the appropriate period at the current rate.

    + +

    For example, Achilles has a subscription to the Modern Hoplite app. +His subscription is currently due to expire on August 1. On July 10, he +purchases a 3-month subscription at the current rate. Those three months are +added to his existing subscription, so the subscription now expires on November +1.

    + +

    It is up to the app to convey this with an appropriate UI. For example, if a +user does not have an active subscription, the app might have a +buy button, but if the user has a subscription the button might +say renew.

    + +

    Subscription Upgrade/Downgrade

    + +

    + With version 5 of the In-app Billing API, users can upgrade or downgrade a + subscription during its active period. When the user does this, the active + subscription is canceled and a new subscription is created. The unused + balance of the old subscription is applied on a pro-rated basis to the new + subscription. The first billing period for the new subscription begins after + that balance is used up. (The new subscription does not need to have a period + of the same length as the old one.) +

    + +

    For example, Samwise has a subscription to online content from the +Country Gardener app. He currently has a monthly subscription to the +Tier 1 +version of the content (which has text-only content). This subscription costs +him £2/month, and renews on the first of the month. On April +15, he chooses to upgrade to the Tier 2 subscription (which includes video +updates), costing £3/month. His Tier 1 subscription is immediately ended. +Since he paid for a full month (April 1-30), but only used half of it, half of a +month's subscription (£1) is applied to his new subscription. However, since +that new subscription costs £3/month, the £1 credit balance only pays for ten +days. So Samwise's credit pays for his subscription from April 15-25. On April +26, he is charged £3 for his new subscription, and another £3 on the 26th of +each month following.

    + +

    + Note: The new subscription's billing date depends on when + the subscriber's pro-rated credit runs out, so the subscriber cannot upgrade + or downgrade to a seasonal subscription, which has fixed and predetermined + beginning and end dates. +

    + +

    When a user upgrades or downgrades a subscription, your app calls + +getBuyIntentToReplaceSkus(). +This method is passed the new SKU the user wants to buy, and all +the old SKUs that are superseded by it. The remaining portions of the old SKUs +are used to pay for the new subscription, and billing begins when this credit +is used up.

    +

    Deferred Billing

    Using the @@ -316,7 +380,7 @@ canceling subscriptions from inside the purchasing app.

    When the user cancels a subscription, Google Play does not offer a refund for the current billing cycle. Instead, it allows the user to have access to the -cancelled subscription until the end of the current billing cycle, at which time +canceled subscription until the end of the current billing cycle, at which time it terminates the subscription. For example, if a user purchases a monthly subscription and cancels it on the 15th day of the cycle, Google Play will consider the subscription valid until the end of the 30th day (or other day, @@ -357,12 +421,12 @@ Orders page in the Play Store, or by contacting you directly.

    If you receive requests for refunds, you can use the Google Play Developer API or the Merchant Center to cancel the subscription, verify that it -is already cancelled, or refund the user's payment without cancelling it. You +is already canceled, or refund the user's payment without canceling it. You can also use the Google Play Developer API to refund and revoke a user's subscription. If you refund and revoke a subscription, the user's -subscription is immediately cancelled, and the user's most recent subscription +subscription is immediately canceled, and the user's most recent subscription payment is refunded. (If you want to refund more than the most recent payment, you can process additional refunds through the Merchant Center.)

    @@ -423,7 +487,7 @@ approach to purchase verification accounts for the offline use-case.

  • Remotely query the validity of a specific subscription at any time
  • Cancel a subscription
  • Defer a subscription's next billing date
    • -
  • Refund a subscription payment without cancelling the subscription
    • +
  • Refund a subscription payment without canceling the subscription
  • Refund and revoke a subscription
    • diff --git a/docs/html/google/play/billing/billing_testing.jd b/docs/html/google/play/billing/billing_testing.jd index 36456ccc1900..44b32863f2a8 100644 --- a/docs/html/google/play/billing/billing_testing.jd +++ b/docs/html/google/play/billing/billing_testing.jd @@ -25,8 +25,8 @@ page.tags="inapp, billing, iap" implementation:

    @@ -43,14 +43,13 @@ Devices.

    When your In-app Billing implementation is ready, you can test purchasing of your in-app SKUs in two ways:

    -
    Key
    {@code RESPONSE_CODE}0 if the request was successful, error otherwise.Value is 0 if the request was successful, error otherwise.
    {@code INAPP_PURCHASE_ITEM_LIST}