Audience: event helper function - sendEvent(..)

Background and motivation

To send a Performance event of any type, the cX.sendEvent(<arguments>) helper function can be used.

The function will use the /dmp/push API internally, through a persisted query that you need to setup.

The helper function handles:

Reading the required parameters from the session and from the page
Adding the current user ID to the request

Specification / Syntax

// asynchronous version
cX.callQueue.push(['sendEvent', <event type> [, <custom parameters>] [, <options>] ]);
 
// synchronous version
cX.sendEvent(<event type> [, <custom parameters>,] [, <options>]);

Where

(required) event type: A string with the name of the event. See below for examples
(optional) custom parameters: Any custom parameter that is associated with the event. All parameters fed with Performance events follow the same syntactical restrictions and limits as for custom-parameters for analytics events.
(optional) options: Options for the execution of the event sending. It can have the following properties

- (optional)persistedQueryId: The id of the persisted query to execute.
- (optional)origin: The origin for the event (see the /dmp/push API documentation)
- (optional)callback: A function that will be called back when the event has been sent.
- (optional)synchronous: true / false (default) - Force synchronous execution (will block page rendering)

Even if "persistedQueryId" and "origin" is marked as optional above, they must always be set in one way or another.

If not set in the call to sendEvent, these two attributes must be set with the setEventAttributes function:

// This sets the attributes for all later sendEvent calls:
 
// asynchronous version
cX.callQueue.push(['setEventAttributes', { origin: 'xyz-website', persistedQueryId: '123456' }]);
 
// synchronous version
cX.setEventAttributes({ origin: 'xyz-website', persistedQueryId: '123456' });

Also:

The "origin" must be prefixed by the customer prefix.
the normal sendPageViewEvent must always be called for all pages where you want to later send custom events with cX.sendEvent. This will allow you to later join the custom event with the corresponding pageview event.

Creating a persisted query

From the Admin UI

Access the Admin UI and "Create a new persisted request"

https://admin.cxense.com/#/cx/api/persisted-queries\

Select dmp/push as your Path.

Fill in the Request data field.

Add events to Mutable fields

Copy the ID out of the overview-table:

From the command line

cx.py /persisted/create '{ "path": "/dmp/push", "request": { "events": [] }, "mutable": { "events": true }}'

This command returns the identity of the newly created persisted query, e.g. something like this:

927c1bd9548fb68791261237d6169a3892h21af

Code examples

The asynchronous version is recommended.
Only use a synchronous approach, if you are aware of all side effects with regard to your page loading!

Asynchronous version

// default asynchronous loading of the cx.js library
<script type="text/javascript">
    (function(d,s,e,t){e=d.createElement(s);e.type='text/java'+s;e.async='async';
    e.src='http'+('https:'===location.protocol?'s://s':'://')+'cdn.cxense.com/cx.js';
    t=d.getElementsByTagName(s)[0];t.parentNode.insertBefore(e,t);})(document,'script');
</script>
 
<script type="text/javascript">
var cX = cX || {}; cX.callQueue = cX.callQueue || [];
 
// default pageview tracking
cX.callQueue.push(['setSiteId', '1234']); // <-- TODO: Insert siteId here
cX.callQueue.push(['sendPageViewEvent']);
 
// one time initialization for all sendEvent calls
cX.callQueue.push(['setEventAttributes', { origin: 'xyz-website', persistedQueryId: '123456' }]);  // <-- TODO: Insert origin and persisted query id here
 
// Send a simple event:
cX.callQueue.push(['sendEvent', 'Video_paused']);
 
 
// Send an event with custom parameters:
cX.callQueue.push(['sendEvent', 'Video_paused', { videoId: '123ks92', videoTitle: 'Tutorial' }]);
 
 
// Send an event and get a callback:
cX.callQueue.push(['sendEvent', 'Video_paused', { }, { callback: function() { alert('Event sent!'); } }]);
 
 
// Send an event synchronously:
cX.callQueue.push(['sendEvent', 'Video_paused', { }, { synchronous: true }]);
</script>

Synchronous version

// synchronous and protocol-aware loading of cx.js
<script type="text/javascript">
  document.write('<scr'+'ipt type="text/javascript" src="http'+(location.protocol==='https:'?'s://s':'://')+'cdn.cxense.com/cx.js"></scr'+'ipt>');
</script>
 
<script type="text/javascript">
 
 
// default pageview tracking
cX.setSiteId('1234'); // <-- TODO: Insert siteId here
cX.sendPageViewEvent();
 
// one time initialization for all sendEvent calls
cX.setEventAttributes({ origin: 'xyz-website', persistedQueryId: '123456' }); // <-- TODO: Insert origin and persisted query id here
 
// Send a simple event:
cX.sendEvent('Video_paused');
 
// Send an event with custom parameters:
cX.sendEvent('Video_paused', { videoId: '123ks92', videoTitle: 'Tutorial' });
 
// Send an event and get a callback:
cX.sendEvent('Video_paused', {}, { callback: function() { alert('Event sent!'); } } );
 
// Send an event synchronously:
cX.sendEvent('Video_paused', {}, { synchronous: true });
 
</script>

Last updated: June 25, 2026