Update android_in_app_purchases.rst (#5104)

* Update Android In-App Purchase

Co-authored-by: Timo Schwarzer <[email protected]>
Co-authored-by: Max Hilbrunner <[email protected]>

tutorials/platform/android_in_app_purchases.rst

@@ -103,6 +103,18 @@ initiate the purchase flow for it.
 
     payment.purchase("my_iap_item")
 
+Then, wait for the ``_on_purchases_updated`` callback and handle the purchase result:
+
+::
+
+    func _on_purchases_updated(purchases):
+        for purchase in purchases:
+            if purchase.purchase_state == 1: # 1 means "purchased", see https://developer.android.com/reference/com/android/billingclient/api/Purchase.PurchaseState#constants_1
+                # enable_premium(purchase.sku) # unlock paid content, add coins, save token on server, etc. (you have to implement enable_premium yourself)
+                if not purchase.is_acknowledged:                                        
+                    payment.acknowledgePurchase(purchase.purchase_token) # call if non-consumable product
+                    if purchase.sku in list_of_consumable_products:
+                        payment.consumePurchase(purchase.purchase_token) # call if consumable product
 
 
 Check if the user purchased an item
@@ -110,7 +122,7 @@ Check if the user purchased an item
 
 To get all purchases, call ``queryPurchases``. Unlike most of the other functions, ``queryPurchases`` is
 a synchronous operation and returns a :ref:`Dictionary <class_Dictionary>` with a status code
-and either an array of purchases or an error message.
+and either an array of purchases or an error message. Only active subscriptions and non-consumed one-time purchases are returned.
 
 Full example:
 
@@ -119,10 +131,11 @@ Full example:
     var query = payment.queryPurchases("inapp") # Or "subs" for subscriptions
     if query.status == OK:
         for purchase in query.purchases:
-            if purchase.sku == "my_iap_item":
-                premium = true # Entitle the user to the content they bought
+            if purchase.sku == "my_iap_item" and purchase.purchase_state == 1:
+                # enable_premium(purchase.sku) # unlock paid content, save token on server, etc.
                 if !purchase.is_acknowledged:
                     payment.acknowledgePurchase(purchase.purchase_token)
+                    # Or wait for the _on_purchase_acknowledged callback before giving the user what they bought
 
 
 Consumables
@@ -132,17 +145,17 @@ If your in-app item is not a one-time purchase but a consumable item (e.g. coins
 multiple times, you can consume an item by calling ``consumePurchase`` with a purchase token.
 Call ``queryPurchases`` to get the purchase token. Calling ``consumePurchase`` automatically
 acknowledges a purchase.
+Consuming a product allows the user to purchase it again, and removes it from appearing in subsequent ``queryPurchases`` calls.
 
 ::
 
     var query = payment.queryPurchases("inapp") # Or "subs" for subscriptions
     if query.status == OK:
         for purchase in query.purchases:
-            if purchase.sku == "my_consumable_iap_item":
-                if !purchase.is_acknowledged:
-                    payment.consumePurchase(purchase.purchase_token)
-                    # Check the _on_purchase_consumed callback and give the user what they bought
-
+            if purchase.sku == "my_consumable_iap_item" and purchase.purchase_state == 1:
+                # enable_premium(purchase.sku) # add coins, save token on server, etc.
+                payment.consumePurchase(purchase.purchase_token)
+                # Or wait for the _on_purchase_consumed callback before giving the user what they bought
 
 Subscriptions
 *************