20

Tracking custom events

How it works

Most source methods have a defined purpose: the identify call identifies users; page calls track pageviews. But the track call lets you send custom events, so that you can track the activities that are meaningful to you. Track calls take a name representing the name of the event you want to track and a set of custom properties.

For example, when someone adds an item to their cart, you might send an added_to_cart event with properties representing the item that your customer added to their cart.

If you run an online class and you want to track progress, you might send a call when people begin a new module in the course or watch a video. The names of your events might be module_started and video_started; and the properties would contain information about the module that a person began or the video they watched respectively.

Events can be anonymous

You can send track calls before or after you identify someone—when they sign up, login, provide their email, etc; the order of calls doesn’t matter. Most destinations automatically resolve anonymous activity to the “identified” user after you send an identify call.

In rare cases—like with Mixpanel—you’ll have to send an alias call to associate anonymous activity with the identified person. But even in these rare cases, you can still associate anonymous activity with a person after they make themselves known.

The power of properties

Track calls take a custom dictionary of properties. Properties are simply nested JSON and can contain any data you want to pass along to your destinations. This includes nested objects, arrays, and arrays of objects.

When you set up events, you should send all the data that you think might be useful—even if you won’t use this data in all of your destinations. You can always ignore data at your destination, but you can’t use data in a destination that you don’t send from the source!

Here’s the complete, JSON representation of an event. See the properties object? That’s information you can use downstream in your destinations.

{
  "userId": "AiUGstSDIg",
  "type": "track",
  "event": "Course Started",
  "properties": {
    "course_name": "Intro to Customer.io Data Pipelines",
    "courseId": "cdp101",
    "progress": 0,
    "modules": [
        {
            "moduleId": "cdp101-1",
            "moduleName": "track calls",
            "started": false
        },
        {
            "moduleId": "cdp101-2",
            "moduleName": "identifying people"
            "started": true
        }
    ]
  },
  "integrations": null,
  "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  "receivedAt": "2015-12-12T19:11:01.266Z",
  "sentAt": "2015-12-12T19:11:01.169Z",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "version": 0,
  "context": {
    ...
    },
    "page": {
      "name": "string",
      "path": "/docs/",
      "referrer": null,
      "search": null,
      "title": "Customer.io Docs",
      "url": "https://customer.io/docs",
      "keywords": [
        "string"
      ]
    },
    "library": {
      "name": "analytics.js",
      "version": "2.11.1"
    }
  },
  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  "originalTimestamp": "2015-12-12T19:11:01.152Z"
}

Example use cases

The following use cases are examples of the things you might send with track calls. You can copy these examples if they fit your use case, but you’ll get more out of your integration if you tailor calls to fit your needs!

Logging in and logging out

When someone logs in, or creates an account, you’ll send an identify call. But in these cases, you’ll also send a track call. Track calls on login and log out can help you track the length of sessions in your app, understand the times when your users are most active, and other information independent of identify calls!

Your log in and log out track events will look something like this:

analytics.track("login", {
  username: "cool.person"
  session_started: 1683250025
  platform: "chrome"
  login_page: "https://fly.customer.io/pipelines/my-pipelines"
});

analytics.track("logout", {
  username: "cool.person"
  session_ended: 1683361625
  logout_from: "session_expred"
});

Added to cart

If you run an online store, you probably want to keep track of the products that your audience is interested in, and the items they add to their cart for things like cart abandonment campaigns and to help you anticipate changes in your inventory.

So, when someone clicks Add to cart, you might send a call that looks like this:

analytics.track("added_to_cart", {
  item_name: "Cool New Sneakers"
  brand: "Nike"
  qty: 1
  price: 99.99
  sku: "abc123"
});

Media started/ended

If you run a media operation, you’re in education technology, or you deliver webinars, you might want to know when your audience plays videos (so you can track progress) and online lectures. These kinds of things help you better understand when people use your videos, whether or not they finish them, and other engagement needs—like play speed.

You might attach track calls to the buttons in a video player to capture play, pause/stop, and other things about media.

analytics.track("video_watched", {
  video_name: "Cool New Video"
  length: 1.56
  speed: 1.25
  finished: false
});