Use our JavaScript snippet

Our basic JavaScript snippet is a block of code that you insert into your web app. It’s a low-impact way to send data to—through your users’ web browsers. While an API integration is more flexible, this is a really quick way to get started.

We also have a Custom forms JavaScript snippet that helps you identify people who fill out your forms. See Custom form integrations for more information.

 You can also integrate directly with our API

Our JavaScript snippet makes it really easy to get started, but isn’t essential. You can do everything through our REST API.

Add the JavaScript snippet

Below is an example snippet for the US region. You can go to Data & Integrations > Integrations > API to get the snippet with all the values specific to your region and workspace.

You should include this snippet on every page in your app, immediately before the closing </body> tag.

 Use the right snippet for your region

If your account is based in the EU, the JavaScript snippet references track-eu.js. If you use the US-based snippet for an EU-region account, we’ll redirect requests accordingly, but your data may be subject to logging in the US.

<script type="text/javascript">
    var _cio = _cio || [];
    (function() {
        var a,b,c;a=function(f){return function(){_cio.push([f].
        var t = document.createElement('script'),
            s = document.getElementsByTagName('script')[0];
        t.async = true;    = 'cio-tracker';
        t.setAttribute('data-site-id', 'YOUR_SITE_ID');
        t.setAttribute('data-use-array-params', 'true');
        t.src = '';
        //If your account is in the EU, use:
        //t.src = ''
        s.parentNode.insertBefore(t, s);

Identify your users

You must identify people before you can add them to segments and send them messages. You can do this by adding the _cio.identify function to your HTML, beneath the JavaScript snippet.

// Send this when a user logs in or you otherwise identify them. 
<script type="text/javascript">
        // Required attributes — you must include at least one of the following
        id: 'YOUR_USER_ID_HERE',   // Unique id for the currently signed in user in your application.
                                   // This value is an email address if your workspace uses email
                                   // as an identifier.
        email: '',  // Email of the currently signed in user.

        // Strongly recommended when you first identify someone
        created_at: 1339438758,   // Timestamp in your system that represents when
                                  // the user first signed up. You'll want to send it
                                  // as seconds since the epoch.

        // Example attributes (you can name attributes what you wish)
        first_name: 'John',       // Add any attributes you'd like to use in the email subject or body.
        last_name: 'Smith',       // First name and last name are shown on people pages.
        plan_name: 'premium'      // To use the example segments, set this to 'free' or 'premium'.

When you send _cio.identify, you must send an identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace.. Depending on your workspace settings, this may be either:

  • id: the person’s unique identifier that maps a person to your backend systems.
  • email: the person’s email address.

When you first identify someone, we strongly recommend that you send created_at. This value is a timestamp (seconds since epoch) representing the moment you first identified and created a person. You shouldn’t pass this value with subsequent identify calls, or you’ll overwrite a person’s created_at attribute.

You can also send in additional attributesA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages. that are of value to you. In the above example we send first_name, last_name and plan_name attributes. You can use these attributes to segment your audience or to personalize messages for people.

Automatically identify people who click tracked links

By default (for workspaces created after July 12, 2021), automatically appends a _cio_id parameter containing a person’s cio_idAn identifier for a person that is automatically generated by and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc). to tracked linksA link in a message that logs when a person clicks it. You can gather metrics for tracked links and use them to determine your audience’s level of engagement.. If your tracked links send people to a webpage containing our JavaScript snippet, the snippet automatically identifies people.

Even if you don’t use our JavaScript Snippet, you can still take advantage of the _cio_id parameter in tracked links to identify people. If you integrate directly with our API or one of our libraries, you can identify people using cio_<_cio_id-param-value> rather than a person’s ID or email address.

To change or disable this setting:

  1. Go to Settings > Workspace Settings.

  2. Go to URL Parameters. If you already have URL parameters enabled, click Settings; otherwise, click Get Started.

  3. Click Add _cio_id URL parameter.

    Auto-identify setting
    Auto-identify setting

This setting affects messages you send after you enable or disable it. It does not affect messages that you’ve already sent.

Update a person’s attributes

To update an existing user’s attributes, just send the _cio.identify call again. You must include a valid identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. value—normally id or email—and any attribute you want to set or change for that person. If the attributes already exist in their profile, we overwrite them. If your request includes new attributes we add them to the profile.

Send events

You may want to track custom events like “watchedIntroVideo” or “purchased”. In most cases, you should make _cio.track calls after _cio.identify for the logged in user, so that you can associate events with a person in your workspace.

<script type="text/javascript">
    _cio.track("purchased", { price: "23.45" });

Send anonymous events

You can send anonymous events with _cio.track. If you’ve enabled Anonymous event merging, the JavaScript snippet automatically associates events (that occurred in the past 30 days) with people when you identify them.

 Anonymous event merging is on by default for new workspaces

If you created your workspace before July 2021, you must enable Anonymous event merging. Otherwise, anonymous events are not associated with people you identify.

This provides a way to attribute events to a person before you identify them (before they log in, sign up, etc). See anonymous events for more information.

<script type="text/javascript">
    _cio.track("addedToCart", { product: "cool-shoes" });
        id: 'YOUR_USER_ID_HERE',

Page events

The JavaScript snippets automatically captures page events whenever it loads. For most websites, this means that you’ll capture page view events every time a person goes to a new page. When the page loads, the JavaScript snippet automatically captures the full page URL—window.location.href—and other basic user information, like the user agent and window dimensions.

This appear in your activity log or on a specific person’s activity as a page event. You can use these events to trigger campaigns, add people to segments, etc.

You can also pass your own page events, which you might need to do if you install our snippet in your single page application. See page view events for more information. Page events take two optional parameters—the page name and an additional object data. If you leave the page name empty, we use the current URL (window.location.href).

<script type="text/javascript">"pageName", {"extraDataObject": "moreData"});

Handling arrays

To maintain the integrity of arrays in event calls, set t.setAttribute('data-use-array-params', 'true'); in the JavaScript snippet. It may be commented-out in the copy of the snippet that you copy from the Integrations page. With this setting set to true, arrays in track calls will maintain their shape as expected.

If you do not set this parameter, the javascript snippet reshapes arrays as objects with integer keys. For example, the following event with an array results in a payload formatted as an object.

Track callReshaped payload
  _cio.track('test_event, { my_array: ['one', 'two'] })
  "my_array": {
    0: "one"
    1: "two"

You can override the data-use-array-params setting from the JavaScript snippet on any individual track call using the useArrayParams boolean. Set it to true to maintain the shape of arrays in your request. If useArrayParams is false or absent, arrays in your request are reshaped as objects.

_cio.track('my_event', { my-array ["item1", "item2"]}, { useArrayParams: true });

Stop identifying a person

When a person logs out of your website or app, you can clear the session by calling _cio.reset().


If you want to identify a new person—like when someone switches profiles on your website, etc—you can simply call _cio.identify() for the new person. The new person then becomes the currently-identified person, with whom all new information—messages, events, etc—is associated.

Copied to clipboard!
Is this page helpful?