Segment + Iterable Integration (Sending Data from Segment to Iterable)

This guide describes how to use Segment to send data to Iterable. It discusses how to set up Segment, create and identify users, and track events.

# In this article

# Create a sandbox project in Iterable

When first configuring Segment to send data to Iterable, it's a good idea to test your configuration with an Iterable sandbox project (a test project that won't contain production data). Because Iterable separates user data by project, sandbox projects provide a convenient way to test new ideas and integrations without fear of making unintended changes to production data.

# Configuring your Segment account

Sending data from Segment to Iterable requires an Iterable API key. To create one:

1. In Iterable, create a server-side API key

   WARNINGS

   • Create a new API key for Segment—don't reuse an existing one. This makes it easier to delete the key at a later time without being concerned that it is being used in other places.
   • Never bundle a server-side API key in client-side code, whether JavaScript, mobile application code, or otherwise.

2. In Segment, navigate to the Sources tab. Open the source from which you'd like to send data to Iterable.

3. Click Add Destination.

4. From the list of possible destinations, choose Iterable.

5. Click Configure Iterable.

6. Enter the Iterable API key created above.

7. Enable the toggle at the top of the Iterable integration.

Segment will now send data from the selected source to Iterable.

# userId and email

The following sections describe how to use Segment's identify, track and page calls with Iterable. When making these calls, you must provide the fields each platform uses to identify users: Segment uses userId and Iterable uses email.

When you call Segment's identify, track or page methods, they pass the included data to Iterable's APIs. For Iterable to use this data to create a new user profile (when necessary), the request body must include an email address.

To create new Iterable users from Segment, it's best to call their identify method. When you provide both userId and email to an identify call, Iterable adds them both to the user's profile. Then, future calls to Segment's track and page methods can include one or both of these values, and Iterable updates the expected user profile.

However, it's best to include userId and email with every Segment call.

# Identifying users

Segment describes their identify method as follows:

identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them like their email, name, etc.

Here's an example call to Segment's identify method, using their Analytics.js (JavaScript) Source:

analytics.identify("2e69b96320754", {
  email: "user@example.com",
  favoriteColor: "red",
  address: {
    AddressLine1: "123 Main St",
    AddressLine2: "",
    City: "San Francisco",
    ZipOrPostcode: "94105",
    StateProvinceCounty: "CA",
    CountryId: "US"
  }
});

identify sends data to Iterable by calling its POST /api/users/update API. Iterable uses values included in the request to update the user's profile (except for email, which can only be updated by calling POST /api/users/updateEmail).

# Tracking events

Segment describes their track method as follows:

The track API call is how you record any actions your users perform, along with any properties that describe the action.

Here's an example call to Segment's track method, using their Analytics.js (JavaScript) Source:

analytics.track("User Signed Up", {
  email: "user@example.com",
  plan: "Annual",
  accountType: "Facebook",
  campaignId: 12345,
  templateId: 54321
});

track sends data to Iterable by calling its POST /api/events/track API. Iterable saves this event with an eventType of customEvent, an eventName matching the name provided in the track call, and extra fields saved in dataFields.

# Page

Segment describes their page method as follows:

The page call lets you record whenever a user sees a page of your website, along with any optional properties about the page. Calling page or screen in one of our sources is one of the first steps to getting started with Segment.

Here's an example call to Segment's page method, using their Analytics.js (JavaScript) Source:

analytics.page("Page Category", "Page Name", {
    email: "user@example.com"
});

Segment notes the following things about the page call:

In analytics.js a page call is included in the snippet by default just after analytics.load. We do that because you must call this method at least once per page load. However, you can choose to add an optional name or properties to the default call, or call it multiple times if you have a single-page application.

Iterable saves the event with an eventType of customEvent and an eventName of Viewed <CATEGORY_NAME> <PAGE_NAME> Page. Extra values included in the page call are saved on the event's dataFields object.

# Options for page events

On the Destinations > Iterable screen, Segment provides various options for page events:

• Map All Pages to Single Event Name

  Enabling this option causes Iterable to use the same event name for all page events: Loaded a Page (for web pages) and Loaded a Screen (for mobile app screens). We recommend turning this option on.

  An Iterable project can contain up to 8,000 unique custom event field names. If the same field name is used on various custom events, each with a different eventName, it counts multiple times against this limit. Mapping events to a single event name, and using properties and categories to capture specific information, cuts down on the number of field names in use.

• Options to specify which page events Segment should pass to Iterable:

  • Track All Pages

    Enabling this option causes Segment to create a page event in Iterable for every page call.

    NOTES

    • We recommend disabling this option.
    • The snippet provided by Segment for integrating their Analytics.js Source on your website includes a call to page. Each web page that uses that snippet will call page automatically. However, you can edit the snippet to disable this behavior or change the details provided to the call.

  • Track Categorized Pages

    Enabling this option causes Segment to create a page event in Iterable for each page call that includes a category.

  • Track Named Pages

    Enabling this option causes Segment to create a page event in Iterable for each page call that includes a category.

    IMPORTANT

    If Map All Pages to Single Event Name is not enabled, Segment creates an event for each enabled option on this screen. For example, if all options are enabled, the following call creates three events:

    analytics.page("PageCategory", "PageName", {
        "email": "user@example.com",
    });
    

# E-commerce

Iterable supports Segment's e-commerce events.

The following table describes how particular event names passed to Segment's track method map to Iterable API calls:

# Product Added, Product Removed

When tracking Product Added or Product Removed events, provide a products array that contains all the items that should be in the cart. Each item in this array must have an id, name, price and quantity. Iterable saves these as events with an eventType of customEvent and an eventName of updateCart.

This example updates the cart so that it contains two items:

analytics.track("Product Added", {
  email: "user@example.com",
  products: [
    {
      id: "7",
      name: "Yoga Mat",
      quantity: 1,
      price: 25.99
    },
    {
      id: "8",
      name: "Water Bottle",
      quantity: 2,
      price: 18.99
    }
  ]
});

# Order Completed

When tracking Order Completed events, provide:

• A products array (as described above)
• A total (integer or float)
• If you are tracking purchase and revenue data, you can include the campaignId and templateId, too.

Iterable saves these events with an eventType of purchase. For example:

analytics.track("Order Completed", {
  email: "user@example.com",
  products: [
    {
      id: "3",
      name: "Iterable Stickers",
      quantity: 4,
      price: 15
    },
    {
      id: "4",
      name: "Dog Treats",
      quantity: 1,
      price: 4.5
    }
  ],
  total: 64.5,
  campaignId: 12345
});

# Learn more

For more information about this integration, see Segment's support docs:

• Destinations Overview
• Iterable Destination
• The Protocols Tracking Plan