[in_app_purchase] update docs to warn about completePurchase (flutter#2739)

Author: Chris Yang

packages/in_app_purchase/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.3+1
+
+* Update documentations for `InAppPurchase.completePurchase` and update README.
+
 ## 0.3.3
 
 * Introduce `SKPaymentQueueWrapper.transactions`.

packages/in_app_purchase/README.md

@@ -120,6 +120,24 @@ once they're marked as consumed and fails to return them here. For restoring
 these across devices you'll need to persist them on your own server and query
 that as well.
 
+### Listening to purchase updates
+
+You should always start listening to purchase update as early as possible to be able
+to catch all purchase updates, including the ones from the previous app session.
+To listen to the update:
+
+```dart
+  Stream purchaseUpdated =
+      InAppPurchaseConnection.instance.purchaseUpdatedStream;
+  _subscription = purchaseUpdated.listen((purchaseDetailsList) {
+    _listenToPurchaseUpdated(purchaseDetailsList);
+  }, onDone: () {
+    _subscription.cancel();
+  }, onError: (error) {
+    // handle error here.
+  });
+```
+
 ### Making a purchase
 
 Both storefronts handle consumable and non-consumable products differently. If
@@ -134,11 +152,19 @@ if (_isConsumable(productDetails)) {
 } else {
     InAppPurchaseConnection.instance.buyNonConsumable(purchaseParam: purchaseParam);
 }
-
 // From here the purchase flow will be handled by the underlying storefront.
 // Updates will be delivered to the `InAppPurchaseConnection.instance.purchaseUpdatedStream`.
 ```
 
+### Complete a purchase
+
+The `InAppPurchaseConnection.purchaseUpdatedStream` will send purchase updates after
+you initiate the purchase flow using `InAppPurchaseConnection.buyConsumable` or `InAppPurchaseConnection.buyNonConsumable`.
+After delivering the content to the user, you need to call `InAppPurchaseConnection.completePurchase` to tell the `GooglePlay`
+and `AppStore` that the purchase has been finished.
+
+WARNING! Failure to call `InAppPurchaseConnection.completePurchase` and get a successful response within 3 days of the purchase will result a refund.
+
 ## Development
 
 This plugin uses

packages/in_app_purchase/lib/src/in_app_purchase/in_app_purchase_connection.dart

@@ -109,8 +109,7 @@ abstract class InAppPurchaseConnection {
   /// [PurchaseDetails.status] and update your UI accordingly. When the
   /// [PurchaseDetails.status] is [PurchaseStatus.purchased] or
   /// [PurchaseStatus.error], you should deliver the content or handle the
-  /// error. On iOS, you also need to call [completePurchase] to finish the
-  /// purchasing process.
+  /// error, then call [completePurchase] to finish the purchasing process.
   ///
   /// This method does return whether or not the purchase request was initially
   /// sent successfully.

packages/in_app_purchase/pubspec.yaml

@@ -1,7 +1,7 @@
 name: in_app_purchase
 description: A Flutter plugin for in-app purchases. Exposes APIs for making in-app purchases through the App Store and Google Play.
 homepage: https://github.com/flutter/plugins/tree/master/packages/in_app_purchase
-version: 0.3.3
+version: 0.3.3+1
 
 dependencies:
   async: ^2.0.8