Customer.io destination

Customer.io is a popular marketing platform for sending targeted emails and push and SMS notifications to improve customer engagement and overall conversion rate.

Find the open source transformer code for this destination in the GitHub repository.

Getting started

RudderStack supports sending event data to Customer.io via the following connection modes:

In a web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the Customer.io native SDK from the https://assets.customer.io/ domain. Based on your website’s content security policy, you might need to allowlist this domain to load the Customer.io SDK successfully.

Once you have confirmed that the platform supports sending events to Customer.io, follow these steps:

1. From your RudderStack dashboard, add the source. From the list of destinations, select Customer.io.
2. Assign a name to the destination and click Continue.

Connection settings

The connection settings required to configure Customer.io as a destination in RudderStack are listed below:

• Site ID: Enter your Customer.io site ID.
• API Key: Enter your Customer.io API key.

For more information on obtaining your Customer.io site ID and API key, see FAQ.

• Event sent after setting device token: Enter the name of the event that is fired immediately after setting the device token.
• Data center: Choose your Customer.io data center from US or EU.

To send data to the EU data center using RudderStack Open Source, you should be using rudder-transformer v1.42.0 or later.

• Client-side Events Filtering: This setting lets you specify which events should be blocked or allowed to flow through to Customer.io. For more information on this setting, see the Client-side Events Filtering guide.

Consent settings

• OneTrust Cookie Categories: This setting lets you associate OneTrust cookie consent groups to Customer.io. For more information on this setting, see the OneTrust Consent Manager guide.
• Ketch Consent Purposes: This setting lets you associate Ketch consent purposes to Customer.io. For more information on this setting, see the Ketch Consent Manager guide.

Web SDK settings

• Use native SDK to send events: Turn on this setting to send the events through Customer.io’s native JavaScript SDK.
• Send page name in SDK mode: When sending events in web device mode using the native web SDK, RudderStack sends the page name to Customer.io if this setting is toggled on. Otherwise, Customer.io fetches the page name in the form of a URL.
• Enable in-app message support: Turn on this setting to send in-app messages to your website using the native web SDK. For more information on setting up in-app messages for your website, see the Customer.io documentation.

Identify

The identify call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.

userId is a mandatory field for Customer.io.

If it is not present, RudderStack:

• Uses email in cloud mode. If email is absent too, it drops the event.
• Drops the event in device mode.

RudderStack also sends the createdAt field as created_at to Customer.io to register the user signup time. If it is not present in the event, RudderStack automatically assigns the event’s timestamp to created_at before sending it to Customer.io.

A sample identify call is shown below:

rudderanalytics.identify("userId", {
  name: "Tintin",
  city: "Brussels",
  country: "Belgium",
  email: "tintin@herge.com"
});

You cannot use the same email to make consecutive identify calls with different userId.

To update user information, you can use cio_id - the Customer.io canonical identifier:

rudderanalytics.identify('<cio_id>', {
  email: '<updated_email>@example.com',
  id: '<updated_id>'
});

Unsubscribing users

You can pass unsubscribed: true in the identify call to unsubscribe a user in Customer.io:

rudderanalytics.identify("userId", {
  email: "tintin@herge.com",
  unsubscribed: true
});

Make sure the user ID and the email values match the Customer.io attributes. You can verify this by selecting that user in the People page in your Customer.io dashboard and clicking on Attributes.

Track

The track call lets you record the user actions along with their associated properties and send them to Customer.io.

A sample track call is shown below:

rudderanalytics.track("Track me", {
  category: "category",
  label: "label",
  value: "value",
});

For anonymous users, Customer.io does not permit an event name of size more than 100 Bytes. RudderStack automatically trims the event names in such a scenario.

For more information on the Track API event limits, see the Customer.io documentation.

Page

If you are using a native web SDK, RudderStack loads the Customer.io JavaScript snippet and captures the page views automatically. You can also send the page event to record the page views along with the other page-related information.

A sample page call is as shown below:

// "home" is the name of the page.
rudderanalytics.page("home", {
  path: "path",
  url: "url",
  title: "title",
  search: "search",
  referrer: "referrer",
});

Screen

The screen call is the mobile equivalent of the page call. It lets you record the screen views on your mobile app along with other relevant information about the screen.

If you have enabled screen views in your app implementation in the iOS or Android SDK, RudderStack registers the screen views as Viewed <screen_name> Screen under the user’s Activities tab.

RudderStack also forwards the event properties to Customer.io as received.

A sample screen call using RudderStack’s iOS SDK is shown below:

[[RudderClient sharedInstance] screen:@"Main"
            properties:@{@"prop_key" : @"prop_value"}];

RudderStack transforms the above event as Viewed Main Screen before sending it to Customer.io.

Group

The group call lets you link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits or properties associated with that group and send this information to Customer.io.

A sample group call is shown below:

rudderanalytics.group("group@49", {
  email: "help@rudderstack.com",
  action: "identify"
})

RudderStack automatically maps the following properties to the corresponding Customer.io properties:

Alias

The alias call lets you merge different identities of a known user. It is an advanced method that lets you change the tracked user’s ID explicitly.

The alias call is applicable only when both the user identities are present in Customer.io. The mapping can be ID to ID, email to email, email to ID, and ID to email.

A sample alias call is as shown below:

rudderanalytics.alias("userId", "previousId");

You can merge two accounts using email as well. RudderStack sets the primary email as userId and secondary email as previousId.

A sample alias call merging two accounts is shown:

rudderanalytics.alias("<primary.email>", "<secondary.email>");

Device token registration

RudderStack registers the device token to Customer.io for the following Application Lifecycle Events:

• Application Installed
• Application Opened

To use this feature, enable the trackApplicationLifecycleEvents feature in your mobile SDK implementation code. Also, you need to register your device token after initializing the SDK.

The following snippets demonstrate registering the device token for iOS and Android:

[[[RudderClient sharedInstance] getContext] putDeviceToken:[self getDeviceToken]];

RudderClient.putDeviceToken(getDeviceToken())

You can also specify the event name to be fired after setting the device token using the Event sent after setting device token dashboard setting.

Make sure you fire the event just after setting the device token in your app, so RudderStack can immediately register the device token on that event and not delay until the next lifecycle event.

The following snippets demonstrate how you can send a device_token_registered event after setting the device token in your app:

[[RSClient sharedInstance] track:@"device_token_registered"];

rudderClient!!.track("device_token_registered")

RudderStack also supports removing the device (identified by device_id) whenever you send a custom Application Uninstalled event.

FAQ

Where do I find the Customer.io API key and site ID?

To obtain the Customer.io API key and site ID, follow these steps:

1. Sign in to your Customer.io dashboard.
2. In the left panel, click Settings and select Account Settings.
3. Then, click API Credentials. You should find the site ID and API key for your project listed here.

Questions? Contact us by email or on Slack