1

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 Customer.io—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.

Add the JavaScript snippet

Below is an example snippet for the US region. You can go to Data & Integrations > Integrations > Customer.io 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.

<script type="text/javascript">
    var _cio = _cio || [];
    (function() {
        var a,b,c;a=function(f){return function(){_cio.push([f].
        concat(Array.prototype.slice.call(arguments,0)))}};b=["load","identify",
        "sidentify","track","page"];for(c=0;c<b.length;c++){_cio[b[c]]=a(b[c])};
        var t = document.createElement('script'),
            s = document.getElementsByTagName('script')[0];
        t.async = true;
        t.id    = 'cio-tracker';
        t.setAttribute('data-site-id', 'YOUR_SITE_ID');
        t.setAttribute('data-use-array-params', 'true');
        t.src = 'https://assets.customer.io/assets/track.js';
        //If your account is in the EU, use:
        //t.src = 'https://assets.customer.io/assets/track-eu.js'
        s.parentNode.insertBefore(t, s);
    })();
</script>

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">
    _cio.identify({
        // 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: 'user@domain.com',  // 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'.
    });
</script>

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), Customer.io automatically appends a _cio_id parameter containing a person’s cio_idAn identifier for a person that is automatically generated by Customer.io 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.

   

   

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("watchedIntroVideo");
    _cio.track("purchased", { price: "23.45" });
</script>

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.

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" });
    _cio.identify({
        id: 'YOUR_USER_ID_HERE',
    });
</script>

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.

  _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 });