We’ve migrated our documentation to a new site, which means some URLs have changed.
Audience
Audience
Breadcrumbs

/dmp/push

This request can be used for authenticated feeding of DMP events to the processing system. Aggregation of the fed events can be done with /dmp/traffic, /dmp/traffic/event, /dmp/traffic/custom using DMP filters.

We recommend to use the DMP event helper function - sendEvent(..) when sending DMP events with a client-side approach (whenever it is possible). The function automatically sets the correct values for userIds, siteId, rnd and prnd.

The user must be authenticated and have write permissions to site groups/sites. The sites must be set up with a long-term and dmp capabilities.

Request

The request object has the following fields:

Name

Type

Required

Description

events

Array of Object

Yes

An array of DMP events to feed.

Each event object has the following fields:

Name

Type

Required

Description

time

Integer or String

No

Allows to specify the exact time of an event. Can be specified either as seconds measured in

Unix time

(e.g. 1400078399) or as

ISO 8601

date and time in extended format (e.g., "2014-05-14T14:39:59.000Z"). The specified time must be less than 12 hours behind the current time, and not more than 60 seconds in future. If not specified, the time of event will be set to the current system time.

userIds

Array of Object

Yes

List of known user identities to identify the user. Note that different users must be fed as different events.

pageViewEventId

Integer

No*

A value uniquely identifying the corresponding page view event. In order to link DMP events to page views this value must be identical to the eventId value of an

exported page view event

. See the clarification below.

eventId

Integer

No*

A value uniquely identifying this event. Multiple events on the same page view must have distinct eventId values. Values of previously imported events can be obtained via

/dmp/traffic/data

. See the clarification below.

prnd

String

No*

An alternative specification for pageViewEventId, meant to be used by the

sendEvent(..)

function or similar. In order to link DMP events to page views this value must be identical to the rnd value of the

page view event

. See the clarification below.

rnd

String

No*

An alternative specification for eventId, meant to be used by the

sendEvent(..)

function or similar. Multiple events on the same page view must have distinct rnd values. See the clarification below.

siteId

String

Yes

The analytics site identifier to be associated with the events.

origin

String

Yes

Differentiates various DMP applications used by the customer. Must be prefixed by the

customer prefix

e.g. pre-origin0.

type

String

Yes

Differentiates various event types, e.g., "click", "impression", "conversion", etc.

customParameters

Array of Object

No

An optional list of customer-defined parameters. Parameters fed with DMP events follow the

same syntactical restrictions and limits as for ordinary custom-parameters for analytics events

.

consent

Array of String

No

An optional list of consents, such as "required", "pv", "recs", "segment", "ad", "geo", "device"

Syntactical Restrictions

  • STRING PARAMETERS: The maximum length of string parameters is 30 characters.


Event identifier clarification

  • While not mandatory, it is highly recommended to specify eventId and pageViewEventId each event. pageViewEventId is needed to distinguish between events corresponding to different page views, and eventId is needed to distinguish between different events for a single page view. For correct linking with page views, the pageViewEventId value must correspond to the eventId value of the corresponding page view event.

  • Generally speaking, eventId and pageViewEventId should be used when the eventId value of the original page view event is available (e.g., importing new DMP event based on the previous results from /traffic/data and /dmp/traffic/data), while rnd and prnd specification should be used when the rnd value of the originating page view event is available (i.e., alongside sending a page view event from cx.js).

  • Missing eventId/rnd will result in eventId being set to 0, missing pageViewEventId/prnd will result in pageViewEventId being set to 0. If two events for the same user have the same eventId/rnd and pageViewEventId/prnd, then the two events will be considered as duplicates. Duplicate events is subject to de-duplication.




Each user identifier object has the following fields:

Name

Type

Required

Description

type

String

Yes

Site specific identifier (type cx) or

external user identifier

type.

id

String

Yes

Value of the user identifier.

For the custom parameter object, the following fields apply:

Name

Type

Required

Description

group

String

Yes

Parameter name, e.g., "campaign", "adspace" or "creative". The group name must be unique within the customParameters.

type

String

No

Parameter type, e.g. 'number' or 'string'. Use number for items to be used as

DMP metrics

, and string for items to be used in top-lists.

item

String

Yes

Parameter value, e.g. '"sale"', '0.32', '42'. The format must agree with the specified type, i.e., use "42" for string and 42 for number.

Response

The normal response is an empty object.

Examples

Bash
$ python cx.py /dmp/push '{
 "events": [
 {
 "userIds": [
 {
 "type": "cxd",
 "id": "123456"
 }
 ],
 "pageViewEventId": 12345,
 "eventId": 12,
 "siteId": "987654321",
 "type": "impression",
 "origin": "cxd-ads",
 "customParameters": [
 {
 "group": "ad",
 "item": "shoead5"
 },
 {
 "group": "campaign",
 "item": "shoesale"
 },
 {
 "group": "creative",
 "item": "fancyshoe"
 },
 {
 "group": "adspace",
 "item": "header"
 }
 ],
 "consent": ["pv", "recs"],
 }
 ]
}'
{}

Pixel API

In some cases, we want to track performance data from tags or sites that do not run our CX.js script. We want to be able to do a pixel request towards our servers with URL parameters that are forwarded as a DMP event. One example could be tracking an impression from landing page of an advertiser that is not our customer, or a pixel tracker from an email newsletter.

This API will not require authentication of the client, but it will need to identify a persisted query.

Every request has to pass valid 'persisted' parameter.

All data is passed as URL query parameters. Values and keys are URL encoded.


Format of query string

/ : - reserved characters, cannot be used in key name neither parameter value

query_string: persisted=value(&debug=true)?(&key=value)* 
value - URL encoded string
key - URL encoded string 
key: primitive | object
primitive - string 
object - object_name/field_1:value_1/field_2:value_2 ... /field_n=value_n 
/ - field separator : - value separator object_name - string
field - string value - string

()? - means zero or one occurrence

()* - means zero or many occurrences

| - means 'or'

Below is presented translation of 'event' object into list of key value pairs and then into query string:

1. Event

JSON
{
 "userIds": [
 {
 "type": "cxd",
 "id": "123456"
 }
 ],
 "pageViewEventId": 12345,
 "eventId": 12,
 "siteId": "987654321",
 "type": "impression",
 "origin": "cxd-ads",
 "customParameters": [
 {
 "group": "ad", "item": 15.5, "type": "number"
 },
 {
 "group": "campaign", "item": "shoesale", "type": "string"
 }
 ]
 }

2. List of corresponding key=value pairs

Bash
pageViewEventId=1234
eventId=12
siteId=987654321
type=impression
origin=cxd-ads
userIds/type:cxd/id=123456
customParameters/group:ad/item:15.5/type=number
customParameters/group:campaign/item:shoesale/type=string

3. Final Query String

Bash
?persisted=nf4544&pageViewEventId=12345&eventId=12&siteId=987654321&type=impression&origin=cxd-ads
&userIds%2Ftype%3Acxd%2Fid=123456
&customParameters%2Fgroup%3Aad%2Fitem%3A15.5%2Ftype=number
&customParameters%2Fgroup%3Acampaign%2Fitem%3Ashoesale%2Ftype=string

HTTP GET Request format

  1. /dmp/push.gif?query_string

  2. /dmp/push.html?query_string

Bash
https://comcluster.cxense.com/dmp/push.html?persisted=5555&pageViewEventId=12345&eventId=12&siteId=987654321&type=impression&origin=cxd-ads
&userIds%2Ftype%3Acxd%2Fid=123456
&customParameters%2Fgroup%3Aad%2Fitem%3A15.5%2Ftype=number
&customParameters%2Fgroup%3Acampaign%2Fitem%3Ashoesale%2Ftype=string

HTTP Response format

  • html (/dmp/push.html)

Example: <html />

  • 1px gif (/dmp/push.gif)

Example: GIF89a����!�,D;

  • JSON (/dmp/push.html?debug=true or /dmp/push.gif?debug=true) if HTTP Status Code not 200

Example: HTTP Error 400: Bad Request {"error":"Invalid request: Invalid persisted request id"}

Last updated: