Sending custom vars

Custom vars are additional information on the page, the user or the session, sent along with pageviews.

They generally include datalayer information, such as:

• Page type,
• Product category,
• If the user is signed in or not,
• The number of items in the cart

This information enables visitor segmentation or page grouping, for which the URL would not be enough.

Each custom var is composed of a key (max. 512 characters) and value (max. 255 characters).

You are limited to 20 custom vars per project.
You can update up to 20 cvars on the same page.

Each custom var holds a unique index, strictly comprised between 1 and 20. Custom vars with indexes outside this range are not sent. Indexes are available for users to select within Contentsquare.

Use a consistent index for a given custom var within a project — for instance, if the “page template” is collected with an index of 3, use the slot 3 for this information on every page of the website.

Saving a custom variable creates a URI-encoded cookie which contains a stringified JSON of the stored information. This string may contain all URI allowed characters ↗.

To define a custom var, use the setCustomVariable command:

<script type="text/javascript">
   window._uxa = window._uxa || [];
   window._uxa.push(['setCustomVariable', index, name, value, scope]);
</script>

This means that you have to add an array to the _uxa object, containing:

• index is a integer > 0 and <= 20

• name is a string of 512 characters max (if longer the Tag will truncate it)

• value is a string of 255 characters max (if longer the Tag will truncate it)

• scope (optional) defines the custom var scope and behavior

  • No scope specified (default):
    • In scopes visit and page.
  • 2 or visit:
    • In scope visit.
  • 3 or page:
    • In scope page.
    • Deleted after a Natural pageview.
  • 4 or nextPageOnly:
    • In scope nextPageOnly.
    • Deleted after a Natural pageview, or an Artificial pageview with the next trackPageview command.

Once defined, custom vars are sent automatically with the next pageview (natural or artificial).

Defining a custom var with an index that already exists overrides its name and value.

Defining a custom var in scope visit at index 5 with name cname and value cvalue.

<script type="text/javascript">
  window._uxa.push(['setCustomVariable', 5, "cname", "cvalue", 2]);
</script>

Defining a custom var in scopes visit and page at index 6 with name cname and value cvalue.

<script type="text/javascript">
  window._uxa.push(['setCustomVariable', 6, "cname", "cvalue"]);
</script>

Defining a custom var with the scope nextPageOnly.

<script type="text/javascript">
  // either
  window._uxa.push(['setCustomVariable', 6, "cname", "cvalue", 4]);
  // or
  window._uxa.push(['setCustomVariable', 6, "cname", "cvalue", "nextPageOnly"]);
</script>

• A custom var can be deleted by calling the command with an empty string value. The index parameter must match the custom var to delete.
• Custom vars with scope nextPageOnly are automatically deleted when the next natural or artificial page view is sent.

Deleting the custom var of name cname.

<script type="text/javascript">
  window._uxa.push(['setCustomVariable', 5, "cname", ""]);
</script>

Deleting custom var of name cname from scope visit.

<script type="text/javascript">
  window._uxa.push(['setCustomVariable', 6, "cname", "", 2]);
</script>

Deleting custom var of name cname from both scopes page and visit with an empty scope value.

<script type="text/javascript">
  window._uxa.push(['setCustomVariable', 6, "cname", ""]);
</script>

To verify that custom vars have been sent, check the cvarp parameter of the corresponding pageview.

Learn more about pageviews