/widget/report | Documentation

Retrieves Cxense Content reports.

Request

The request object has the following fields:

Name	Type	Required	Description
`type`	String	No	One of `campaign`, `page`, `conversion` or `attribution`. Default is `campaign`.
`widgetId`	String	No	The widget ID. Not available for `conversion` type as conversions are reported on a per-site basis.
`start`	Number or String	Yes	Specified according to Traffic time specification .
`stop`	Number or String	Yes	Specified according to Traffic time specification .
`fields`	Array of String	No	The metrics to aggregate `total` for. Any field documented as part of a `total` object is available. Default is to return all documented fields. For performance reasons it is recommended to specify only the fields actually needed.
`historyFields`	Array of String	No	The metrics to aggregate a `stats` for. Must be a subset of fields. Defaults to value of `fields`.
`historyBuckets`	Integer	No	The desired number of "buckets" to divide the interval into. At most 7*24.
`resolution`	String	No	The size of the "buckets". Possible values: `hour`, `day`, `week`, `month`
`useUtc`	Boolean	No	Whether to use UTC when rounding to the nearest day/week/month.
`timeZone`	String	No	Which time zone to use when rounding to the nearest day/week/month. Specified as name in the TZ database.
`siteId`	String	No	Count only impressions, clicks or conversions originating from the given site.
`targetSiteId`	String	No	Count only impressions and clicks towards the given target site.

At least one of siteId and widgetId must be provided. If widgetId is provided, the user must have read access to the site group id of the widget. If only siteId is provided, the user must have read access to the provided site id. Exactly one of historyBuckets and resolution must be provided. Only one of useUtc and timeZone can be specified. If none of them are specified, the time zone of the site containing the widget is used.

If type is campaign, the request object additionally has the following fields:

Name	Type	Required	Description
`path`	String	No	Count only impressions and clicks with the given "path" (described below).
`paths`	Array of String	No	Count only impressions and clicks with any of the given "paths" (described below).
`recommendationType`	String	No	Count only impressions and clicks towards the given recommendation type. One of `backfill`, `fixed`, `empty`, `creative`, `behavioral`, `collabctx`, `collabusr`, `contextual`, `explicit`, `rate`, `recent`, `search`, `trend`. The recommendation type `empty` is used for widget requests that yielded no results.
`deviceType`	String	No	Count only impressions and clicks towards the given device type. Examples of values are `Desktop`, `Mobile`, `Tablet` or `Smart TV`.
`position`	Integer	No	Count only impressions and clicks towards the given position in the widget.
`positions`	Array of Integer	No	Count only impressions and clicks towards the given positions in the widget.
`experienceId`	String	No	Count only impressions and clicks towards the given experienceId in the widget.
`experienceIds`	Array of String	No	Count only impressions and clicks towards the given experienceIds in the widget.
`groups`	Array of String	No	Count only impressions and clicks grouped by the specified group. The available groups are `position` and `experienceId`.

If type is page, the request object additionally has the following fields:

Name	Type	Required	Description
`url`	String	No	Count only impressions and clicks towards the given url. Numbers are aggregated on normalized URLs. Unique user numbers or `recommendationTypes` will not be returned when using this field.

If type is conversion, the request object additionally has the following fields:

Name	Type	Required	Description
`productId`	String	No	Count only conversions for the given product.
`productIds`	Array of String	No	Count only conversions for the given products.

If type is attribution, the request object additionally has the following fields:

Name	Type	Required	Description
`productSiteId`	String	No	Count only attribution for the given product site.
`productId`	String	No	Count only attribution for the given product.
`productIds`	Array of String	No	Count only attribution for the given products.
`campaign`	String	No	Count only attribution for the given widget campaign.
`campaigns`	Array of String	No	Count only attribution for the given widget campaigns.

For type conversion at least one of productId/s and siteId must be provided. If productId/s is provided, the user must have read access to the site group id and site id of the product. Additionally, site id of all product ids given in one request must be the same.

Response

The response object has the following fields:

Name	Type	Description
`widgetId`	String	The widget ID (as in the request).
`timeZone`	String	"UTC" if `useUtc=true` in the request, otherwise the time zone identifier of where the widget is located.
`history`	Array of Number	The start times of the "buckets" (as Unix time s ordered incrementally). With n buckets, it contains (n + 1) values, where the last value is the stop time of the last bucket.
`total`	Object	A stats entry indicating the total for the provided time interval.
`stats`	Array of Object	A stats entry per "bucket" (in the natural order).
`widgetIds`	Array of String	The widget IDs.
`siteIds`	Array of String	The origin site IDs.
`targetSiteIds`	Array of String	The target site IDs.

If type is campaign, the response object additionally has the following fields:

Name	Type	Description
`paths`	Array of String	The paths (described below).
`recommendationTypes`	Array of String	The recommendation types.
`positions`	Array of Number	The positions within a widget.
`positionStats`	Dictionary	The dictionary from positions to stats entries.
`groups`	Dictionary	The dictionary from the groups to items, for each group defined in the request.

groups is excluded from the response if groups is not defined in the request. positionStats and positions are excluded from the response if groups is defined in the request. In order to get positionStats (if groups is defined in the request), consider adding position as a group in the request.

Each group consists of the following fields:

Name	Type	Description
`group`	String	The name of the group.
`items`	Array of Object	The set of items aggregated for this group.

Each item consists of the following fields:

Name	Type	Description
`item`	String	The name of the item.
`data`	Object	The requested metrics and associated aggregated numbers.

If type is conversion, the response object additionally has the following fields:

Name	Type	Description
`productIds`	Array of String	The products.

If type is attribution, the response object additionally has the following fields:

Name	Type	Description
`productSiteIds`	Array of String	The product sites.
`productIds`	Array of String	The products.
`campaigns`	Array of Object	The campaign stats.

The campaign stats object has the following fields:

Name	Type	Description
`campaign`	String	The widget campaign.
`history`	Array of Number	The start times of the "buckets" (as Unix time s ordered incrementally). With n buckets, it contains (n + 1) values, where the last value is the stop time of the last bucket.
`stats`	Array of Object	A stats entry per "bucket" (in the natural order).

Name

Type

Description

campaign

String

The widget campaign.

history

Array of Number

The start times of the "buckets" (as

Unix time

s ordered incrementally). With n buckets, it contains (n + 1) values, where the last value is the stop time of the last bucket.

stats

Array of Object

A stats entry per "bucket" (in the natural order).

Each stats entry for types campaign and page contains the stats for one history "bucket":

Name	Type	Description
`impressions`	Number	Number of impression requests.
`clicks`	Number	Number of clicks on recommended articles.
`autorefreshes`	Number	Number of impression requests caused by browser auto-refresh.
`visibilitySeconds`	Number	Number of seconds the impressions were visible in total. Visibility must be reported through `/public/widget/visibility`.
`visibleImpressions`	Number	Number of impression requests that were reported to be visible. Visibility must be reported through `/public/widget/visibility`.
`activeTime`	Number	How much time on average a user spent reading the destination article after clicking on a recommendation.

If type is campaign, the stats object additionally has the following fields:

Name	Type	Description
`uniqueUsers`	Number	The estimated number of unique Cxense-specific identities, without consideration to the identities linked by the customer. For more information see the user identities demystification page .

Name

Type

Description

uniqueUsers

Number

The estimated number of unique Cxense-specific identities, without consideration to the identities linked by the customer. For more information see

the user identities demystification page

Each stats entry for type conversion contains the stats for one history "bucket":

Name	Type	Description
`conversions`	Number	The number of conversion requests.
`uniqueUsers`	Number	The estimated number of unique Cxense-specific identities, without consideration to the identities linked by the customer. For more information see the user identities demystification page .

Name

Type

Description

conversions

Number

The number of conversion requests.

uniqueUsers

Number

The estimated number of unique Cxense-specific identities, without consideration to the identities linked by the customer. For more information see

the user identities demystification page

Each stats entry for type attribution contains the stats for one history "bucket":

Name	Type	Description
`directConversions`	Number	The estimated number of conversions directly attributed to one of the campaign of the widget. Direct attribution means the user has clicked on one of the affiliated campaigns with an offer within the last 30 minutes before the conversion.

Further details

Includes aggregated and real-time data

This API includes both real-time data (the same data that the /traffic API uses) and pre-aggregated data depending on the time ranges queried. Be aware that there can be small fluctuations in the results between different calls to /widget/report, in the same way that is in the traffic API.

With `resolution`

The timeZone field in the response is "UTC" if useUtc=true in the request; otherwise it is the time zone of the site of the widget.

The start field in the request is rounded down to the nearest hour/week/month, depending on the resolution; and the stop field is rounded down. The rounding off is done with respect to the time zone, and with Monday as the first day of the week.

The report covers the period from (and including) start rounded down to (and excluding) stop rounded up. If start is not before stop after rounding, then the stats array will be empty (and history will have one element).

With `historyBuckets`

The start and stop fields are rounded down and up respectively, to nearest UTC hour.

Paths

A path is a string of the form <tag 1>/<tag 2>/.../<tag n>consisting of the (non-null) tag fields of a path in the content settings object (seen as a tree).

The stats entries of such a path include every path extension <tag 1>/.../<tag n+1>.

Impressions, clicks and CTR

There will always be one entry in the stats response field for each "time bucket" – even if there were no registered impressions or clicks in the period.

The click-through rate (CTR) is usually calculated as clicks divided by impressions (perhaps multiplied by 100 to get percentage points),but observe that this formula is not always meaningful. Since a click can end up in a later "time bucket" than the corresponding impression,it is possible to have a time bucket with zero impressions and non-zero clicks.

You should also be aware that if you specify path (or siteId) in the request object, then the stats entry field impressions is a relative number:If, for example, only one of four recommended articles has the given path, then this is counted as 1/4 of an impression.

Example

$ cx.py widget/report '{"widgetId":"ce048abf333263a1c23b5825f48e7a40a1bc9b87","start":"2014-01-21T18:00:00.000Z","stop":"2014-01-22T00:00:00.000Z","resolution":"hour"}'
{
 "widgetId": "ce048abf333263a1c23b5825f48e7a40a1bc9b87",
 "timeZone": "Asia/Tokyo",
 "history": [
 1390327200,
 1390330800,
 1390334400,
 1390338000,
 1390341600,
 1390345200,
 1390348800
 ],
 "stats": [
 {
 "impressions": 1255,
 "clicks": 47,
 "autoRefreshes": 1,
 },
 {
 "impressions": 1033,
 "clicks": 54,
 "autoRefreshes": 1
 },
 {
 "impressions": 1045,
 "clicks": 54
 "autoRefreshes": 1
 },
 {
 "impressions": 1466,
 "clicks": 42,
 "autoRefreshes": 1
 },
 {
 "impressions": 2150,
 "clicks": 78,
 "autoRefreshes": 1
 },
 {
 "impressions": 4542,
 "clicks": 144,
 "autoRefreshes": 1
 }
 ],
 "widgetIds": [
 "ce048abf333263a1c23b5825f48e7a40a1bc9b87"
 ],
 "siteIds": [
 "9222326071608921377"
 ],
 "paths": [
 "a/1",
 "a"
 ],
 "targetSiteIds": [
 "9222326071608921377"
 ]
}

Last updated: December 28, 2023

Request

Response

Further details

Includes aggregated and real-time data

With resolution

With historyBuckets

Paths

Impressions, clicks and CTR

Example

With `resolution`

With `historyBuckets`