Custom parameters

• • JavaScript API
    • Session annotation
  • URL API
  • HTTP API

Event data can be submitted to the Cxense platform using JavaScript or HTTP APIs. Additional information about an event, i.e., further information about an event other than the fact that it occurred, can be expressed using custom parameters. For example, a site could add information about whether a page view event comes from a registered user by including the value true for a custom parameter named registered.

• The type of value a parameter can hold is limited to either consisting of a small number of unique strings, or being an integer.

• A sum will be calculated when the value can be parsed as a number.

JavaScript API

Custom parameters are added to the page view event by pushing them to the cX call queue using the setCustomParameters command. For example, to additionally tell the Cxense platform that a page view event was generated by a registered user, one might do as shown in the example below.

cX.callQueue.push(['setCustomParameters', { 'registered': 'true' }]);

The recommended way is to add all custom parameters before issuing the sendPageViewEvent command, which will make sure only one HTTP connection is used to transfer all parameters. Parameters added after the page view event has been sent will be lost. The optimal method for when all parameter data is available on page load would thus be as follows:

// Site information.
cX.callQueue.push(['setSiteId', '1234']);

// Custom parameters.
cX.callQueue.push(['setCustomParameters', { 'registered': 'true', 'level': '42' }]);

// Ready to send the page view event after all custom parameters have been added.
cX.callQueue.push(['sendPageViewEvent']);

There are several JavaScript methods related to custom parameters that can be added to the call queue:

For user and retargeting parameters it can be useful to be able to set multiple values for the same parameter at the same time. This can be done by setting the value to an array of values. Each value of the array must conform to the restriction on value length, and there can be at most 10 entries in the array. If more than 10 values are given in the array, it is undefined which 10 values are used.

// Site information.
cX.callQueue.push(['setSiteId', '1234']);

// Custom parameters. Sets "books", "science" and "cars" in the user's profile, under the group "interests".
cX.callQueue.push(['setUserProfileParameters', { 'interests':['books', 'science', 'cars'] }]);

// Ready to send the page view event after all custom parameters have been added.
cX.callQueue.push(['sendPageViewEvent']);

Session annotation

From JavaScript, you can also start and stop automatic annotations of events in a session. Starting an annotation means that all events from now on will automatically be assigned the custom parameter you choose.

Stopping an annotation stops the automatic addition of custom parameters to events.

The use cases for session annotations are for example:

• You want to track the origin of a visit, e.g. this session was started by a gift card offer

• You want to track a visitor path

// Starts the automatic addition of the custom parameters "a: 1" and "b: 'c'" for all further events in this session:
cX.callQueue.push(['startSessionAnnotation', { a: 1, b: 'c' }]);
cX.callQueue.push(['sendPageViewEvent']);

You can at any time add more annotations. The new annotations will merge with the existing ones, overriding the ones with the same key:

// Changes the annotation of "b: 'c'" and adds the annotation of "d:'f'" for all further events in this session:
cX.callQueue.push(['startSessionAnnotation', { b: 'e', d: 'f' }]);
cX.callQueue.push(['sendPageViewEvent']);

You can also at any time stop the annotation of one or more custom parameters:

// Stops annotation of "b:'e'", matching both the key name "b" and the value "e":
cX.callQueue.push(['stopSessionAnnotation', { b: 'e'}]);
cX.callQueue.push(['sendPageViewEvent']);

Or stop for any value:

// Stops annotation of "b", matching only the key name "b" and not the value "e":
cX.callQueue.push(['stopSessionAnnotation', { b: null}]);
cX.callQueue.push(['sendPageViewEvent']);

If you want to keep the annotation for this pageiew, but then stop it, you can place the stopSessionAnnotation call on the line below "sendPageViewEvent":

// Stops annotation of "b", starting at the next pageview event
cX.callQueue.push(['sendPageViewEvent']);
cX.callQueue.push(['stopSessionAnnotation', { b: null}]);

Finally, you can stop all annotations:

// Stops all annotations:
cX.callQueue.push(['stopAllSessionAnnotations');
cX.callQueue.push(['sendPageViewEvent']);

URL API

In some cases you might want to add custom parameters only for those page view events that have a given source of origin, e.g., perhaps you only want to add a custom parameter if the page is viewed as the result of clicking a certain external link. One way to do this is to add JavaScript to the landing page in question and use the abovementioned JavaScript API to only set custom parameters if certain conditions hold. This works, but adding the required custom JavaScript logic can be cumbersome. To this end, defining custom parameters based on the presence of certain URL parameters in the external link is also supported as a more convenient alternative.

All URL parameters that start with the prefix cx_ are treated as custom parameters. I.e., if the Cxense script is present on the page and the link contains one or more such URL parameters, these are automatically interpreted as custom parameters for page views involving that link.

https://www.example.com/foo?cx_registered=true&cx_level=42

HTTP API

This API is in the process of being deprecated, and will be replaced shortly with something else. Contact Cxense support if you need to send custom parameters to the Cxense platform using HTTP.

Custom parameters can be added by using the prefix cp_ for parameter names. E.g., the custom parameter named registered with the value true will thus become cp_registered=true. Only the pgv event type is currently supported, so each request must include typ=pgv and include all required parameters.

GET /Repo/rep.html?ver=1&typ=pgv&sid=1234&ckp=user12345&rnd=0.52254374988082919&loc=http%3A//example.com/app%3Fa%3Db%26c%3D&cp_registered=true&cp_level=42 HTTP/1.0
Host: comcluster.cxense.com
X-Forwarded-For: 173.203.85.136
User-Agent: ExampleBrowser v1.0

Last updated: December 28, 2023