Add API for retrieving information about the subscription lifecycle

[jm1175]

The extension needs to be able to retrieve information for subscriptions such as whether they are paused, expired, account on hold etc.
As mentioned here: https://developer.android.com/google/play/billing/subscriptions#lifecycle

[britzl]

Additional data can be retrieved from a purchase and added to the response returned to Lua here:

https://github.com/defold/extension-iap/blob/master/extension-iap/src/java/com/defold/iap/IapGooglePlay.java#L84-L110

For client side retrieval of subscription info we only get information for the Active, Cancelled and In grace period states and the only thing we can read is the isAutoRenewing value which will be true in the Active and In grace period states. So it's a very "blunt" way of reading subscription state. You really need the server side part as well to be able to get more fine grained control and info about subscriptions.

Please also note that we should try to provide the same info for iOS and Amazon as well to maintain a consistent API. @jm1175 could you please check for Amazon and iOS docs covering the same info about subscriptions?

[britzl]

Additional data can be retrieved from a purchase and added to the response returned to Lua here:

https://github.com/defold/extension-iap/blob/master/extension-iap/src/java/com/defold/iap/IapGooglePlay.java#L84-L110

We want to add auto_renewing or perhaps active_subscription as a value read from the Purchase.isAutoRenewing() value:

https://developer.android.com/reference/com/android/billingclient/api/Purchase#isAutoRenewing()

[britzl]

whether they are paused, expired, account on hold

As you can see from my reply above the only information you can get from the client is if a subscription is cancelled or active, nothing more.

In order to surface this in the extension we need to read the Purchase.isAutoRenewing() value and return this to Lua. We also need to add an iap.TRANS_STATE_CANCELLED state to a purchase to complement the existing states.

[jm1175]

Ah ok I see, just being able to check if a subscription is in the "active" state would be useful. isAutoRenewing() would return false in those other cases like "paused", "expired", "account on hold" right? The only problem is when the subscription is "cancelled" or "paused" the content in the app should still be available until the subscription period is finished.

iOS and Amazon don't seem to have as detailed documentation on the subscriptions like Google but I found these two:

https://developer.apple.com/documentation/storekit/original_api_for_in-app_purchase/subscriptions_and_offers/handling_subscriptions_billing?language=objc

https://developer.amazon.com/docs/in-app-purchasing/iap-faqs.html#subscription-item-questions

This bit in the Amazon docs seems relevant: "For Entitlements and Subscriptions, the purchase receipt is listed in the onPurchaseUpdatesResponse(). If the purchase receipt is canceled or expired, the receipt has a valid cancelDate property." And a bit further down: "Amazon provides a cancelDate when the subscription is no longer active. If the cancelDate is null, the subscription is still active for the customer."

[britzl]

For Google Play:

https://developer.android.com/reference/com/android/billingclient/api/BillingClient#queryPurchaseHistoryAsync(com.android.billingclient.api.QueryPurchaseHistoryParams,%20com.android.billingclient.api.PurchaseHistoryResponseListener)