In-App Purchases Gem

The In-App Purchases Gem provides functionality for in app purchases in an Open 3D Engine (O3DE) project. Platform-specific information is handled by the provided API, allowing you to use a single implementation of the In-App Purchases Gem for both Android and iOS.

Note:
For Android, you must install the Google Play billing library from the Android SDK Manager. You can find this option under the extras section.

Handling Requests for Queries and Purchases

You can access the API through code by connecting to the EBus:

EBUS_EVENT(InAppPurchases::InAppPurchasesRequestBus, Initialize);

To use the API, include the InAppPurchasesBus.h header file.

You can also access the API through Script Canvas.

MethodUsageParameters
InitializeCall this method first for all platforms. This method handles all necessary setup before the API can be used.None
QueryProductInfoUse this method when the product IDs are shipped with the game. This method looks for a product ID file (product_ids.json on Android or product_ids.plist on iOS) and retrieves product details using the IDs that are specified in the file.None
QueryProductInfoByIdsUse this method to retrieve product details if the product IDs are provided at runtime, for example if they are retrieved from a server at runtime.AZStd::vector<AZStd::string>& productIds
QueryProductInfoByIdUse this method to retrieve product details if the product IDs are provided at runtime, for example if they are retrieved from a server at runtime. Use this method to retrieve details for a single product only.AZStd::string& productId
QueryPurchasedProductsUse this method to query the Google Play Store for products that were already purchased by the signed-in user. On iOS, this method reads the receipt that is stored on the device and lists the items purchased by the signed-in user.None
RestorePurchasedProductsUse this method to restore purchases that were made by the user. This applies to purchases made on a different device, where the current device does not have receipts stored locally. This method is supported on iOS only.None
ConsumePurchaseCall this method for all purchases that are consumable, such as virtual currencies, health, and ammo. This method requires the purchase token provided by the Google Play Store when the product was purchased. This method is required and supported on Android only.AZStd::string& purchaseToken
FinishTransactionCall this method at the end of a transaction. This method requires the transaction ID provided by the iOS App Store when the product was purchased. It also accepts a boolean parameter to indicate whether or not to download content that is hosted on Apple servers. If this method is not called, the transaction will be reported each time the game is restarted. This method is required and supported on iOS only.AZStd::string& transactionId | bool downloadHostedContent
PurchaseProductUse this method to request to purchase a product from the Google Play Store or the iOS App Store. This method requires the product ID of the product being purchased.AZStd::string& productId
PurchaseProductWithDeveloperPayloadUse this method to request to purchase a product from the Google Play Store or the iOS App Store. This method requires the product ID of the product being purchased. It accepts an additional parameter for the developer payload, which is used by Android to associate a purchase with a user account. When you request purchased products, you can use the developer payload to determine if the signed-in user made the purchase. On iOS, the user account is used in fraud detection.AZStd::string& productId | AZStd::string& developerPayload
GetCachedProductInfoUse this method to return product details that are stored in a cache each time there is a query for information. The cache only stores product details that were retrieved during the previous call to QueryProductInfo/QueryProductInfoByIds/QueryProductInfoById.None
GetCachedPurchasedProductInfoUse this method to return details for purchased products that are stored in a cache. The cache only stores details for purchased products that were retrieved during the previous call to QueryPurchasedProducts.None
ClearCachedProductDetailsUse this method to clear the product details that were cached by the previous call to query product details.None
ClearCachedPurchasedProductDetailsUse this method to clear the details for purchased products that were cached by the previous call to query details for purchased products.None

Handling Responses to Queries and Purchases

When a user makes a query or a purchase, the API sends the request to Apple or Google servers. Once a response is received, the API broadcasts the response on the InAppPurchasesResponse bus.

To handle responses to queries or purchases, overload the functions provided in the class in the InAppPurchasesResponseBus.h file.

MethodUsageParameters
ProductInfoRetrievedThis method is called when product information is retrieved for all requested products. Product information includes product ID, name, description, price, and more. Depending on the platform, the provided pointers must be cast to the appropriate type (ProductDetailsAndroid or ProductDetailsApple).const AZStd::vector<AZStd::unique_ptr<ProductDetails const> >& productDetails
PurchasedProductsRetrievedThis method is called when details are retrieved for all purchased products. Details for purchased products include product ID, transaction ID, transaction time, and more. Depending on the platform, the provided pointers must be cast to the appropriate type (PurchasedProductDetailsAndroid or PurchasedProductDetailsApple).const AZStd::vector<AZStd::unique_ptr<PurchasedProductDetails const> >& purchasedProductDetails
NewProductPurchasedThis method is called when a new product is successfully purchased.const PurchasedProductDetails* purchasedProductDetails
PurchaseCancelledThis method is called when a purchase is canceled.const PurchasedProductDetails* purchasedProductDetails
PurchaseRefundedThis method is called when a purchase is refunded.const PurchasedProductDetails* purchasedProductDetails
PurchaseFailedThis method is called when a purchase fails.const PurchasedProductDetails* purchasedProductDetails
HostedContentDownloadCompleteThis method is called when content that is hosted on Apple servers is downloaded successfully. The transaction ID and download path are provided.const AZStd::string& transactionId | AZStd::string& downloadedFileLocation
HostedContentDownloadFailedThis method is called when content that is hosted on Apple servers fails to download. The transaction ID and content ID of the failed content download are provided.const AZStd::string& transactionId | const AZStd::string& contentId