🚧

Beta

Please note that it is a Beta feature.

This tutorial will help you integrate purchases made via Samsung TV.

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 Samsung 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 proactive reconciliation. And we take care of the reporting.

This tutorial will show what you need to take care of as a broadcaster to enable purchases via Samsung TV 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 SamsungTV 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

As a broadcaster, you should first conduct Samsung-related configuration.

For details of the setup in Samsung, please refer to the following Samsung documentation:

• Samsung Apps TV Seller Office
• Samsung Developer Documentation

The required steps include:

1. Create a Samsung test application on your side.

2. Create products.
   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 Samsung product IDs (itemIDs from Samsung) 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.

3. Log in to Cleeng Dashboard, go to Admin Settings > Integrations > Samsung TV. Once there (see the screenshot below), configure the Security Key and App ID so that data can be synchronized.

   

4. Contact Cleeng Broadcaster Success Specialists 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/samsung-tv/purchase-validation (or POST https://inapp.api.prod.cleeng.com/samsung-tv/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

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

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.

Even though most responses are within 3 seconds, they can take up to 60 seconds on the app store side. Therefore, the application needs to poll the Cleeng API using the Get entitlements endpoint: GET mediastoreapi.cleeng.com/entitlements/{offreId} every five seconds until validation is completed and access is granted.

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

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.

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 invoiceId yet
• subscription transfer - if we already have an active subscription for the provided invoiceId 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 Samsung checkout, Cleeng does not handle payments. This also means that subscription lifecycle events like termination, or subscription upgrade/downgrade 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

Please follow these steps to test the initial payment configuration:

1. Configure purchase in Samsung:
   • Create a new product group (see Samsung documentation)
   • Create new products (see Samsung documentation). For initial payment configuration purposes, please add at least one product).
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 Samsung 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 Security Key and App ID in the Cleeng Dashboard.
5. Register a user in your Samsung application.
6. Make an initial purchase.
7. 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
• Recurring payment
• Subscription switch (upgrade/downgrade)
• Subscription renewed
• Payment failed