Mad Menace Games is the creator of the popular game GraveStompers: Zombie vs Zombie. GraveStompers is a console-style 3^rd person shooter with intuitive touch-screen controls in which zombie eradication has never been more exhilarating. One way Mad Menace monetizes their game is through the Amazon In-App Purchasing API to allow users to purchase Ghostface, the villain from the Scream movies. Since the game is built using the Unity game engine, Mad Menace Games uses the free Amazon In-App Purchasing API plug-in for Unity to support their monetization strategy. According to Michael Stragey, GraveStompers lead developer, the Unity plug-in made it extremely easy to accomplish this and release their game on Amazon. In this post, we look at the following 4 steps used by Mad Menace Games for supporting an entitlement in-app purchase in Unity:

1. Setting up the Amazon In-App Purchasing Unity plug-in and test environment
2. Launching the Amazon purchase flow
3. Handling the result of the Amazon purchase flow
4. Determining if the user previously purchased the entitlement

Step 1: Setting up the Amazon In-App Purchasing Unity plug-in and test environment

To start off, Mad Menace Games had to install and setup the Amazon In-App Purchasing Unity plug-in. To do this for your app, with your Android game open in Unity, you add the Amazon plug-in and support for In-App Purchasing to your environment by completing the following steps:

1. Right click on Project Pane
2. Select “Import Package/Custom Package…”
3. Select the “AmazonIAP.unitypackage” that was downloaded as part of the Amazon Mobile App SDK and click “Open”
4. From the import dialog click “Import” and this package will be added to your project
5. Select the “Amazon” menu
6. Click “Generate AndroidManifest.xml file”
    

There is only one more setup task now that the Unity environment has Amazon In-App Purchasing available and the application specifies this support in its manifest. As a developer, you need to set up your sandboxed test environment for running in-app purchasing transactions. This means you install the AmazonSDKTester.apk from the Amazon Mobile App SDK on your emulator or device and provide a JSON file detailing your IAP items. More details on setting up your test environment can be found here.

Step 2: Launching the Amazon purchase flow

With setup now complete, let’s take a look at the more exciting stuff. After installing the plug-in, Mad Menace Games added the code for supporting the sale of their character “Ghostface”. The first step is to add the code for launching the Amazon purchase flow UI when the user wants to buy the character. This can be easily done with the following code:

AmazonIAP.initiatePurchaseRequest("com.gravestompers.characters.ghostface");

The string “com.gravestompers.characters.ghostface” is the SKU of the Ghostface IAP item specified on the Mobile App Distribution Portal along with being defined in the JSON file for testing. These places are where you also specify things such as the type of in-app item (consumable, entitlement, or subscription), price, title, and description.

Step 3: Handling the result of the Amazon purchase flow

Now with the purchase flow being in place and the user actually able to make a purchase, code is required for handling the result of the purchase flow and providing the user with the actual Ghostface character. The response for this purchase flow will be returned via the AmazonIAPEventListener methods: purchaseFailedEvent and purchaseSuccessfulEvent. Below is an example of what Mad Menace Games’ code may look like for this.

void purchaseFailedEvent( string reason )

{

      // Log the reasons for failure

      Debug.Log( "purchaseFailedEvent: " + reason );

}

void purchaseSuccessfulEvent( AmazonReceipt receipt )

{

      // Store receipt and verify it is legitimate with Amazon Receipt Verification Server

      storeAndVerifyReceipt( receipt );

      if (receipt.sku == "com.gravestompers.characters.ghostface")

            unlockGhostfaceChacter();

}

As a best practice, we recommend validating the receipt you receive from a successful purchase via your server that stores these receipts. More information on validation of receipts can be found here.

Step 4: Determining if the user previously purchased the entitlement

After creating a fully functioning purchase experience, there was one final coding task Mad Menace Games had to complete. Once a user owns this character, they should be able to access the character if they uninstall and reinstall the app, clear their app data, or change from playing the app on their phone to playing it on their Kindle Fire HD. To help make life easier for developers, Amazon keeps track of these entitlement in-app purchases. As a developer, you can receive these purchases via the AmazonIAPEventListener’s purchaseUpdatesRequestSuccessfulEvent method. This method will be called anytime there are new entitlements the running app needs to process. Below is an example code snippet:

void purchaseUpdatesRequestSuccessfulEvent( List<string> revokedSkus, List<AmazonReceipt> receipts )

{

  // Process New Receipts

  foreach ( AmazonReceipt receipt in receipts )

  {

   // Store receipt and verify it is legitimate with Amazon Receipt Verification Server

      storeAndVerifyReceipt( receipt );

      if (receipt.sku == "com.gravestompers.characters.ghostface")

        unlockGhostfaceChacter();

  }

}

That is all it took for Mad Menace Games to add Amazon In-App Purchasing support to their GraveStompers Unity game. You can find more information on Amazon In-App Purchasing and the Unity plug-in here.