Customer.io Destination


Customer.io lets you send automated email, push, SMS, letters, and webhooks based on your customer’s activities in your app or product. It makes conversion tracking, optimization and remarketing easier than ever. The analytics.js Customer.io Destination is open-source. You can browse the code on GitHub.

This document was last updated on January 26, 2018. If you notice any gaps, out-dated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Use Cases

Getting Started

The first step is to make sure Customer.io supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

Web Mobile Server
📱 Device-mode
☁️ Cloud-mode
  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “Customer.io” within the Destinations Catalog and confirm the Source you’d like to connect to.
  3. Drop in your Customer.io API Key and Site ID, which you can retrieve from Settings > API Credentials in Customer.io, into the Segment UI Settings.
  4. Alternatively, you can automatically sync your Customer.io connection settings to your desired Segment source by following the flow within the Customer.io Setup Guide.

customerio setup guide screenshot

Page

If you haven’t had a chance to review our spec, please take a look to understand what the Page method does. An example call would look like:

analytics.page();

Page events will be sent to Customer.io as a Page View event where name and properties are optional. In the Customer.io “Activity View”, the event will have “Activity Type” set to “Page View” and “Activity Name” set to the page name. If no page name has been specified, “Activity Name” will default to the page URL.

Screen

If you haven’t had a chance to review our spec, please take a look to understand what the Screen method does. An example call would look like:

[[SEGAnalytics sharedAnalytics] screen:@"Home"];

Screen events will be sent to Customer.io as a custom event. In the Customer.io “Activity View”, “Activity Type” will be event and “Activity Value” will be set to Viewed {screen name} Screen. For the earlier example the “Activity Value” will be Viewed Home Screen. If no screen name has been specifed then “Activity Value” will be Viewed Undefined Screen.

Identify

If you haven’t had a chance to review our spec, please take a look to understand what the Identify method does. An example call would look like:

analytics.identify('userId123', {
  email: 'john.doe@segment.com'
});

An email address is not required by Customer.io. It is only needed for people you intend to send email messages to (as opposed to SMS or push notifications). If you want an email to appear in the Customer.io “People View”, you must provide an email as a trait labeled email.

When you identify a new user, the user will be subscribed to Customer.io. If the user is already subscribed, the user attributes will be updated according to the traits provided.

To unsubscribe a user, simply pass in user_id and unsubscribed (with a value of true) in an identify call. Be sure the user_id and email match the values in Customer.io, which you can find in the “Overview” section under the “Attributes” column within an individual user’s view in the Customer.io UI. Here is an example of how to unsubscribe a user:

analytics.identify('userId123', {
    email: 'john.doe@segment.com',
    unsubscribed: true
  }
)

Track

If you haven’t had a chance to review our spec, please take a look to understand what the Track method does. An example call would look like:

analytics.track('Clicked Button');

Track events will be sent to Customer.io as custom events. In the Customer.io “Activity View”, “Activity Type” will be set to event and “Activity Name” will be set to the event name.

Device Token Set up

Before you can send the Application Installed, Application Uninstalled, or Application Opened events to Segment. device.token must be set.

For that, you need to make the following calls:

  • For Android, you need to make a call to putDeviceToken when Segment client is initialized.
    • Read more here for adding tokens for Android devices
  • For iOS, you need to make a call to segment.registeredForRemoteNotifications when you receive the didRegisterForRemoteNotificationsWithDeviceToken event.
    • Read more here for adding tokens for iOS devices

Application Installed

Application Installed events will add or update a device in the person’s Customer.io profile using this API endpoint. Please note, you must pass a device token in your event payload via a context.device.token property. See more on Contextual properties here.

{
"action": "track",
"userId": "019mr8mf4r",
"event": "Application Installed",
"properties": {
  "version": "1.2.3",
  "build": 1234
},
"context": {
  "device": {
    "token": "ff15bc0c20c4aa6cd50854ff165fd265c838e5405bfeb9571066395b8c9da449",
    "type": "ios"
  }
}
}

## Application Opened Application Opened events will add or update a device device in the person’s Customer.io profile using the same endpoint as above. If a device already exists, Customer.io will update its last_used_at timestamp. Again, please ensure you pass a device token in your event payload via a context.device.token property. See more on Contextual properties here.

{
"action": "track",
"userId": "019mr8mf4r",
"event": "Application Opened",
"properties": {
  "version": "1.2.3",
  "build": 1234
},
"context": {
  "device": {
    "token": "ff15bc0c20c4aa6cd50854ff165fd265c838e5405bfeb9571066395b8c9da449",
    "type": "ios"
  }
}
}

## Application Uninstalled Application Uninstalled events will remove the device from the person’s Customer.io profile using this API endpoint. Please note, you must pass a device token in your event payload via a context.device.token property. See more on Contextual properties here.

{
"action": "track",
"userId": "019mr8mf4r",
"event": "Application Uninstalled",
"properties": {
  "version": "1.2.3",
  "build": 1234
},
"context": {
  "device": {
    "token": "ff15bc0c20c4aa6cd50854ff165fd265c838e5405bfeb9571066395b8c9da449",
    "type": "ios"
  }
}
}

Sending Data from Customer.io

Customer.io supports sending email events to other tools on the Segment platform. These events will be sent as track calls to the other destinations you’ve turned on.

To enable this feature, go to the Account Settings in Customer.io and add your Segment write key:

Send email events from Customer.io

Best Practices

Rate Limits

Customer.io has limits on the data collected by their API. To ensure your events arrive in Customer.io, please ensure that you are respecting the limits placed on the Customer.io API. If you are using our HTTP API to send a batch of events to Customer.io at once, make sure you throttle the import to 100-200 requests per second.

Troubleshooting

No Events in Customer.io from the Browser

Remember that before we can send events to Customer.io from client-side Javascript the current user must be identified with their userId. The user’s email address can only be used to identify them if that is the id on record for them in Customer.io.

Page events not being associated with user

Page events will only be associated to a user if the user has been previously identified in Customer.io. If you identify a user after making Page calls, the previous page events will not be associated to the user in Customer.io.

Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Settings

Segment lets you change these destination settings from your Segment dashboard without having to touch any code.

API Key

You can find your API Key on the Customer.io Integration page. It should be 20 or 64 characters long, and look something like this: 91837a6c9e8b49d0ef71. An API Key is required if you’re using our server-side or mobile libraries.

Convert To Unix Time

If true, timestamps are converted to Unix Time.

Site ID

You can find your Site ID on the Customer.io Integration page.

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account