9

Journeys Track API Source

Customer.io Journeys automatically acts as multiple sources of data in Data Pipelines: one source for Journeys Message Metrics and individual sources for each set of Journeys (Track) API credentials. This page is specifically about the Journeys Track API as a source. If you want to learn more about the metrics we forward from Journeys to Data Pipelines, see the Journeys Message Metrics page.

How it works

Journeys API sources automatically translate incoming calls to our Journeys Track API to our Data Pipelines format. This lets you use our Journeys Web SDK, our Journeys mobile SDKs, and our Track API—as a sourceA source is a website or server that you want to capture data from—it’s a source of data! without doing any extra integration work.

Our Track and Data Pipelines APIs share similar concepts, meaning that nothing’s lost in translation. Your Track identify calls become Data Pipelines identify calls, your Track page calls become Data Pipelines page calls, and so on.

Journeys API sources

We treat each set of Journeys API credentials as a separate source. This lets you route each set of credentials to specific destinations; you don’t have to forward all Journeys API calls to the same place(s).

Sources are organized by the Name you give to each set of credentials. You may have separate sets of credentials for your website, mobile app, testing, etc.

Mobile and Web SDK support

Our mobile and web SDKs are based on our Track APIs. But, if you use these sources and you’ve enabled the Track API as a source, then these SDKs are automatically set up as data sources.

You do not need to write extra calls with a separate API in your mobile app to take advantage of Data Pipelines. We’ll translate calls from our SDKs to the Data Pipelines format, so you can take advantage of your web and mobile data in destinations without any extra development overhead.

Enabling Track API/SDKs as a source

If you’re new to Customer.io, this integration is automatic: your Track API calls are automatically forwarded to Data Pipelines.

If you created your account before July 25th, 2023, you can tell Customer.io to forward your Track API calls to Data Pipelines with the Send People and Events from Journeys to Data Pipelines setting. This setting appears when you set up Data Pipelines or as a banner on the Data Pipelines Dashboard page.

Mapping Track API calls to Data Pipelines

The Journeys Track and Data Pipelines APIs are very similar. In many cases, they share the same “method” name—they both identify people, track events, and so on. This makes it easy to map calls from the Track API to Data Pipelines, but we discuss mappings in greater detail in the sections below.

The Journeys Track API doesn’t have a group method; rather, it handles group calls with a cio_relationships object in identify calls. We discuss this in greater detail in the Group calls section below, but this means that the Journeys Track API identify method with cio_relationships in the payload will produce two calls to Data Pipelines: one identify call and one group call.

Identifying people by email

In our Track API and associated Journeys SDKs, you can identify people by their email address alone. If you don’t provide an id value in the same call, we’ll map a person’s email directly to the userId in Data Pipelines.

But, while Journeys supports email as an identifier, your Data Pipelines destinations may not operate this way. If you identify the same person by an email address and later by id, you may end up with separate profiles in your destination representing the same person.

When you identify people by email address, we capture the email address as both context.journeys.identifiers.email and userId. If your integration identifies people by both email and ID, you may want to filter your destination actions where context.journeys.identifiers.email equals userId. This will prevent you from sending actions to people identified by email only.

Mapping Track v2 calls

The Track v1 API includes methods that generally map to Data Pipelines—they both have methods to identify, track, send page events, etc.

The Track v2 API uses the type and action keys to dictate an action. We use these keys to map actions to Data Pipelines. For example, if the v2 action is identify and type is person, that represents a Data Pipelines identify call. If the type is object, that represents a group call.

Identify

The Track v1 API includes an identify method that maps cleanly to the identify method in Data Pipelines. We map Track v2 calls to the Data Pipelines identify method when type is person and action is identify.

For a typical identify call, we map any keys that aren’t identifiers to traits. The lone exception is cio_relationships: we don’t pass this key in identify calls, but rather send a separate group call to set relationships. See Group calls below for more information.

_cio.identify('customer-id', {
  "email": "customer@example.com",
  "created_at": 1361205308,
  "first_name": "Bob",
  "plan": "basic"
})

{
  "type": "identify",
  "traits": {
    "created_at": 1361205308,
    "first_name": "Bob",
    "plan": "basic"
  },
  "userId": "97980cfea0067",
  "integrations": {
    "All": true,
  },
  "sentAt": "2023-08-24T14:15:22Z",
  "messageId": "01H95X6RDPC4P9DHPC0JX52YKE",
  "timestamp": "2023-08-24T14:15:22Z",
  "context": {
    "journeys": {
      "identifiers": {
        "id": "customer-id",
        "email": "customer@example.com"
      }
    }
  }
}

Track, page, and screen events

The Track v1 API includes a track method that maps cleanly to Data Pipelines track method. The Track v1 API doesn’t have methods for page and screen events. Rather, you’ll send standard track events with a type of page or screen. These map to the Data Pipelines page and screen methods respectively.

The Track v2 API works similarly. We map Track v2 calls to Data Pipelines track, page, and screen methods when the incoming type is person and the action is event, page, or screen respectively.

The event name maps directly to the event key in Data Pipelines. The data object in your event call maps to the properties key in Data Pipelines. For page calls, the event name is typically the URL of the page a person viewed. For screen calls, the event name is typically the name of the screen in your app.

curl --request POST \
  --url https://track.customer.io/api/v1/customers/customer-id/events \
  --header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
  --header 'content-type: application/json' \
  --data '{"name":"Started Game","data":{"game":"checkers","moves":0}}'

{
  "type": "track",
  "event": "Started Game",
  "properties": {
    "game": "checkers",
    "moves": 0
  },
  "userId": "customer-id",
  "integrations": {
    "All": true,
  },
  "sentAt": "2023-08-24T14:15:22Z",
  "messageId": "01H95X6RDPC4P9DHPC0JX52YKE",
  "timestamp": "2023-08-24T14:15:22Z",
  "context": {
    "journeys": {
      "identifiers": {
        "id": "customer-id",
      }
    }
  }
}

Semantic Events

A number of default actionsThe source event and data that triggers an API call to your destination. For example, an incoming identify event from your sources adds or updates a person in our Customer.io Journeys destination. in Data Pipelines are based on the event name in a track call. We call these semantic events. If you send events with names and structures corresponding to our semantic events, you’ll be able to use our default actions in destinations without any extra work.

For example, we typically use an event name called Application Installed to trigger the Add Device action in destinations.

{
  "name": "Application Installed",
  "data": {
    "version": 1.2.3,
    "build": "v8"
  }
}

{
  "userId": "abcde12345",
  "type": "track",
  "event": "Application Installed",
  "properties": {
    "version": "1.2.3", 
    "build": "v8"
  }
}

Group calls (cio_relationships)

Journeys calls groups objectsNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or colege course itinerary., and doesn’t have a specific endpoint to create groups. Instead, we base “group” calls on payloads of the Track API:

• Track v1 API: identify method containing cio_relationships.
• Track v2 API: Where type is object or whenever action is add_relationship.

Because the Journeys API revolves around people, the calls in which you set relationships will result in two calls to Data Pipelines.

While an identify call including cio_relationships will result in two Data Pipelines API calls (identify and group), we’ll just show the resulting group call in the example below.

curl --request PUT \
  --url https://track.customer.io/api/v1/customers/example-person-id \
  --header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
  --header 'content-type: application/json' \
  --data '{
    "email": "person@example.com",
    "cio_relationships": {
        "action": "add_relationships",
        "relationships": [
            {
                "identifiers": {
                    "object_type_id": "1",
                    "object_id": "acme"
                }
            }
        ]
    },
  }'

{
  "userId": "97980cfea0067",
  "groupId": "acme",
  "traits": {},
  "integrations": {},
  "messageId": "01H95X6RDPC4P9DHPC0JX52YKE",
  "timestamp": "2023-08-23T22:28:55.111Z,",
  "context": {
    "journeys": {
      "identifiers": {
        "id": "example-person-id"
      }
    }
  },
  "receivedAt": "2023-08-23T22:28:55.387Z,",
  "type": "group"
}

Context from the Track API

Data Pipelines payloads contain a context object that contains information about the source of the data. For data coming in through our Journeys Track API (including our mobile and web SDKs), the context contains a child object called journeys with identifiers from the original call. This can help you understand which calls were made from the Track API (or our associated libraries).

The context object contains a journeys.identifiers object with identity information for the person or group represented in the original call.

{
  "context": {
    "journeys": {
      "identifiers": {
        "object_type_id": "1",
        "object_id": "acme",
        "id": "42",
      }
    }
  }
}