Amazon FireTV

🚧
Important
Amazon FireTV in-app purchase integration supports only subscription offer type.

Prerequisites

You need to connect the middleware to Amazon, before proceeding with FireTV application.

In order to do so, please continue with the following steps:

Setting up Amazon account and creating an application.
Adding test products - see the tutorial.

📘
Important notes for setting up products compatible with Cleeng:

Item ID (SKU) should be the reference of Cleeng Offer ID example S123123123_US

Remember to add the SKU from Amazon in the offer setup in the dashboard in order to map the external offer properly in the Cleeng system. For more information, see this article.

Use subscription purchasable item for subscriptions for a specific period of time. It means that the application must rely on Cleeng when checking entitlement.

Configure Real-Time-Notifications (see the section on keeping subscribers synchronized below).
In order to validate receipt Cleeng requires Amazon “Shared Secret”. The shared secret can be found on the Shared Key page for your developer account with the Amazon Appstore link.

You need to deliver the shared secret to our Support Team to enable the Amazon FireTV functionality.

General Amazon IAP FAQ.

🚧
Important
Cleeng's sandbox uses Amazon's production Receipt Verification Service (RVS). Amazon Cloud Sandbox (App Tester) is NOT supported. Use Live App Testing (LAT) instead.

Communication with receipt endpoint

For details, see the /amazon/payment endpoint.

🚧
Note
When this endpoint returns HTTP status code 200 (“OK”), it only confirms that the request structure and content is correct and that it has been accepted for asynchronous processing by Cleeng; it does NOT indicate the result of receipt validation. Access to content depends on successful receipt validation, which is performed automatically by Cleeng and may take some time to complete.

Validate Access

Receipt processing is an asynchronous process that may take some time, therefore application needs to poll Cleeng API Get entitlements method until the transaction is completed and access is granted.

Alternatively, client backend (middleware) can receive in-app purchase validation webhook notifications. If you are subscribed to the topics listed below, you will receive information about the result of verification.

Webhooks dedicated for in app purchase validation:

In addition generic subscription lifecycle topics will also be emitted:

For details of possible outcomes of in-app purchase validation and webhooks sent, please refer to In-app Purchase Validation article.

Keep subscribers synchronized

Amazon Real-Time Notifications (RTN) let Cleeng learn about changes to an Amazon Appstore purchase as they happen. For example, when a customer’s subscription renews or is cancelled on Amazon, the Amazon Appstore pushes a notification to a Cleeng endpoint. Cleeng then verifies the receipt with Amazon and updates the matching subscription in your Cleeng account, normally within minutes. Without RTN, Cleeng detects such changes only through its periodic checks against Amazon, which can take much longer.

Real-Time Notifications require no change in your app.

⚠️
Important
Every new purchase must be registered through the /amazon/payment endpoint. Real-Time Notifications only keep an already-registered purchase up to date.

Setting up Real-Time Notifications

In the Amazon Developer Console, add Cleeng's RTN endpoint for your app, as described in Amazon's Use Real-Time Notifications guide. The endpoint contains your Cleeng publisher ID:

Environment	Endpoint
Production	`https://api.cleeng.com/amazon/rtn/{publisherId}`
Sandbox	`https://api.sandbox.cleeng.com/amazon/rtn/{publisherId}`

Please remember to replace {publisherId} with your Cleeng publisher ID, for example https://api.cleeng.com/amazon/rtn/123456789.

Use the sandbox endpoint with your Cleeng sandbox account and the production endpoint with your production account.

Amazon Developer Console - Add an Endpoint

Following the result of each synchronization

Subscribe to the result webhooks (recommended). Use the Webhooks API to subscribe to the inappPurchaseValidationSucceeded and inappPurchaseValidationFailed topics. Cleeng sends one of them after every RTN-triggered synchronization.

Testing Real-Time Notifications

Add the sandbox endpoint, register a test purchase through the /amazon/payment endpoint, and then change that purchase on the Amazon side, for example cancel it. The subscription in your Cleeng sandbox account should reflect the change.

Pro Tip
Enable Accelerated timelines for subscriptions in “Live App Testing” in the Amazon Developer Console during the creation of a “New Test” to shorten renewal intervals in the sandbox. With this setting on, renewals happen in minutes instead of following the real billing period; the shortest is 5 minutes, for weekly subscriptions.

If notifications arrive but nothing changes in Cleeng, the purchase was most likely never registered through the /amazon/payment endpoint.