Understanding the API
In this article you’ll learn the basics of the Cleeng API. It covers the main principles developers need to know before creating a custom Cleeng integration, including:
- Main integration points
- Loading libraries (SDKs)
- Testing your setup
- Authentication tokens
Main integration points
The following sequence diagrams explain the main integration points how basic new visitor flow works.
When a user visits your player, website or application (the app) you first need to validate if they are entitled to watch your premium content. If they are entitled, you can display and load the premium videos (diagram 2). If they are not entitled you want to provide an option to register (or login) and let them buy via an optimized checkout flow (diagram 1).
Sequence diagram: not entitled user
In the diagram you see the main integration points:
- Validate entitlement
With the server-side getAccessStatus API method you can validate if the user is authenticated and authorized to watch your premium content.
- Trigger registration/purchase
*Sequence diagram: entitled user*
In SVOD tutorial 1.1 you will find PHP code for setting up your own SVOD channel on your website that follows the sequence as explained above.
Loading libraries (SDKs)
For secure entitlement validation and many other API calls you need to use server-side methods. You can call the API directly - it is fully based on JSON-RPC. However to simplify the API handling Cleeng provides different SDKs that take care of many aspects automatically. Visit SDKs page in order to find the exact instructions on how to load these SDKs within your application.
Most commonly used Cleeng API methods don’t require an API Key. However if you want to manage offers and prices via the API or use some of our advanced methods you require an API key (Publisher Token or Distributor Token). You can find it in your Dashboard > api-keys section.
Cleeng Sandbox - test environment
When you start to work on your integration you might want to understand the exact responses from the API first. You can use the API console for that.
Once you have something integrated, you need to test the full user flow without doing real payments each time you run a test.
You can apply free access coupons as an alternative to real payments. You can configure 100% discount coupons via your Dashboard > Coupons.
For more extensive integrations and testing you are recommended to connect to the sandbox environment. The sandbox is a separated environment with isolated database. This means that your account details, offers, api-keys and transactions are different from your official account. This gives you the opportunity to fully play around and try out things, without messing up your main account and your reporting. Most important, the sandbox checkout allows you to apply fake credit cards details in the checkout.
Card name: any
Card date: 08 / 2018
In order to use the sandbox you first need to register a new sandbox account here and use the API key as provided in the dashboard of the sandbox environment. If you develop in PHP, and you have loaded the Cleeng PHP SDK you can enable the Sandbox with the following commands:
$cleengApi = new Cleeng_Api(); $cleengApi->enableSandbox();
Most of the API functions will take either "customerToken" or "publisherToken" as their first parameter. Both types of token look similar (they are 48-character keys). Their purpose (and so level of access they give) is different.
After a purchase is made (or access is granted) on the Cleeng platform, Cleeng will automatically pass Customer Token back to your website or application. It can be used then to verify access, using getAccessStatus method.
The Customer Token is automatically stored in a cookie after the purchase process, so in a normal scenario you don't need to worry about handling it.
Two things worth mentioning:
- You can keep the Customer Token stored in the cookie, as it cannot be used to modify any data on Cleeng Platform directly. In that case the user will have to log-in again.
- If you're using PHP SDK, you don't need to worry at all about handling the tokens. The SDK will automatically pass customerToken to functions that need it. For more information, please refer to reference of getAccessStatus, or to tutorials.
By default the Customer Tokens (and the cookie in which they are kept) expire in two weeks after being created. The authentication function (or generateCustomerToken - Enterprise only) can be used to generate new token if old one has expired.
The Publisher Token is used to identify merchant (the seller). This token is used to create and update offers, as well as gives access to other e-commerce functions (like reporting).
It can be obtained from API Keys Page (you must be logged in to Cleeng as a publisher to see this page).
Congrats! You've now been introduced to the main principles of the Cleeng API. Now you are ready for Tutorial 1.1