/public/widget/data | Documentation

Fetch data (i.e. recommendations) for a content widget.

Unlike the API methods for configuring content widgets, this method does not require HTTPS or any form of authentication.

In most cases there is no need to make direct requests to this API method. From web pages we recommend that you use the JavaScript function 'insertWidget' as described in the Cxense Content Integration Guide. For ad hoc testing and debugging you should consider using /widget/data/preview.

Request

The request object has the following fields:

Name	Type	Required	Description
`widgetId`	String	Yes	Identifier of a content widget object .
`user`	Object	No	Information about the current user / consumer.
`context`	Object	No	Information about the current context / page.
`tag`	String	No	Only display results from the branch with the given tag and ignore other conditions.
`prnd`	String	No	Identifier for the page view where the result of this call will be displayed. Should only be provided when overridden using setRandomId in cx.js .
`userAgent`	String	No	Device-specific userAgent, utilized to override the user agent information in the request headers when necessary.
`consent`	List of Strings	No	List of consent classes .

In addition, the service may use any third party cookies in the request.

"`user`" request object

A user object can have the following fields:

Name	Type	Description
`ids`	Object	Map from ID-types to IDs (String to String). ID-types are defined as a customer-prefix . Example for default Cxense id: `"user": {` `"ids": {` `"usi": "12343123411343595"` `}` `}` Example for an external-id linked with the customer-prefix "`xyz`": `"user": {` `"ids": {` `"xyz": "subscriber14"` `}` `}`
`likes`	Object	Preference object (see below).
`dislikes`	Object	Preference object (see below).

Name

Type

Description

ids

Object

Map from ID-types to IDs (String to String). ID-types are defined as a

customer-prefix

. Example for default Cxense id: "user": {

"ids": {

"usi": "12343123411343595"

}

} Example for an external-id linked with the customer-prefix "xyz": "user": {

"ids": {

"xyz": "subscriber14"

}

likes

Object

Preference object (see below).

dislikes

Object

Preference object (see below).

"`context`" request object

A context object can have the following fields:

Name	Type	Description
`url`	String	The URL.
`contextualUrls`	Array of String	An optional set of contextual URLs that are used for collaborative matching and are filtered from the result.
`pageclass`	String	Specifies/overrides the pageclass of the current page.
`sentiment`	String	Specifies/overrides the sentiment of the current page.
`recommending`	Boolean	Specifies/overrides the recs-recommending setting of the current page.
`categories`	Object	Specifies/overrides the categories of the current page.
`keywords`	Array of String	A list of dynamic keywords describing the context.
`neighborRemovalKeys`	Array of String	A list of custom document fields to use when excluding already recommended articles. For this to work the fields must be returned in the result fields . See `neighbors` field below for more info. Default is [`recs-articleid`, `id`].
`neighbors`	Array of String	A list of strings uniquely identifying articles (queryable from the `neighborRemovalKeys` fields) already linked to near this widget to avoid recommending the same articles. By default the article id is used, which will only work when articles are tagged with cXenseParse:articleid .
`referrer`	String	The URI of the document that linked to this page.
`parameters`	Object	Parameter object. Object with key and value. This is used for placeholders. See Content configuration placeholders .
`uncachedSettings`	Boolean	If true, widget/content settings will be read per request, bypassing caches. This must only be used for testing, not on production sites.

"context": {
 "url": "https://cxnews.azurewebsites.net/articles/world/arsenal-relies-own-goal-beat-10-man-newcastle-135849921",
 "referrer": "https://cxnews.azurewebsites.net/",
 "neighbors": ["135849921", "135849924", "135849654"],
 "categories" : { "taxonomy" :"news/politics", "source":"external", "subscriber": "no" }
}

As of July 2014 the fields pageclass, sentiment, recommending and categories only have effect on "conditional" content settings.

Furthermore keywords must be explicitly enabled for "recs" content settings to have any effect (see Content settings object). If specified, the field categories is a map from category type to path, e.g. {"taxonomy":"news/politics"}.

Best practice available, which demonstrates how to: Using "context" as a dynamic parameter for content-configurations

The fields 'likes' and 'dislikes' should not be used in general. They were added for a particular use case where the site has information about user preferences that cannot otherwise be deduced (by Cxense).

"`preference`" request object

A preference object can have the following fields:

Name	Type	Description
`categories`	Array of String	An array of categories.
`boost`	Float	A boost value between 0.0 and 100.0 indicating the level of boost to give for the list of categories. Note that 0.0 (the default) has the special handling of being a filter instead of a boost.

Response

The response object may have the following fields:

Name	Type	Description
`items`	Array of Object	Array of content widget data object.
`template`	String	The HTML template that should be used to render the widget.
`style`	String	The CSS style that should be used to render the widget.

The template and style fields are only present the widget object specifies the template and style.

Each data object consists of fields specified in the content configuration object, if these fields are available.(In other words, this response object has fewer levels of nesting as the matches from recs.cxense.com)

Whenever a data object contains the field 'url', it will also contain the field 'click_url' (which redirects to 'url'). This click URL is used to count and analyze the widget clicks. In particular, it is used to compute the CTR.

Tracking without redirect

Tracking without redirects can achieved by modifying the click_url path so it returns an image instead of a redirect.

The new click_url path must start with /public/widget/click/image/ instead of /public/widget/click/

Example (where the result has been pretty-printed)

HTTP POST request:

$ curl 'https://api.cxense.com/public/widget/data' -d '{"widgetId":"f1560e95a1e119c26121d5bd42190629f6b798e5","user":{"ids":{"usi":"123"}},"context":{"url":"https://www.cxense.com"}}'
{
 "items": [
 {
 "url": "https://www.cxense.com/about/news/1-minute-online-business-thrive",
 "title": "Take 1 minute to learn how to make your online business thrive",
 "dominantthumbnail": "https://analytics.cdn.cxense.com/analytics/ImageService/ThumbnailDominant_mGp0qDlpMhLRKXW28sY688eE%29yU%3D",
 "click_url": "https://api.cxense.com/public/widget/click/jLGgg6ALXB4DgVfy-PQSGQxEdTetVlle3xPHuu3m7ZUoXgsXcHov9nE-1XO58DBUy1p3eD-zdDcW3sweF2O4aREMuQWd5HdAd_knrE3WeiHPr9TFjY5rj0U7KXYO9i3_W7zbQLIvhR2X-Gf2-9QWmLxzVzjCgbLpJE3HzDXLiDMqj_NTAi2HlLQ8tJeqGv4SXSUAXg8-m1OhWx8Mp4SxBbdR292JgcsQN_lYyXkbkX5_oV8yZlEqyn5NH36pyYsLM57SdHisjfhnGxTSJJvQIAGo2OAejD2e9WB1WbiDjGxmgQdVr6kKho_wWEtQIe-Vk4iQ7DCdPjk7IM1sVRNiEIKJAiErrSgX-hfP9ckKwShNhZPrkwvylYuFek_s_O1UM1XWJylrgVh5Nuk5H-vPzuH6qxV0ekj4c2xx-kxuiRXP3e9AlxaZGuLqqqIAqt3hAo_-cep1PgcDyJ_Raen53lqNUVLOgc9EQ_HroAnNf1H2vO4JyCdXoaCFtNEc2NSg-hF3JKuujjcMpDmfeL_J-n-7gMp5RDs5Dw0"
 }
 ]
}

With HTTP GET instead of **POST **request, the payload will be added url-encoded as json HTML parameter:

$ curl 'https://api.cxense.com/public/widget/data?json=%7B%22widgetId%22%3A%22f1560e95a1e119c26121d5bd42190629f6b798e5%22%2C%22user%22%3A%7B%22ids%22%3A%7B%22usi%22%3A%22123%22%7D%7D%2C%22context%22%3A%7B%22url%22%3A%22http%3A%2F%2Fwww.cxense.com%22%7D%7D'

Last updated: December 28, 2023

Request

"user" request object

"context" request object

"preference" request object

Response

Tracking without redirect

Example (where the result has been pretty-printed)

"`user`" request object

"`context`" request object

"`preference`" request object