API documentation

Cleeng for publisher

Cleeng API One of the key benefits of Cleeng is the easy integration for publishers.

For publishers using a common publishing platform like WordPress or Drupal there are ready-to-use plugin available. However if you have a proprietary or in-house developed platform, or if you want to build your own creative solution, you can work directly with the API. If your platform is based on PHP we recommend you use the PHP Client SDK to simplify your integration even further. Find here the full list of methods available in the API.

Table of contents

Cleeng platform overview
Get started!
Using the Cleeng API
API reference
URLs – Developing & testing your solution
Cleeng Community & support

Cleeng platform overview

The Cleeng Platform is accessible for users via ‘my account‘. This is the central place for users to manage their profile and to view their content library. The Cleeng Platform tracks all purchases done, tracks the Users “balance” and tracks all commissions. Applications, plug-ins and widgets installed on websites or publishing platforms communicate via the Cleeng API to the Cleeng Platform.

Via the API the publisher creates content “references” on the Cleeng platform. The content “reference” includes among other things, the description, the URL and the price. When a user visits the publishers’ platform, the (hidden) content stays on the server of the publisher and is only revealed after a secure API purchase confirmation given by the Cleeng platform. After confirmation the information is pulled from the publishers server with an AJAX request.

Get started!

You can now get started using Cleeng and build your own plugin or application based on the Cleeng API.

Pick your base: start with the PHP SDK or use the API directly
Create a Cleeng account in case you haven’t done so, and register your application. You will receive your personal API key
Build an application, plug-in or widget using this documentation, and start making money immediately.

This documentation is not as comprehensive as a real example. So we recommend you to look into one of the existing plugins to get detailed understanding of how to use Cleeng.

Any feedback on the API, PHP SDK or this document is more than welcome. Please send your comments to us. Of course we look very much forward if you have something cool to show! In case you built a quality plug-in or SDK for a common platform we are more than willing to promote it for you.

Using the Cleeng API

The Cleeng API is available on the following URL. This API supports the JSON-RPC protocol.

https://api.cleeng.com/json

When developing, testing or experimenting with the API you should use the sandbox, which is available on below URL. In case you use sandbox, please avoid covering content on your public website as your visitors might be very confused. Also note that your settings, content references and accounts are NOT copied in between the SANDBOX servers and the LIVE servers.

https://api.sandbox.cleeng.com/json

As specified by the JSON-RPC protocol, all requests use the POST method, and with every request a JSON-encoded object needs to be sent as POST DATA. The object should contain three parameters:

method: name of API function to call
params: specifying the function parameters
id: identifier (for your reference), can be any integer value

Using CURL directly on the command line gives a general format that looks like

curl  https://api.sandbox.cleeng.com/json -d {\
	“method”:”,\
	”params”:,\
	”id:1”\
}

All functions that are available for the Cleeng API are explained in the API reference.

Making a JSON API Call – example getContentInfo

Please find below an example request to the API using CURL from command line. In this case the function “getContentInfo” is used.

curl  https://api.sandbox.cleeng.com/json -d \  '{"method":"getContentInfo","params":[[1]],"id":1}'

As part of the JSON-RPC protocol, the response from the server will always contain three properties (“result”, “id” and “error”), where “result” will contain the information from the Cleeng Platform. The server response of the above “getContentInfo” will be similar to:

{     "result": {
	"success":true,
	"contentInfo": {  
		"1":{                 
			"id":"1",
			"pageTitle":"Title of page",  
			"averageRating":5,                 
			"price":"0.72",                 
			"currency":"USD",                
			"currencySymbol":"$",                 	
			"shortDescription":"short description",                 
			"referralProgramEnabled":false,                 
			"purchased":false,                 
			"canVote":false,                 
			"voted":false  
			}         
		}     
	},     
	"id":"1",     
	"error":null 
}

All API methods return the “success” property (boolean), which tells you if the server request was successful. When success is equal to “true”, the function – specific data is returned (in the above example one-element array of the content description).

In case of failure additional information is returned in “errorCode” and “errorDescription” properties. For an example, consider calling getContentInfo() with invalid argument format:

curl  https://api.sandbox.cleeng.com/json -d \  '{"method":"getContentInfo","params":[“invalid param”],"id":1}'

This will result in a response similar to:

{	"result": {        
		"success":false,
		"errorCode":"ERR_INVALID_ARGUMENT_FORMAT",
		"errorDescription":"Invalid argument format (array expected)",
		},
	"id":"1",    
	"error":null
}

The error is given within the result, as it is an error of the method/function. The top-level errors (last line in above code) are shown when errors happen with the JSON-RPC itself.

Note: in order to simplify the server response, most Cleeng API functions work with an array to be able to exchange multiple results in one call.

Authorized API calls

To obtain secure information from a user via the API (like if a certain user purchased the content), the API will only give proper results when authentication has taken place of the user. Most Cleeng API functions require a user to authenticate before returning any information. After authorization (see next section) a token is obtained (OAuth Token – 32 characters key), which needs to be passed as GET parameter to the API URL:

https://api.sandbox.cleeng.com/json?oauth_token=XXXXXX

For information on obtaining OAuth token, please refer continue to read the next section.

Authentication with OAuth

The Cleeng API uses OAuth 2.0 protocol. (Cleeng uses draft 9 from IETF.org.)

Basic OAuth Flow with Cleeng
Here is how OAuth works in general on the Cleeng platform:

User is redirected to https://sandbox.cleeng.com/oauth/authenticate
User logs in, or if he is already logged in, he will “autologin”
User is redirected back to original website with authentication code passed as a parameter. Now this code needs to be exchanged for an access token, using https://sandbox.cleeng.com/oauth/token
Now this access token can be used for calling API methods.

Getting the Cleeng Access Token
To use the API, you need to have a Cleeng API key.
First step required to authenticate a user is to retrieve the authorization code – a 32-character pseudo-random value. To obtain it, the API has to redirect the user to

https://sandbox.cleeng.com/oauth/authenticate

with the following parameters:

client_id – identifier obtained via application registration
redirect_uri – URL where user will be redirected back
response_type- string value, should always be “code”

After user signs in, Cleeng will redirect him back to redirect_uri with authentication code passed in argument code, which should be exchanged for an access token in next 30 seconds (code will expire after that time). In order to do so, the plug-in has to fetch content from

https://sandbox.cleeng.com/oauth/token

passing the following arguments:

client_id – identifier obtained via application registration
client_secret – password obtained via application registration
grant_type – always “authorization-code”
code – authorization code

If all parameters are correct, the json-encoded object will return one property: access_token. This token can be passed directly to the API with a GET variable (?oauth_token=xxxx).

Signing-out

When a user clicks “log-out” from your website or platform, the user should be signed-out from Cleeng Platform as well. This requires calling logout() method, which destroys the user session on your server and removes the access token from cleeng.com. Example call with command-line CURL:

curl https://api.sandbox.cleeng.com/json.php?oauth_token=XXXXXXXXX -d \ '{"method":"logout","params":[],"id":1}'

Automatic log in

To simplify the user experience, Cleeng provides a method for automatically authenticating users on every website using Cleeng.

For automatic login, a user needs to be logged in on the Cleeng Website. The application or plug-in loads the https://sandbox.cleeng.com/js/autologin.js file. This file contains a JavaScript object, called “CleengAutologin”. It has “available” property, which determines if automatic login is possible. If true, the additional information is provided:

CleengAutologin = { 
    available: true, 
    id: 'SESSION IDENTIFIER',
    key: 'SESSION KEY' 
};

Now, having id and key, they can be passed to autologin() API method. This will return an authentication code, which should be exchanged for the access token.

Purchasing content

When the Cleeng layer is loaded on the website, it should load the Cleeng logo from the Cleeng website. This is done for tracking purposes and a prerequisite to get a full analytical overview of your visitors and their buying behavior on your Cleeng sales reports. But also it is key as our smart fraud mechanisms, as these impressions are used to make judgments about improper content. And only with impressions it will give you visibility on the browse-pages that we have soon available on the site… and this will ultimately lead to more traffic.

From a developer’s point of view, the flow for purchasing content is similar to the OAuth authorization. In order to ensure security and to give the user the ability to confirm their purchase, this process takes place on the Cleeng Website. This means the user needs to be redirected to https://sandbox.cleeng.com/oauth/authenticate with one additional parameter:

purchase_content_id – identifier of content to be purchased

Additionally, if user is authenticated, the plug-in should also pass oauth_token (so that user won’t need to log in again). So the full request becomes like this:

https://sandbox.cleeng.com/oauth/authenticate?response_type=code&client_id=CLIENT_ID&purchase_content_id=CONTENT_ID&redirect_uri=CALLBACK_URL&oauth_token=ACCESS_TOKEN

After purchasing the user is redirected back to callback_url. He will receive a new authentication code (even if he was authenticated before) which has to be exchanged for the access token. Now the application or plug-in can use the functions like getContentInfo() or isContentPurchased(), to check whether the actual transaction took place.

Setting up content as a publisher

To be able to define content on your website to be purchased, you’ll need to create content “references” on the Cleeng platform. To create, update or remove content via the API you’ll need to be authenticated with a Cleeng Publisher account. You can easily upgrade your user account to become a publisher.

See the API reference for all the functions and parameters to store content “references on the Cleeng platform.

API reference

Find here the full API reference with all methods (/functions) you can call, as well as the full list of possible error messages.

URLs: developing & testing your solution

While you are building your application or plug-in you should build it against the Cleeng sandbox environment. This way you can test fully without initiating real financial transactions. Once you are satisfied and you have fully tested your solution, you can change to the Production Environment. Please bear in mind that your settings and trial content on the sandbox environment are not replicated on the live environment. Also we are able to clean-up the content references on the sandbox environment without upfront notice.

Production environment
API (JSON-RPC) - https://api.cleeng.com/json
Authentication - https://cleeng.com/oauth/authenticate
Token - https://cleeng.com/oauth/token

Sandbox environment
API (JSON-RPC) - https://api.sandbox.cleeng.com/json
Authentication - https://sandbox.cleeng.com/oauth/authenticate
Token - https://sandbox.cleeng.com/oauth/token

Cleeng Community & support

Making money with digital content has been a major challenge for many publishers. We believe that the Cleeng Community can bring innovation to content monetization by sharing ideas and solutions among each other. Because for all publishers it is important that many websites and platforms enable Cleeng, as by having more Cleeng users, the more likely Cleeng will be the solution for you and other publishers to best monetize content.

Let the community know about your brilliant ideas, show what you have built, indicate your challenges using the API or share any other. Please read and contribute on our Developer Discussions or contribute to the Publisher Community.

In case you want direct support for the API or you have some other feedback, please get in contact with us directly.