Roku

Prerequisites

For Roku in-app purchases to be connected to Cleeng's system, the following steps must be completed:

1. Create a Roku customer account

2. Enroll as a Roku developer

3. Register for Roku Partner Payouts Program

4. Configure in-app products for your Roku channel app

Remember to add your Roku product ID 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.

5. Set your Roku push notification URL to this Cleeng endpoint:

• https://cleeng.com/roku/push-notification/{publisherId} (production environment)
• https://sandbox.cleeng.com/roku/push-notification/{publisherId} (sandbox environment)

Replace {publisherId} with your publisher ID in the URL.

Providing a URL is necessary to receive account activity notifications (e.g. purchases, subscription cancellations, reversals, etc.). To see which notifications are supported, please refer to the Notifications section below.

Important
Please note that you should leave the “Stop sending billing notifications” box unchecked (see the image below). Otherwise, Cleeng will not receive the notifications and ChurnIQ reporting will not work.

6. Contact Cleeng to finalize Roku in-app purchase setup.

📘

Important

You need to deliver an API Key to our Support Team to enable Roku functionality.

To get the Roku API Key, you need to go to Roku Developer Console and navigate to Roku Pay Web Services. The API Key can be found here. You can see the example screen below:

To find out more about the Roku API key, feel free to check out Roku documentation.

Purchase Flow

The Roku channel app is responsible for displaying the “buy" button to initiate the payment. Once successful payment is completed through Roku Billing, the Cleeng receipt endpoint must be notified. For details, see the /roku/payment endpoint.

🚧

Important

Please note that middleware is required in integrations utilizing a publisher token.

This tutorial focuses on the integration when a publisher token is used, so middleware is also included.

If you use the MediaStore SDK /roku/payment endpoint in your integration that utilizes JWT, middleware is not needed.

Validate Access

Payment processing is an asynchronous process. Even that most responses are within 4 seconds, it can take up to 30 seconds.
Our recommendation is that the application polls the Cleeng Core API using the GET /3.1/entitlements method until the transaction is completed and access is granted.

(For direct integrations using JWT, the application should poll MediaStore API endpoint: GET /entitlements/{offreId} ).

The flowchart below shows the process for backend integrations:

Notifications

Push Notifications provide direct communication between Roku and Cleeng with near real-time subscription updates.

To receive notifications you need to provide a URL address as specified in the Prerequisites section.

The table below presents which Roku notifications are supported:

Subscription Upgrades and Downgrades

Upgrades

Subscription upgrades work in the following way:

• A subscription is upgraded immediately.
• The customer gets access to the new plan.
• The customer is charged with the price for a new plan decreased by the remaining value from the previous subscription.
• The billing cycle is changed and starts at the moment of the subscription upgrade.

Downgrades

Downgrades work in the following way:

• A subscription downgrade happens only when the subscription renews.
• The customer is charged full price for the new plan at the start of the next billing cycle.
• The billing cycle remains unchanged.