10

Understanding source calls

How it works

Sources send data into Data Pipelines. Source data is pretty uniform: there are just a few types of calls that sources make.

We map source data to destinations as Actions—the actions your source data take in each destination, like creating people, updating people, tracking custom events, etc.

Actions are unique to each destination. This page describes the different kinds of source calls, so you can:

• Properly implement source libraries and calls.
• Understand the data that you can capture and forward to your destinations.

You can send source calls in any order

In most cases, people who use your site or app begin as anonymous users. You can still track their activities, but they’re attributed to anonymous people (by anonymousId). When someone logs into your app, provides their email, and so on, you should send an identify request. Most destinations—including Customer.io Journeys—handle this situation gracefully and associate anonymous activity with the identified person.

This means that you don’t need to manage the order of operations: you don’t have to identify someone before you send a track event, and so on.

Identify

The identify method represents a known person. You’ll typically send identify calls when a person makes themselves known to you—like when they log into your app, sign up for an account, or provide their email address.

With every identify call, you can pass traitsInformation that you know about a person, captured from identify events in Data Pipelines. Traits are analogous to attributes in Customer.io Journeys.—things that you know about a person, like their first name, their interests, etc.

{
  "type": "identify",
  "traits": {
    "first_name": "cool",
    "last_name": "person",
    "email": "cool.person@example.com",
    "plan": "premium"
  },
  "userId": "97980cfea0067",
  "created_at": "1679407797",
}

Group

A group call associates a person with a group—like an account, an online class, or recreational league.

When you send a group call, you’ll send a groupId. If the groupId doesn’t already exist, downstream destinations typically create it—like when someone creates a new account or starts a new recreational league. You can also set traits for the group. These are things you know about the group, like the account’s billing date, the name of the teacher for the class, or the name of the recreational league.

{
  "messageId": "4vl6zh",
  "timestamp": "2022-11-24T22:56:14.144Z",
  "type": "group",
  "traits": {
    "name": "Example Co, Inc.",
    "industry": "edtech",
    "plan": "enterprise"
  },
  "groupId": "example-company",
  "userId": "97980cfea0067"
}

Track event

The track method helps you represent your audience’s activities—the things that they do in your app or on your website.

Track calls can contain properties—extra data about on event beyond the event name. For example, if someone adds a product to their cart, you might keep a list of properties about the product they added to their cart. If someone starts an online course, you might capture additional information about the course. Properties are like traits for an event!

{
  "messageId": "i6yatl",
  "timestamp": "2022-11-24T22:48:17.593Z",
  "type": "track",
  "email": "cool.person@example.com",
  "properties": {
    "class_name": "Customer.io Basics",
    "class_code": "cio101",
    "start_date": 1679410730
  },
  "userId": "97980cfea0067",
  "event": "Course Enrolled"
}

Page

The page method represents the pages that people visit on your website. It helps you monitor the places that people do, and don’t, visit in your app or website. Page calls can help you follow up with people, to see if they’re still interested in a particular product, online class, and so on.

Our JavaScript source automatically captures page events on load. But you’ll need to invoke the page method manually if:

• You use our server-side libraries.
• You have a single-page app.
• You want to augment the call with special properties.

{
  "messageId": "efxqsi",
  "timestamp": "2022-11-24T22:55:59.498Z",
  "type": "page",
  "email": "cool.person@example.com",
  "properties": {
    "session_started": 1679410730,
    "url": "http://www.example.com"
  },
  "userId": "97980cfea0067",
  "name": "home"
}

Screen

The screen method is like the page method, but for your mobile app(s). Screen calls represent the screens that people use in your app, helping you better understand which parts of your app people use.

Like page and track calls, you can send properties about the screen that you might want to use in your downstream destinations.

{
  "messageId": "9zk6c",
  "timestamp": "2023-03-20T22:56:06.259Z",
  "type": "screen",
  "email": "cool.person@example.com",
  "properties": {
    "session_started": 1679410730
  },
  "userId": "97980cfea0067",
  "name": "home"
}

Alias

The alias method is only supported by Mixpanel’s original API. If you use Mixpanel, you can enable simplified identity merging to associate anonymous activity with an identified user without sending alias calls.

The alias method reconciles identifiers in systems that don’t automatically handle identity changes—like when a person graduates from an anonymous user to an identified user.

For example, a person has an anonymousId until you identify them by userId. Most destinations will automatically associate data representing an anonymous ID with the new user ID when you send an identify call, but some destinations may not! The alias call tells these destinations to represent the anonymousId (as the previousId) with the new userId.

{
  "previousId": "sqsv42VjV1e2d8ha2SHxM6",
  "userId": "97980cfea0067"
}

If you need to use the alias method, you’ll want to call it before you first identify someone by their userId. For example, using our JavaScript snippet, your flow might look something like this:

// the anonymous user does actions under an anonymous ID
analytics.track('92734232-2342423423-973945', 'Anonymous Event')

// the anonymous user signs up and is aliased to their new user ID
analytics.alias('92734232-2342423423-973945', '1234')

// the user is identified
analytics.identify('1234', { 'plan': 'Free' })

// the identified user does actions
analytics.track('1234', 'Identified Action')