Implement pending purchases with Amazon IAP

#tutorial #amazon #iap #kotlin

What if I told you that as a developer you can provide parents with the peace of mind to never experience news headlines such as these:

With Appstore SDK’s new pending purchases feature for the In-App Purchasing (IAP) API, you can now provide users with the assurance that unknown purchases won’t occur when children are using your app.Why does it matter? Because offering the best user experience for IAP flows creates several benefits including positive brand reputation, increased ROI, and customer loyalty to start.

So what are pending purchases?

A pending purchase occurs when a user of a child profile in Amazon Kids requests a purchase inside an app or game. After a child requests a purchase, a notification is sent to the parent. The parent can then approve or decline the purchase through the Parent Dashboard. While waiting for approval, the purchase will be in a pending state. If the parent approves the request, your app can deliver the IAP item.

Here’s a screen recording of the pending purchase flow for Amazon Kids:

Integrating pending purchases with the Appstore SDK

Before you can implement pending purchases there are a few things you will need:

An app or game implementing the Amazon IAP API. If you would like to implement the API for the first time, you can watch my YouTube tutorialhere.
An app or game upgraded to the latest version of theAppstore SDK - v3.0.4 (Appstore SDK contains the IAP API)
Fire tablet device for testing (optional)

Now that you are all set, lets look at how you can implementPendingPurchases and the good news is this can be done in 3 steps:

Stage 1: Call`enablePendingPurchases` to support child request

To enable Pending Purchases, your app must call thePurchasingService.enablePendingPurchases()
method at any point before initiating a purchase in theMainActivity of your app.

Kotlin

classMainActivity:AppCompatActivity(){privatelateinitvarbinding:ActivityMainBindingoverridefunonCreate(savedInstanceState:Bundle?){super.onCreate(savedInstanceState)binding=ActivityMainBinding.inflate(layoutInflater)valview=binding.rootsetContentView(view)PurchasingService.registerListener(this,purchasingListener)// The call to enablePendingPurchases is required for your app to receive a PENDING RequestStatusPurchasingService.enablePendingPurchases();....funrequestInAppPurchase(){PurchasingService.purchase(....)}}

Java

publicclassMainActivityextendsActivity{@OverridepublicvoidonCreate(BundlesavedInstanceState){super.onCreate(savedInstanceState);PurchasingService.registerListener(...);// The call to enablePendingPurchases is required for your app to receive a PENDING RequestStatusPurchasingService.enablePendingPurchases();}...voidrequestInAppPurchase(){PurchasingService.purchase(...)}}

Stage 2: Parent approval & handle`RequestStatus` of`PENDING`

When a child initiates a request for a purchase, the resultingPurchaseResponse object has aRequestStatus ofPENDING. Therefore, in your app or game ensure you are monitoring the purchase request status. You must either use Real-Time Notifications (RTN) or regularly callgetPurchaseUpdates() to be notified of the purchase status and fulfil the purchase.

Kotlin

privatevarpurchasingListener:PurchasingListener=object:PurchasingListener{overridefunonUserDataResponse(response:UserDataResponse){if(response.getRequestStatus()==PurchaseResponse.RequestStatus.PENDING){// You can break here and do nothing, or show a modal indicating a request is pending.// The Appstore also shows a modal to the user indicating the request is pending before// returning the response to your app.}}// ...}

Java

classMyListenerimplementsPurchasingListener{publicvoidonPurchaseResponse(finalPurchaseResponseresponse){if(response.getRequestStatus()==PurchaseResponse.RequestStatus.PENDING){// You can break here and do nothing, or show a modal indicating a request is pending.// The Appstore also shows a modal to the user indicating the request is pending before// returning the response to your app.}}// ...}

Stage 3: Child approval notification and handling

Once a parent has reviewed the request, the purchase is either:

approved, theRequestStatus is updated toSUCCESSFUL and your app follows its regular logic for successful transactions. On Fire devices, users get a notification from the system when a purchase is approved.
not approved, such as if the parent declines the purchase or lets the purchase request expire, your app doesn't need to take any further action. When not approved, there will be no notification from RTN and no new transaction when a call togetPurchaseUpdates() is made.

Next steps

Once you have implemented Pending Purchases, you can test out your implementation with the Amazon App Tester. Within the tester you will be able to see the status of the purchases and manipulate them to test out the different scenarios of your users journey.

Here’s a screen recording of the Amazon App Tester in action:

Summary

We hope this feature enables new purchase flows to improve the user experience and review stages for parents and children. Try this feature out and let us know what you think!