[in_app_purchase] Explanation for casting details to implementations

packages/in_app_purchase/in_app_purchase/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.0.5
+
+* Add explanation for casting `ProductDetails` and `PurchaseDetails` to platform specific implementations in the readme.
+
 ## 1.0.4
 
 * Fix `Restoring previous purchases` link in the README.md.

packages/in_app_purchase/in_app_purchase/README.md

@@ -62,6 +62,7 @@ This section has examples of code for the following tasks:
 * [Making a purchase](#making-a-purchase)
 * [Completing a purchase](#completing-a-purchase)
 * [Upgrading or downgrading an existing in-app subscription](#upgrading-or-downgrading-an-existing-in-app-subscription)
+* [Accessing platform specific product or purchase properties](#accessing-platform-specific-product-or-purchase-properties)
 * [Presenting a code redemption sheet (iOS 14)](#presenting-a-code-redemption-sheet-ios-14)
 
 ### Initializing the plugin
@@ -245,6 +246,73 @@ InAppPurchase.instance
     .buyNonConsumable(purchaseParam: purchaseParam);
 ```
 
+### Accessing platform specific product or purchase properties
+
+The function `_inAppPurchase.queryProductDetails(productIds);` provides a `ProductDetailsResponse` with a 
+list of purchasable products of type `List<ProductDetails>`. This `ProductDetails` class is a platform independent class 
+containing properties only available on all endorsed platforms. However, in some cases it is necessary to access platform specific properties. The `ProductDetails` instance is of subtype `GooglePlayProductDetails`
+when the platform is Android and `AppStoreProductDetails` on iOS. Accessing the skuDetails (on Android) or the skProduct (on iOS) provides all the information that is available in the original platform objects.
+
+This is an example on how to get the `introductoryPricePeriod` on Android:
+```dart
+//import for GooglePlayProductDetails
+import 'package:in_app_purchase_android/in_app_purchase_android.dart';
+//import for SkuDetailsWrapper
+import 'package:in_app_purchase_android/billing_client_wrappers.dart';
+
+if (productDetails is GooglePlayProductDetails) {
+  SkuDetailsWrapper skuDetails = (productDetails as GooglePlayProductDetails).skuDetails;
+  print(skuDetails.introductoryPricePeriod);
+}
+```
+
+And this is the way to get the subscriptionGroupIdentifier of a subscription on iOS:
+```dart
+//import for AppStoreProductDetails
+import 'package:in_app_purchase_ios/in_app_purchase_ios.dart';
+//import for SKProductWrapper
+import 'package:in_app_purchase_ios/store_kit_wrappers.dart';
+
+if (productDetails is AppStoreProductDetails) {
+  SKProductWrapper skProduct = (productDetails as AppStoreProductDetails).skProduct;
+  print(skProduct.subscriptionGroupIdentifier);
+}
+```
+
+The `purchaseStream` provides objects of type `PurchaseDetails`. PurchaseDetails' provides all 
+information that is available on all endorsed platforms, such as purchaseID and transactionDate. In addition, it is 
+possible to access the platform specific properties. The `PurchaseDetails` object is of subtype `GooglePlayPurchaseDetails` 
+when the platform is Android and `AppStorePurchaseDetails` on iOS. Accessing the billingClientPurchase, resp. 
+skPaymentTransaction provides all the information that is available in the original platform objects.
+
+This is an example on how to get the `originalJson` on Android:
+```dart
+//import for GooglePlayPurchaseDetails
+import 'package:in_app_purchase_android/in_app_purchase_android.dart';
+//import for PurchaseWrapper
+import 'package:in_app_purchase_android/billing_client_wrappers.dart';
+
+if (purchaseDetails is GooglePlayPurchaseDetails) {
+  PurchaseWrapper billingClientPurchase = (purchaseDetails as GooglePlayPurchaseDetails).billingClientPurchase;
+  print(billingClientPurchase.originalJson);
+}
+```
+
+How to get the `transactionState` of a purchase in iOS:
+```dart
+//import for AppStorePurchaseDetails
+import 'package:in_app_purchase_ios/in_app_purchase_ios.dart';
+//import for SKProductWrapper
+import 'package:in_app_purchase_ios/store_kit_wrappers.dart';
+
+if (purchaseDetails is AppStorePurchaseDetails) {
+  SKPaymentTransactionWrapper skProduct = (purchaseDetails as AppStorePurchaseDetails).skPaymentTransaction;
+  print(skProduct.transactionState);
+}
+```
+
+Please note that it is required to import `in_app_purchase_android` and/or `in_app_purchase_ios`.
+
 ### Presenting a code redemption sheet (iOS 14)
 
 The following code brings up a sheet that enables the user to redeem offer

packages/in_app_purchase/in_app_purchase/pubspec.yaml

@@ -2,7 +2,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.
 repository: https://github.com/flutter/plugins/tree/master/packages/in_app_purchase
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+in_app_purchase%22
-version: 1.0.4
+version: 1.0.5
 
 environment:
   sdk: ">=2.12.0 <3.0.0"