Home > Services & APIs > Earn > In-App Purchasing

Integrating Entitlements in Unity (IAP v1.0)

IAP v1.0 Deprecation Notice

In July 2014, Amazon released the In-App Purchasing (IAP) v2.0 API, which includes several important updates. As of April 30, 2016, Amazon will deprecate IAP v1.0 for new and updated app submissions. While this deprecation will not affect apps that are currently live in the Amazon Appstore, any apps submitted as either a new or updated app after May 11, 2016 will need to use IAP v2.0.

Overview of Entitlements

In-App Purchasing v2 Unity Plugin Now Available

A Unity plugin that supports IAP v2 has been released. Please visit the Unity plugins page for more information.

Entitled content includes any type of content that you sell within your app that requires an entitlement (access rights). This type of content is available anywhere the customer is logged into the Amazon Client. The entitled content does not expire. If Amazon needs to rescind the entitled content, your app will be notified via an observable event.

Customers can purchase entitled content one time. Once purchased, the entitled content is granted to the customer's Amazon account. That entitled content is used to access the content from any eligible device the customer has linked to their account.

More detail is available on the IAP developer site: Integrating Entitled Content

Step 1: Entitle Content

When your game starts, you need to make sure the user is entitled to content they have already purchased. This is done by processing the Receipts passed back in the AmazonIAPEventListener.PurchaseUpdatesRequestSuccessfulEvent().

The plugin handles calls to the Amazon IAP API method PurchaseManager.initiatePurchaseUpdatesRequest(), and manages the offset value associated with the return values. The plugin will make subsequent calls using the most recently returned offset. This means that the plugin's AmazonIAPEventListener.PurchaseUpdatesRequestSuccessfulEvent() provides information as it becomes available, and does not return all entitlement information every time it is called. For this reason the app should store entitlement information in local storage, and add to that information as it becomes available.

On startup, the Unity plugin will handle the registerObserver() API call. This will wire up the plugin's AmazonIAPEventListener, which serves a role analagous to the Amazon IAP PurchaseObserver. The results of the call are available in the AmazonIAPEventListener.onSdkAvailableEvent().

The plugin then calls initiatePurchaseUpdates() and makes the results available in the AmazonIAPEventListener.purchaseUpdatesResponseSuccessfulEvent() and the AmazonIAPEventListener.purchaseUpdatesResultFailedEvent().

You should implement these methods to properly entitle purchased content

void onSdkAvailableEvent( bool isTestMode )
{
Debug.Log( "onSdkAvailableEvent. isTestMode: " + isTestMode );
}

void purchaseUpdatesRequestFailedEvent()
{
Debug.Log( "purchaseUpdatesRequestFailedEvent" );
}

void purchaseUpdatesRequestSuccessfulEvent( List<string> revokedSkus, List<AmazonReceipt> receipts )
{
Debug.Log( "purchaseUpdatesRequestSuccessfulEvent. revoked skus: " + revokedSkus.Count );

// Process Receipts
foreach( var receipt in receipts )
{
// Look for Entitlement Receipts and entitle content as necessary
// Do not entitle any SKUs present in the list of revoked SKUs
Debug.Log( receipt );
}
}

Step 2: Check Items

Making a Purchase is a two-step process. First, you query the IAP catalog to make sure the SKUs you wish to purchase are available. This is done by invoking the AmazonIAP.initiateItemDataRequest() method. The plugin's AmazonIAP object is analagous to the Amazon IAP PurchasingManger class.

if( GUI.Button( new Rect( xPos, yPos, width, height ), "Initiate Item Data Request" ) )
{
AmazonIAP.initiateItemDataRequest( new string[] { "com.amazon.buttonclicker.blue_button" } );
}

You need to check the status of the response in the associated AmazonIAPEventListener methods:

void itemDataRequestFailedEvent()
{
// If you get this response, either retry or stop purchase attempt.
Debug.Log( "itemDataRequestFailedEvent" );
}

void itemDataRequestFinishedEvent( List<string> unavailableSkus, List<AmazonItem> availableItems )
{
// Do not continue with the purchase attempt if the your SKU is in the list of unavailable SKUs!
Debug.Log( "itemDataRequestFinishedEvent. unavailable skus: " + unavailableSkus.Count + ", avaiable items: " + availableItems.Count );
}						

Step 3: Purchase Entitlement

Now that you've validated the SKU, you are ready to invoke AmazonIAP.initiatePurchaseRequest(). Note: although you can call this method without checking the item data (above), you will generate an error dialog for your user if you attempt to purchase an item using an invalid SKU.

AmazonIAP.initiatePurchaseRequest( "com.amazon.buttonclicker.blue_button" );

The response (with the purchase Receipt) will be returned via AmazonIAPEventListener methods:

void purchaseFailedEvent( string reason )
{
// The reasons for failure are:
// INVALID_SKU
// ALREADY_ENTITLED
// FAILED
// You should log the reason, but in every case, do not entitle content
Debug.Log( "purchaseFailedEvent: " + reason );
}


void purchaseSuccessfulEvent( AmazonReceipt receipt )
{
// On successful purchase, you may entitle content
Debug.Log( "purchaseSuccessfulEvent: " + receipt );

// You should preserve the token for use with
// Receipt Verification
String purchaseToken = receipt.token;
}

You should retain the purchaseToken from the Receipt for use with the Amazon IAP Receipt Verification System (RVS).