Roku
Prerequisites
For Roku in-app purchases to be connected to Cleeng's system, the following steps must be completed:
-
Create a Roku customer account
-
Enroll as a Roku developer
-
Register for Roku Partner Payouts Program
-
Configure in-app products for your Roku channel app
Note: Each Roku Product ID should match its Cleeng Offer ID
Exception:
Please note that underscore(_) is not supported in Roku, so you have to replace it by dash (-)
Example,
Cleeng Offer ID Roku Product ID S123123123_US S123123123-US
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.
- 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.
- Contact Cleeng to finalize Roku in-app purchase setup.
Important
You need to deliver an API Key to our Broadcaster Success Specialists 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 API using the getAccessStatus()
or getAccessibleTags()
method until the transaction is completed and access is granted.
The below flowchart shows the process:
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:
Roku Notification | Supported at Cleeng |
---|---|
Cancellation | ✓ |
Refund | ✓ |
Sale - Notifications used for a renewal process | ✓ |
UpgradeSale - Notifications used for subscription upgrade | ✓ |
DowngradeSale - Notifications used for subscription downgrade | ✓ |
OnHoldInitiated | ✓ |
OnHoldRecovered - in pair with Sale | ✓ |
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.
Updated 8 days ago