Implementing a Server Side Paywall

Server side widget request

Normally the run method in the cx.cce.js script invokes API at endpoint /public/widget/data with the required parameters. When invoking the API server side the following parameters needs to be added manually:

• User ID: The user id to use is stored in the cookie cX_P. See User tracking and privacy for more details on the cookies stored by Cxense.: 

• Widget ID: This is the ID of the campaign set to deploy. You can find under Settings in the campaign set.

• Current URL: The current url needs to be passed to the API in order to be able to deliver campaign based on location on the site, as well contextual recommendations.

• Referrer URL: The previous URL the user visit. Used to target users coming in from e.g. social networks or search.

• Page View Tracking ID: The ID of the current page view. See details below.

• IP of the user - to be able to do geo targeting based on IP we need to know the customer IP using the X-Forwarded-for HTTP header

Page View Tracking

In a scenario where the paywall decision is done server side before the page view happens, extra steps are required to ensure the events are correctly linked for reporting purposes.

1. On the server, customer must create a page view event ID to be shared across the paywall request and the page view. This can be done by using the logic from cx.js' _randomString method:

   _randomString: function() {
               var randomString = (new Date().getTime()).toString(36);
               while (randomString.length < 16) {
                   randomString += Math.round(Math.random() * 2147483647).toString(36);
               }
               return randomString.substr(0, 16);
           },
   

   
   

2. This id is passed into the request to /public/widget/data on the server using the prnd parameter 

3. The ID is then passed on to the client, and passed on to cx.js prior to submitting the page view event:
     cX.setRandomId('<random id>')

Code examples

1. Sample pageview tracking tag:

   var cX = window.cX = window.cX || {}; cX.callQueue = cX.callQueue || [];
   cX.CCE = cX.CCE || {}; cX.CCE.callQueue = cX.CCE.callQueue || [];
   cX.callQueue.push(['setRandomId', 'dBkisF2QvPMEsj3n']); // server side generated id
   cX.callQueue.push(['setSiteId', '9222302702321341959']);
   cX.CCE.callQueue.push(['sendPageViewEvent', 'cxd', 'e82d54084417a56367924838b765d12304d883e9']);
   
   

   
   

2. Sample widget request object:

   JSON object
   {
   	"context":{
   			"referrer":"https://www.previous.url", 
   			"url":"https://www.current.url"
   	},
   
   	"widgetId":"<widgetid>",
   	"user":{"ids":{"usi":"<value of cX_P cookie>"}},
   	"prnd":"<server side generated id>"
   }
   

   The request should use the endpoint https://api.cxense.com/public/widget/data. GET with parameter json or a POST request.

3. Sample GET request:

   https://api.cxense.com/public/widget/data?json=%7B%22context%22%3A%7B%22referrer%22%3A%22https%3A%2F%2Fwww.previous.url%22%2C%20%22url%22%3A%22https%3A%2F%2Fwww.current.url%22%7D%2C%22widgetId%22%3A%22%3Cwidgetid%3E%22%2C%09%22user%22%3A%7B%22ids%22%3A%7B%22usi%22%3A%22%3Cvalue%20of%20cX_P%20cookie%3E%22%7D%7D%2C%22prnd%22%3A%22%3Cserver%20side%20generated%20id%3E%22%7D
   

   
   

4. If adding Custom User Data it is required that keys are in lowercase to match. Any upper case letters on the categories will not match in the CCE UI, since all keys are lowercased. Sample request including Custom Audience Data below:

   JSON object
   {
   	"context":{
   			"referrer":"https://www.previous.url", 
   			"url":"https://www.current.url",
   			"categories":{
   				"subscriber":"yes"
   			},
   			"parameters":[
   				{
   					"key":"subscriber",
   					"value":"yes"
   				}
   			]
   	},
   
   	"widgetId":"<widgetid>",
   	"user":{"ids":{"usi":"<value of cX_P cookie>"}},
   	"prnd":"<server side generated id>"
   }
   

   
   

Result set

The result set of the API request above is described in detail on /public/widget/data.The CCE result set will contain some default key and values.

Free - open article

If the article is open, the result will contain one item of type "free".

{  
   "items":[  
      {  
         "type":"free",
         "campaign":"1"
      }
   ],
   "template":"",
   "style":"",
   "head":""
}

When processing the result set on the server side any items which are not of type "free" can be considered a locked down article.

When returning a promotion or article then "items" will contain the meta data of the resulting promotion, with image, title, urls etc. This can be rendered on the server side or by using the client side scripts, see below.

Client side rendering

It is possible to use Cxense rendering templates to render the results from a server side requested widget. To do that write the result of the /public/widget/data into a script variable in the page, simulation the data object returned to the renderFunction in cX.insertWidget. On the variable use the function cX.CCE.render to make sure all CCE functionality like visibilty is handled.

   <script type="text/javascript">
        // result from /public/widget/data wrapped in  {"response":{} }
        window.cx_widgetData = { "response": {"items":[{"type":"free","campaign":"24"}], "template": ""} };

		// render result if available
        if (window['cx_widgetData']) {
            cX.CCE.callQueue.push(['render', 'cx_paywall', window['cx_widgetData']]);
        }

   </script>

Last updated: February 04, 2022