Unity IAP v5 Custom Store Tutorial: Amazon Appstore Integration

Overview

This article provides everything you need to integrate the Amazon Appstore SDK as a Unity IAP Custom Store for games targeting Amazon Fire tablets. It includes a full step-by-step tutorial PDF, a companion Unity Asset Package, and a video walkthrough.

The approach uses Unity IAP v5's Store abstraction layer, letting you back Unity IAP with the Amazon Appstore SDK while keeping a consistent purchase API and codebase across platforms. All three Amazon IAP product types are covered: consumables, entitlements (non-consumables), and subscriptions.

Important: This is a learning-focused baseline implementation. It is not production-ready out of the box — see What's Next for the gaps you'll want to close before shipping.

Downloads

Prerequisites

Note on the Amazon SDK version: v3.0.2 is used because it is the most recent version that ships with a ready-made Unity plugin. v3.0.8 (August 2025) does not include a Unity plugin and requires a custom Java/Kotlin bridge. The trade-off is that v3.0.2 supports ARMv7 only — including ARM64 in your build will cause a DllNotFoundException at runtime. For a production title targeting modern 64-bit devices, wrap v3.0.8 directly; for learning or a baseline integration, v3.0.2 is the simplest starting point.

What's Included in the Asset Package

Importing IAP5-AmazonCustomStore-Tutorial-1_0_0.unitypackage adds the following to your project:

Assets/
  Experiments/
    Shared/
      Scripts/       ← UnityMainThreadDispatcher, IAPProducts
    UnityCustomStore/
      Docs/          ← TUTORIAL.md + tutorial screenshots
      Scenes/        ← Pre-built Unity scene (UnityCustomAmazon)
      Scripts/       ← Five C# implementation scripts
  Plugins/
    Android/
      AndroidManifest.xml   ← Pre-configured for Amazon IAP
    Amazon/
      AmazonIapV2/          ← Amazon SDK source files
  Resources/
    BillingMode.json
  Settings/
    Build Profiles/
      Amazon™ 32bit – development.asset
  Images/            ← Store UI product icons

The package does not include the Amazon Appstore SDK itself or TextMesh Pro. You must complete Step 2 (SDK import) before the project will compile. TMP will be installed automatically the first time you open the scene.

Architecture Summary

The implementation is structured in four layers plus two shared helpers:

• IAPManager (MonoBehaviour) — bootstraps Unity IAP, registers the custom store, and dispatches purchase results to the game UI.
• AmazonStoreWrapper (IStoreWrapper) — thin wrapper that gives Unity IAP the store name and the Store instance.
• AmazonCustomStore (Store) — implements the Unity IAP Store contract (Connect, FetchProducts, FetchPurchases, Purchase, FinishTransaction) and translates between Unity IAP types and SDK-agnostic DTOs.
• AmazonPurchasingCustom (IPurchaseServiceCustom) — the only class that touches the Amazon SDK directly. Wrapping SDK calls here means future SDK upgrades or editor mocking only require changes in one place.

Tutorial Steps at a Glance

The full tutorial PDF walks through each step in detail, with code, screenshots, and explanatory notes. Here's a summary:

Step 1 — Install Unity IAP Open Window > Package Manager, select Services, search for In-App Purchasing, and install v5.2.1.

Step 2 — Install the Amazon Appstore SDK Plugin Download v3.0.2 from the Amazon Developer Portal and import the .unitypackage via Assets > Import Package > Custom Package.

Step 3 — Import the Tutorial Asset Package Import IAP5-AmazonCustomStore-Tutorial-1_0_0.unitypackage. Accept all assets.

Step 4 — Configure the Project for Amazon Fire Tablets

• Switch to Android build target and create an Amazon – Development build profile.
• In Player Settings (Android): set Target Architecture to ARMv7 only and Application Entry Point to Activity.
• Enable a custom AndroidManifest.xml and replace the generated file with the version included in the package (pre-configured with the Amazon IAP receiver and <queries> block).
• Open the UnityCustomAmazon scene and add it to your build profile scene list.
• Install TextMesh Pro Essentials when prompted on first scene open.

Step 5 — Create In-App Items in the Amazon Developer Console Create three products matching the SKUs used in the code:

Download the IAP JSON file from the console (needed for on-device testing in Step 10).

Step 6 — Add the App Authentication Key Download AppstoreAuthenticationKey.pem from your app's dashboard and place it at Assets/StreamingAssets/AppstoreAuthenticationKey.pem.

Step 7 — The Custom Store Implementation Review the five C# scripts that implement the store. The tutorial PDF covers each class in full with annotated code and explanations of key decisions (thread marshalling, async connection pattern, pagination of purchase updates, fulfillment flow).

Step 8 — Scene Setup The pre-built scene is included in the package. If building from scratch: add an IAPManager GameObject, a Canvas with buy/spend buttons, TMP_Text status labels, and a UnityStoreUI component — then wire everything up in the Inspector.

Step 9 — Build & Deploy Select the Amazon – Development build profile, enable Development Build and Script Debugging, then click Build and Run to side-load the APK via ADB.

Step 10 — On-Device Testing Setup Because side-loaded builds don't talk to the live Appstore, you need to configure sandbox mode:

1. Install Amazon App Tester from the Appstore on your Fire tablet and sign in with your developer account.
2. Enable sandbox mode via ADB: adb shell setprop debug.amazon.sandboxmode debug (resets on reboot — re-run after every restart).
3. Push the SDK tester JSON: adb push amazon.sdktester.json /sdcard/amazon.sdktester.json

Step 11 — Verify It Works On launch the store connects and products are fetched (filter Logcat by [IAP]). Tap a buy button — the Amazon App Tester overlay should appear. Approve the purchase and confirm the UI updates. Previously purchased entitlements and subscriptions are automatically restored on re-launch via FetchPurchases.

Troubleshooting

What's Next?

This tutorial covers a minimal but fully working integration. Before shipping to production, consider the following:

• ARM64 support: Wrap Amazon Appstore SDK v3.0.8 with a thin Java/Kotlin bridge to support 64-bit devices.
• Receipt validation: Validate receipts server-side using the PurchaseReceipt from the OnPurchaseResponse callback with the Amazon Receipt Verification Service before granting items.
• Double-grant hardening: Persist granted ReceiptIds (PlayerPrefs, file, or server) and guard AddCoins against the same receipt arriving twice.
• Entitlement cache: Implement AmazonCustomStore.CheckEntitlement with a cache populated from HandlePurchasesFetched, replacing the current NotImplementedException stub.
• Error handling and retry logic: Add user-facing error messages and automatic retry for transient failures.
• Editor testing: Create a mock implementation of IPurchaseServiceCustom to test purchase flows in the Unity Editor without a physical device.

Related Resources

• Unity IAP Documentation
• Unity IAP Changelog
• Amazon Appstore SDK Plugin for Unity — Documentation
• Amazon Appstore SDK Plugin for Unity — Changelog
• Amazon Developer Console
• Amazon Receipt Verification Service

Have a question or found an issue with the tutorial? Post in the Unity Discussions thread or contact Developer Support.