🚧

Beta

Please note that it is a Beta feature.

🚧

Important

Vizio in-app purchase integration supports only subscription offer type.

Overview

Payments on mobile and TV apps (in-app purchases) enrich your portfolio with one more payment method for your services. Customers can easily buy access to video content directly from inside your native applications, which simplifies the process. It also provides added value to you.

When you enable in-app purchases with Cleeng you gain:

• entitlement across devices for your customers - they can use your services on many devices
• rich and consolidated reporting for you - all-in-one-place reporting that can support your subscriber retention analytics and strategy building.

It is important to note that legally and technically it is Vizio who handles the actual payments for purchases made in apps. Cleeng acts as an observer and tracks in-app purchase lifecycle events to gather data to make it available for analysis and to control access rights (entitlements).

In short, integration of connected TVs in-app purchases requires the setup on your side, and when ready, calling Cleeng purchase validation endpoint to submit the initial purchase when it happens in the app.

Cleeng takes over from there. We validate the purchase, create a subscription and keep it in sync by listening to server-to-server notifications for subscription status updates. And we take care of the reporting.

This tutorial will show what you need to take care of to enable purchases via Vizio with Cleeng, as well as what the user-flow will look like.

What you have to do

1. Architecture Overview

📘

Depending on how you integrate with Cleeng, you will use different authorization: either a publisher (X-Publisher-Token) or JWT (Bearer) token. A publisher token will be used for integrations through middleware, while JWT - for direct integrations.

Please note that some integration steps will differ for these two flows.

Also, the purchase validation endpoint that is used in Vizio purchase integration accepts either a publisher (X-Publisher-Token) or JWT (Bearer) token for authorization. Please make sure to use the one that matches your current integration.

Please also note that this tutorial focuses on integration where JSON Web Token (JWT) authorization is used so we recommend using MediaStore API (for more information see Getting started), especially for authentication (registration and login).

2. Prerequisites

You need to complete 6 steps in the prerequisites stage:

1. Have a working Vizio application
2. Do the required configuration in Vizio
3. Configure products:

• Add products within Vizio
• Map Vizio products to Cleeng offers
• Configure subscription upgrades and downgrades in the Cleeng Dashboard (if you use subscription upgrade/downgrade feature)

4. Configure Server-to-Server notifications
5. Provide configuration and activate integration in the Cleeng Dashboard
6. Contact Cleeng Support Team to add a payment method.

Please follow the sections below for details:

1. Make sure you have a working Vizio application on your side.

2. Conduct Vizio-related configuration.
   Log in to Vizio Developer Portal (please note that you need a US IP address to be able to log in) - either sandbox for testing: https://preprod.developer.vizio.com/ or production https://developer.vizio.com/.
   For details of the setup in Vizio, please refer to Vizio documentation.

3. Configure products:

   • Create products - subscription plans in Vizio.

   • Products that you add must be compatible with your Cleeng offer, so while mapping offers to Cleeng, make sure to also map trial periods (if available).

     Remember to add your Vizio product IDs (plan codes from Vizio) in the offer setup in the Cleeng dashboard in order to map the external offer properly in the Cleeng system. For more information, see this article.

     

   • Configure subscription upgrades and downgrades in the Cleeng Dashboard.

4. Configure Server-to-Server notifications:
   You need to provide a URL address in Vizio Developer Portal for server-to-server notifications - see Vizio documentation.
   The URL you need to provide is:

   • https://inapp.api.sandbox.cleeng.com/vizio/notifications/broadcasters/{broadcasterId} - for sandbox environment
   • https://inapp.api.prod.cleeng.com/vizio/notifications/broadcasters/{broadcasterId} - for production environment
     👉 Please remember to replace {broadcasterId} with your broadcaster ID (publisher ID) in the URL.
     For more information on Server-to-Server notifications, see the section below.

5. Provide configuration information and activate integration in the Cleeng Dashboard:

   Log in to Cleeng Dashboard, go to Admin Settings > Integration Hub > Vizio.

   Once there (see the screenshot below), configure the API Key (API Key is called Key ID in Vizio Developer Portal), Vizio Partner ID and Signing Key in order to activate integration.

   

   You can get the required information from Vizio Developer Portal:

   

   Note: This key is time-limited and expires after a certain time. Vizio provides non-expiring API keys per each environment via email (this is especially important for production environment).

   

   

6. Contact Cleeng Suport Team to add a payment method.

   🚧

   Important

   Adding a payment method and completing configuration in the Cleeng Dashboard are mandatory for the setup to work.

3. Initial Purchase Submission

Integration of Connected TV in-app purchases requires calling Cleeng purchase validation endpoint to submit the initial purchase when it happens in the app.

When a customer successfully buys a subscription offer, a request should be sent to Cleeng purchase validation endpoint:

• POST https://inapp.api.sandbox.cleeng.com/vizio/purchase-validation - in sandbox environment OR
• POST https://inapp.api.prod.cleeng.com/vizio/purchase-validation - once in production environment.

4. Receive Subscriber Status Validation

Once you make a call to Cleeng’s purchase validation endpoint, Cleeng takes over from there.

We validate the purchase in the app, and act on the validation result (e.g. create a subscription).

Subscriber Status Validation

Vizio subscriptionId is the main object used for validating a purchase, i.e. validating a subscriber status, so access to content is based on a Vizio subscriptionId.

Cleeng validates it before access is granted, but it is an asynchronous process. Because it requires validation with an external app store, we are not able to return the outcome synchronously in the API request response. So the first “OK” message that you receive shows only that the request has been successfully queued.

See below for the overview of the process of subscriber status validation for two integration methods:

• direct integration (without middleware)
• integration with middleware (client backend).

Direct Integrations (Without Middleware)

For direct integrations where no middleware is used (the request is submitted directly to Cleeng platform from the client app and authenticated with an end user JWT token), the polling approach should be used.

The application needs to poll Cleeng API using GET /vizio/purchase-status endpoint. The suggested frequency is to poll every 5 seconds for up until 60 seconds.

While temporarily caching the entitlement is not mandatory, it is strongly recommended to enhance the user experience and ensure immediate access to content. Since purchase validation depends on an external API, there may be some delay before the process is completed and the access is granted permanently.

Integration With Middleware (Client Backend)

For backend integrations where middleware is used and the request is authenticated with a publisher token, your client backend service should subscribe to Cleeng webhook topics.

If you are subscribed to the topics listed below, you will receive a webhook notification when in-app purchase validation (subscriber status validation) is completed with information about the outcome of the validation result.

Webhooks dedicated for in-app purchase validation:

• inappPurchaseValidationSucceeded
• inappPurchaseValidationFailed

Please note that in-app specific data for Vizio will be as follows:

“InAppSpecificData”: {
  “invoiceNumber”: string,
  “subscriptionId”: string
}

In addition generic subscription lifecycle topics will also be emitted:

• subscriptionCreated
• subscriptionTerminated

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

5. Keep Subscribers Synchronized

Cleeng acts as an observer and tracks in-app purchase lifecycle events. But for Cleeng to be able to do this, you need to configure server-to-server notifications to get the subscription status updates and keep subscribers synchronized.

You need to provide a URL address in Vizio Developer Portal for server-to-server notifications - as described in the Prerequisites section.

Server-to-Server Notifications

Server-to-Server Notifications is direct one-way communication between Vizio and Cleeng. It provides near real-time subscription updates that help to get information about new purchases, renewals, billing issues, etc. This helps to build more accurate analytics, as well as simplifies managing the subscriber’s status.

The table below presents which Vizio notifications are supported:

User Flow

1. Register/Login User

Note:

We recommend using MediaStore API (for more information see Getting started), especially for authentication (registration and login).

The application attempts to log in the user. If the user doesn't exist, registration is required. It is recommended that the application uses the Register method to register the customer. For more information, see Registration.

If the user exists, it is recommended that the application uses the Login endpoint to log in. For more information see Login.

2. Subscribe to an Offer

Once a customer successfully subscribes to an offer, they get access to the content.

This can be a result of:

• subscription creation - if we do not have a subscription with this Vizio subscriptionId yet
• subscription transfer - if we already have an active subscription for the provided Vizio subscriptionId and it belongs to a customer with a different email address. Then a new subscription is created for the "new customer" (the one using the new e-mail address) and the subscription assigned to the "old customer" (the one using the old email address) is terminated. Please note that this process has implications in reporting (one subscription is terminated and another one created).

3. Manage Subscription

For subscriptions purchased via Vizio, Cleeng does not handle payments. This also means that subscription lifecycle events like termination are managed by external services. Cleeng acts as an observer and tracks in-app purchase lifecycle events to synchronize the status.

So for example, if you are using Cleeng MediaStore SDK Components in your webApp, a subscription purchased via in-apps cannot be managed in MyAccount and your customers will be informed that they need to go to the external store to manage their subscription there.

If you are not using our Components solution, it is recommended that you provide respective information in your specific My Account implementation.

Testing Guidance

Please follow these steps to test the initial payment configuration:

1. Configure purchase in Vizio:
   • Create products
2. Create a Cleeng sandbox account (or log in if you already have one) and create a test offer in the Cleeng Dashboard.
3. Make sure Vizio and Cleeng offers in the sandbox environment are compatible (while creating a new offer in the Cleeng Dashboard, remember to add the App Store Product ID).
4. Provide the API Key, Partner ID and Signing Key in the Cleeng Dashboard.
5. Contact Cleeng Support Team to complete configuration on Cleeng’s side (add a payment method).
6. Register a user in your Vizo application.
7. Make an initial purchase.
8. You should be able to find transaction details in Cleeng Dashboard under the customer’s details page.

Test Cases

You should cover the test scenarios below to test your integration more thoroughly:

• Initial purchase - when a logged-in customer purchases an offer from a list of offers available on the purchase page opened on the Vizio TV application.
• Recurring payment - when a customer’s subscription reaches a renewal date and the payment for it is processed.
• Subscription switch (upgrade/downgrade) - when a customer switches a subscription to another one (upgrades or downgrades a subscription).
• Subscription cancellation - when a customer cancels a subscription (that they have previously purchased via Vizio TV application).
• Subscription reactivation - when a customer reactivates a previously cancelled subscription before it reaches its end date.
• Payment failed - when a customer's subscription reaches a renewal date and the payment for it fails.
• Subscription expiration - when a subscription reaches its end date and the customer has opted out from the service (has canceled the subscription).