Menu
 

Planning Your Integration: Guide to Mapping Data in Customer.io

Overview

Customer.io helps you react to and influence the behavior of your audience – with unique, personalized communication – at scale. A deliberate approach to mapping your product’s user and behavior data to Customer.io is critical for your success. As your product evolves, you’ll also want to consider how new features, or activities, are represented in Customer.io.

This guide outlines how data is stored within Customer.io to help you plan your integration.

Customer.io maps two specific types of data:

  • customer attributes: who your users are
  • events: what actions your users take in your app

Any data you send into Customer.io should serve your ability to segment your audience and personalize your messaging.

Attribute Data

A profile represents a person with a unique ID in your Customer.io account. Attributes describe the person or their current state. While Customer.io profiles correlate to your app’s database of users, not every database field needs to be reflected in Customer.io.

Do not send sensitive, personal information to Customer.io, such as bank account information, personal health details, credit card numbers, or other secure details. This type of information should not be used directly in email or other types of messages due to their sensitive nature.

Learn more about mapping customer attribute data

Event Data

Events map to actions your users take within your system (and occasionally to actions your service makes on a user’s behalf, such as recommendations).

Consider a streaming music service. Examples of events that your users perform include:

  • create_playlist
  • play
  • upgrade
  • skip_song
  • star_song
  • search

Track activities that users perform to derive value or enjoyment from your service. It’s less productive to track generic, non-descriptive activities like button clicks. Instead, send in user activity that maps to specific, meaningful behavioral goals. Use a simple naming convention that is readable, easily understandable by your team members, and corresponds to the activity being tracked.

Learn more about mapping event data


Describing Users with Customer Attributes

Profiles and their attributes describe your users. A profile represents a person—that is, anyone with a unique ID in your Customer.io account. Attributes describe the current state of a user.

Customer attributes persist but update when a user’s state changes (except for the one customer attribute that cannot change: the id). For instance, if you track the location of your users, you may update their location attribute as the user’s location changes. When an attribute’s value is updated, the previous value is replaced.

How are customer attributes used? Customer attributes are useful for segmenting your audience and personalizing your messages. They’re used as:

  • conditions for segmentation rules that determine who should receive a message. For instance, if you pass along current subscription plan (free / basic / premium) as an attribute, you can set up triggers to only send to customers who have subscribed to a particular plan (e.g. subscription_plan: premium).
  • variables that merge into the content of your messages. For instance, use attributes like first_name to personalize messages by displaying it in the subject or body using liquid.

Required Customer Attributes

You must send in at least the following 3 customer attributes:

  • id (unique and fixed)
  • created_at (timestamp)
  • At least 1 contact attribute—such as email (or phone_number if you’re using our Twilio Action or named_user if you’re using our Urban Airship Action).

1. id

The id attribute is the unique identifier for a user within your database/service. The id is NOT mutable (the only attribute that cannot be changed). Each id attribute must be unique within your Customer.io account.

Common data elements used for the id include: the SQL primary key from your database or the UUID. Avoid using email address or username as the id, as either value could be changed by your users.

2. created_at

The created_at value stores the Unix timestamp/Epoch time format when this user was created in your system. It’s critical that you send this timestamp value to Customer.io in the correct format to allow maximum segmentation options. If you aren’t familiar with the Epoch time format, please review our timestamp FAQ.

3. Contact attributes

email
In order to reach users via email, you’ll need to store their email address. Customer.io requires this attribute field name to be email. Note that Customer.io does not enforce uniqueness of the email attribute and does not automatically dedupe email addresses for you. This allows flexibility.

phone, mobile_phone
If you plan to use the Customer.io Twilio Action, a phone (or mobile_phone) attribute must be present. The recommended format of this attribute is E.164:

[+][country code][subscriber number including area code]


named_user
If you plan to use the Customer.io Urban Airship Push Action, the named_user customer attribute should contain the named user detail that’s stored in your Urban Airship account.

Other Important Attributes

You can add any attributes that describe your service’s users and their state within your service. Common important attributes include data such as first_name, last_name, city, or plan_level. Another good example is timezone; sending us this attribute will allow you to enable the Time Zone Match feature.

There’s no limit on the number of attributes stored per profile. However, each attribute value should be less than 10k of data. Learn more about how to use customer attributes within Customer.io.

Important Customer Attributes
Attribute Format Required?
id any text (not mutable) yes
created_at Unix time / Epoch time yes
email username@domain.com For email
mobile_phone* E.164 ([+][country code][subscriber number including area code] For SMS/Twilio Action
named_user* Must match named_user in Urban Airship For push/Urban Airship Action
first_name* text no
last_name text no
timezone text, in a supported format no
company text no

Describing Users’ Actions with Events

While customer attributes describe people, events are actions that users perform in your app or service. Events can also contain event attributes: data that describes details specific to an event.

For example, when a company that provides online training courses wants to track a class enrollment event, the following structure might apply:

  • Event Name: enrolled (the action taken by the user)
  • Event Attribute data: course_title, course_fee, course_instructor, course_url, course_img_url

The event attributes describe the enrollment event: the title of the course, the name of the instructor, and the URL to access the course.

Important to Know About Event Data

  • Event attribute data should not contain customer attribute data. The event will be tied to the user profile.
  • Event attributes are stored with the event and don’t change, since they describe the action your user performed.
  • Event attributes are separate from user customer attributes and do not cause changes to a user’s customer attributes.
  • Event and event attributes are accessible in
    • segmentation conditions for any type of campaign, and
    • only inside Event-Triggered Message content (not in Segment Triggered Campaign Messages or Newsletters).

Attribute Data vs. Event Data

Customer attributes are mutable (with the exception of the id attribute). As a user continues to interact with your service, you’ll pass new values to Customer.io via the identify call. Customer attributes answer “who” questions, like “Who is currently on the Enterprise plan?”.

Customer.io tracks all event data—and unlike an attribute, an event is never overwritten. Once a user performs an event, it will be a part of their recorded activity in Customer.io. Events answer “what happened?” questions like “has X event occurred within the last 7 days (or ever/never)?

Let’s review some characteristics of attribute vs. event data:

Customer Attributes

  • Customer attributes are changeable (except the id). When an attribute’s value is updated, the previous value is replaced.
  • Attributes reflect the current state or value for a person’s profile (e.g., name, location, email address).
  • Once an attribute value is changed, the previous value is no longer accessible.
  • When sending customer attributes, Customer.io will update only those attribute values that have changed or are new—and ignores attributes that already exist where the value has not changed.
  • Attribute names are case-sensitive.
  • Attribute field names, once added to your Customer.io instance, persist.
  • You can export your customer attribute attribute data (or specific segments) from the People search page.

Event Data

  • Event attributes are stored with the event and don’t change, since they describe the action your user performed.
  • Event attributes are separate from user customer attributes and do not cause changes to a user’s customer attributes.
  • Event and event attributes are only accessible in segmentation conditions and inside Event-Triggered Messages.

How Customer Attribute vs. Event Data is Used in Campaigns

Attribute and event data is used to segment your message recipients and personalize message contents:

  • as variables that merge into the content of your messages. For instance, use attributes like first_name to personalize messages by displaying it in the subject or body. Event attributes are only available to merge into event-triggered message content.
  • to define segmentation rules that target who should receive a message.

Segments can be created with any combination of 4 kinds of data: attribute, event, pageview, and email activity. Segments serve as triggers for segment-triggered campaigns. You can also use segments to narrow down who specifically should receive an event-triggered campaign. More on Segmentation.

Events serve as triggers for event-triggered campaigns. You can also use event data to create segments — based on the event name, the recency and frequency of its occurrence, and the event attribute data. Again, event and event attributes are only accessible in segmentation conditions and inside Event-Triggered Messages.

Recipient Targeting Conditions Message Customization
Newsletters - segments
- customer attributes
Customer attributes
Segment Triggered Campaigns - customer attributes
- event data
- email activity
- pageviews
customer attributes
Event Triggered Campaigns - event sent to Customer.io
- may further filter using segments
- customer attributes
- event attributes

Storing User Activity As Both Attribute and Event Data

Sometimes you’ll want to update a profile and track an event for the same user activity.

A common example is when a user upgrades from a free plan to a paid plan. When the upgrade happens, your integration could update the customer attribute value representing the user’s state (changing it from “free” to “paid”) and track an event for the purchased_plan user activity.

Tracking the purchased_plan upgrade event enables you to:

  • add [users who have upgraded within the last x days] as a segment condition
  • use the purchased_plan event to trigger campaigns

Meanwhile an identify call updates the customer attribute, enabling you to: * segment for all the users who have ever upgraded

Let’s look at how this might be structured. Marie has been testing out my_app and has decided to purchase an annual enterprise plan.

Marie’s Profile, before the Purchase Action has occurred:

id: 123,
first_name: Marie,
last_name: Smith,
email: marie@example.com,
current_plan: trial,
created_at: 1465994819 

Here’s what Marie’s profile would look like inside Customer.io:

When Marie performs the conversion action of upgrading to Enterprise, both the identify and track requests can be called. Identify updates the state of the profile, or in other words, the customer attribute. Track creates the transaction (event) that the user, Marie, has performed.

<script type="text/javascript">
	_cio.identify({
		id:'123', // *must be unique per customer*
	  	current_plan:'Enterprise'
	 });

	_cio.track("purchased_plan",
		{ plan_name: "Enterprise",
		plan_price: 1000.00,
		plan_months: 12 });
</script>

After these two requests, Marie’s profile will look like:

id: 123,
first_name: Marie,
last_name: Smith,
email: marie@example.com,
current_plan: Enterprise,
created_at: 1465994819 

Marie’s state for current_plan updates to “Enterprise”. Now, segments that include free plan users will no longer contain Marie. Her profile will enter any segments looking for the user state where current_plan: Enterprise. (Note, in the identify call, we only have to send the id and the changed/new attributes.)

Customer.io will also know that Marie has performed the event purchased_plan. Questions like: “who has ever performed the event purchased_plan?” will include Marie regardless of her current state, whatever attribute is in her profile. Even if Marie decides to later change to a different plan, this question can always be asked. She will always have performed this event at least once.


Data Formatting and Size Limits

Customer.io allows an unlimited number of customer attributes. The size of customer attribute data should be less than 1000 bytes per attribute.

Events can have an unlimited number of event attributes. The total payload of the event should be less than 10000 bytes.

For more specific details on size limits for our API calls you can check out our REST API Documentation

Using JSON

Customer.io customer attributes and event data can store complex data using JSON. This is useful for a case like a purchase event, where you’d include a JSON array with all of the items purchased:

{
	"name": "purchase",
	"data": {
		"items": [{
			"id": "1001",
			"type": "Shirt",
			"price": 10.99
		}, {
			"id": "1002",
			"type": "Jeans",
			"price": 20.00
		}, {
			"id": "1003",
			"type": "Sweater",
			"price": 70.99
		}, {
			"id": "1004",
			"type": "Socks",
			"price": 10.50
		}],
			"order_total": 112.48,
			"shipping": 9.99
		}
}

API Rate Limits

When sending data to Customer.io, API calls should be limited to 30 requests per second. This recommendation applies to both active data integrations, as well as historical backfill scripts.

Naming and formatting best practices:

  • Attribute names ARE case sensitive. Pick a consistent pattern for all of your attribute names (all lower case, proper case, etc).
  • Avoid using whitespace in attribute names. Use underscores to replace spaces, like first_name. Trim leading/trailing whitespace to avoid duplicate data.
  • We also recommend not using spaces in event names (e.g., your_event_name, not your event name).
  • Attributes can be a string, boolean or a number.
    • Use booleans, not strings for state:
      • Good: account_manager: true
      • Bad: account_manager: 'true'
    • Numbers should be passed as numbers, not strings:
      • Good: num_projects: 15
      • Bad: num_projects: '15'


Backfilling Data

Once you complete your integration, data will flow into Customer.io as users interact with your service. However, you may want to backfill your historical data in Customer.io, especially if you want to do any re-engagement or retention efforts.

Here are some guidelines:

Customer Profile Data:

When backfilling existing profiles, there are a few important considerations:

  • Attribute names must match those of your integration
  • The profile id cannot change once added to Customer.io

Events:

Important: Historical event data should include the timestamp when the event originally occurred. If the timestamp is not included, Customer.io will interpret the event as occurring at the time of import.

How to Backfill Historical Data

Go to our instructions on how to import historical data.


Using Data in Customer.io Campaigns

Attribute and event data is used to:

  • segment recipients (set rules for who will receive messages), and/or
  • personalize message contents.
Recipient Targeting Conditions Message Customization
Newsletters - segments
- customer attributes
Customer attributes
Segment Triggered Campaigns - customer attributes
- event data
- email/message activity
- pageviews
customer attributes
Event Triggered Campaigns - event sent to Customer.io
- may further filter using segments
- customer attributes
- event attributes

In Newsletter Campaigns

  • Access customer attributes to personalize and customize your message using Liquid.
  • Segment recipients based on customer attribute, event history, pageview, and email/message activity data.

In Segment Triggered Campaigns

  • Access customer attributes to personalize and customize your message using Liquid.
  • Segment recipients based on customer attribute, event history, pageview, and email/message activity data.

In Event Triggered Campaigns

  • Access attribute and event data (as events happen, going forward) to personalize and customize your message using Liquid.
  • Trigger messages based on an event. There are additional recipient filtering options, using segments based on customer attribute, event history, pageview, and email/message activity data.

Event Triggered Recommendation or Digest Campaigns

It’s possible to include dynamic, non-user data at send-time for recommendation and daily personalized digest messages. Event triggered campaigns can include the recommendation details needed. You do this by firing an event at Customer.io with the external data that you wish to include in a message to the user. (**Please limit scripted Event calls to 30 requests per second.)

Note: This is an example of an event that is triggered on behalf of your user by your service (rather than directly by the user). In most cases, you would trigger these events with a scheduled/cron job on your system. It is possible to use Customer.io’s webhook Action to initiate the job/service that queries your dynamic data and generates an event to Customer.io.