Segment integration

Segment is a data platform that allows businesses to collect their marketing and customer data.

You can leverage Ortto’s powerful campaign, reporting, and dashboard features on your customer data from Segment. To do this, proceed through each of the following procedures to integrate Ortto with Segment, which imports your customer’s identify and associated track events from Segment into Ortto’s own CDP.

Segment prerequisites

This integration process assumes you have an operating Segment account and workspace.

Configure your Segment source

Ensure that your Segment source, whose customer data is to be handled by Ortto, has been configured in Segment.

Your Segment source should also be configured to push identify (customer contact) and associated track (customer action) event data, which Ortto handles. The Segment event field data (as JSON object responses) handled by Ortto includes the following for identify and track events, along with a single response for all unsupported events.

Identify event field data

• traits object - used to create or update people in Ortto.

Learn more about the structure of identify events from the example below.

Track event field data

• event member - used to create or update activities in Ortto.
• properties object - used to create or update an activity’s attributes in Ortto.
• traits object within a context object - used to create or update people in Ortto.
• userID or anonymousID members or both (within identify or track events) - used to link:
  • Segment traits object data for a person in Ortto, to
  • Segment event member (and its properties object) data for an activity (and its attributes) in Ortto.

Learn more about the structure of track events from the examples below.

Unsupported events

Ortto only supports receiving identify and track events from Segment.

If any unsupported event types from Segment are received, Ortto returns the server response code/status of 501 (not implemented).

Configure the AutopilotApp destination in Segment

Last, ensure that the AutopilotApp destination has been configured in Segment.

Connect from Ortto

If you initially followed the Configuring a new data source procedure, use this procedure to complete the integration between Ortto and your Segment data from the Ortto interface, by establishing the connection between the products.

1. Assuming you have clicked through Integrations > Segment > Get started (from the New data source page), on the Connect to Segment page, click Connect.
2. If you are not yet logged in to Segment, then Segment’s Log in to Segment page is displayed (replacing your Ortto one). Specify your relevant Email and Password credentials and click Log In.
3. On Segment’s Authorize AutopilotApp page, select the appropriate Segment Workspace and Source (containing your customer data) from the appropriate lists, and click Allow.
4. Back in Ortto on the Merge page, choose the appropriate merge option to determine how Ortto behaves when integrating any existing people data in Segment into Ortto.
   The Import and merge new records only, Import and overwrite any records that exist, and Import new records only are equivalent to the respective Append only, Overwrite existing, and Ignore merge strategies for people described in the developer documentation.
   By default, Ortto uses a person’s email address as the unique identifier for merging purposes, followed by their phone number (as a fallback).
   Ortto merges the data from traits object members within identify events (as well as within context objects of track events) in Segment, each of which represents a person whose unique identifier values match those of existing people defined in your Ortto CDP. Note that these unique identifier fields can be customized.
   At Merge key strategy, choose how you want to match people (contacts) using merge keys.
   Your chosen merge strategy (import and merge new, import and overwrite, or import new only) will be applied according to the merge key strategy you select. The merge key strategy refers to the unique identifiers set in your Ortto account when determining how to merge contacts.
   • Merge with any key match. This merge key strategy will merge Segment contacts with existing Ortto records based on any key match. This strategy will look at both your primary and fallback unique identifiers (e.g. email and phone number) to determine whether a match can be found.
   • Match only if previous merge key is empty. This merge key strategy will merge Segment contacts with existing Ortto records based on a primary unique identifier match (e.g. email) only — this strategy will not check your fallback unique identifier.
5. Click Next to open the Map page.
   On this page, Ortto attempts to match the traits members of your Segment identify events (or contained within context objects of track events), to fields defined in your Ortto CDP, since Segment automatically pushes identify and track events to Ortto (once the connection is established above). If matches are found between fields defined in your Ortto CDP and the names of members in the traits objects of Segment identify and/or track events, Ortto automatically applies the appropriate Ortto fields to your Segment source’s fields indicated in the Segment traits section of this page. If Ortto has not made a match under Segment traits or you wish to change a (mis-)match, you can search for other existing Ortto CDP fields and/or add new fields to your Ortto CDP to map to your Segment traits on this page.
6. Click Next to open the Activities page.
   On this page, Ortto automatically reads your Segment track events' event values and properties members, allowing you to re-create this data respectively as activities and attributes in your Ortto account. (Like identify events, Segment also automatically pushes track events to Ortto, once the connection is established above).
   These read activities and attributes are available for you to explicitly add to Ortto (which makes them available from the Activities page).
   To add these activities and their attributes to Ortto:
   • Click Add activity > Select activity (dialog) from this page.
   • Select the generated Segment activity and click Select.
   • In the Add activity dialog, click the attribute to expand it and edit the attribute’s name in Segment or Ortto, as well as its type. You can also choose to populate an existing People field of the CDP with this attribute from the Map value to CDP list, or create a new field for it.

Searching existing Ortto CDP fields

If the list of Ortto CDP fields on the Map page is extensive, you can filter this list itself by typing one or more consecutive letters into the Search box, and any of these fields whose names do not match these letters are dynamically excluded from the list as you type.

You can then select and/or clear the remaining Ortto CDP fields on this list.

Clearing the Search box, or clicking X restores all Ortto CDP fields to the list.

Adding a new Ortto CDP field

If your Ortto account’s existing CDP fields are not suitable for one or more fields of data from your Segment source’s identify events, you can create a new Ortto CDP field on the Map page to map to your identify events' traits fields.

To do so:

1. Click Add a new field.
2. In the Create field dialog, specify the Field name and Field type for your new Ortto CDP field.
3. Click OK and the new Ortto CDP field appears in the Ortto fields section list in alphabetical order. You can now drag this field across to the appropriate Segment identify traits field in the Unique identifiers section of the page.

Segment identify event example

The following JSON object is an example of all field and object data that Ortto can recognize from a Segment identify event. Fields defined in the traits object may require the additional configuration of custom fields in Ortto.

Example Segment identify event:

json
 
{
  "type": "identify",
  "userId": "lana.romeijn.myonlinestore-studio", 
  "anonymousId": "507f191e810c19729de860ea", 
  "traits": { 
    "firstName": "Lana",
    "lastName": "Romeijn",
    "email": "lana.romeijn@example.org",
    "street": "6th St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "USA"
  }
}

The userId and anonymousId member values are used to link identify event with track event data in Ortto, thereby allowing Ortto to associate this person’s data in Ortto (being added or updated through this example identify event) with their activity and/or attributes (being added or updated through the example simple track event below). Only one of these member values is required for Ortto to establish this association.

Each member of the traits object must be siblings. Nesting objects within a traits object is not supported by Ortto.

Segment track event examples

The following JSON objects are examples of all field and object data that Ortto can recognize from Segment track events. The following shows a simple track event, although for track events with a traits object, fields defined in the traits object may require the additional configuration of custom fields in Ortto.

Simple track event

Example simple track event:

json
 
{
  "type": "track",
  "userId": "lana.romeijn.myonlinestore-studio",
  "anonymousId": "507f191e810c19729de860ea",
  "event": "Sign-in button clicked",
  "properties": {
    "action": "sign-in-button-clicked",
    "count": 3
  }
}

The userId and anonymousId member values are used to link identify event with track event data in Ortto, thereby allowing Ortto to associate this person’s data in Ortto (being added or updated through this example identify event) with their activity and/or attributes (being added or updated through the example identify event above). Only one of these member values is required for Ortto to establish this association.

Each member of the properties object must be siblings. Nesting objects within a properties object is not supported by Ortto.

Track event with traits data

Example track event with traits data:

json
 
{
  "type": "track",
  "userId": "lana.romeijn.myonlinestore-studio",
  "context" : {
    "traits": {
      "firstName": "Lana",
      "lastName": "Romeijn",
      "email": "lana.romeijn@example.org",
      "street": "6th St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94103",
      "country": "USA"
    }
  },
  "event": "Sign-in button clicked",
  "properties": {
    "action": "sign-in-button-clicked",
    "count": 3
  }
}

The userId value is not required since this track event contains a context object with the traits data of an associated identify event.

The context object containing the traits data of an associated identify event.

As for identify events, each member of the traits object must be siblings. Nesting objects within a traits object is not supported by Ortto.

Each member of the properties object must be siblings; nesting objects is not supported by Ortto.

Supported date formats from Segment

Ortto supports date formats from Segment that comply with the RFC3339 and ISO 8601 standards, with dates in the format YYYY-MM-DD. This data is typically captured in the member data of properties in track events or traits in identify or track events.

The following examples show date and time, as well as date formats in ISO 8601 standard:

• 2021-01-18T15:04:05+10:00
• 2021-01-21

Alternatively, you can send dates in the format set in your Ortto instance, at Settings > General > Date and time. For example, the format set in your Ortto account could be: MM-DD-YYYY HH:mm.

Rate limits

The number of events that Ortto consumes from Segment is rate-limited.

Ortto supports the following number of events from Segment, after which rate limits are imposed:

• Identify events — 10 x no. of included contacts for your plan (+ additional contacts purchased), per 24-hour period. Therefore, the following Ortto plans support up to the following no. of identify events (assuming no additional contacts purchased):
  • Ortto plan with 5,000 contacts: 10 x 5,000 = 50,000 identify events in a 24-hour period.
  • Ortto plan with 20,000 contacts: 10 x 20,000 = 200,000 identify events in a 24-hour period.
• Track events — 5 x no. of included contacts for your plan (+ additional contacts purchased) x no. of activities tracked from Segment, per 24-hour period. Therefore, the following Ortto plans support up to the following no. of track events (assuming no additional contacts purchased):
  • Ortto plan with 5,000 contacts: 5 x 5,000 x 5 = 250,000 track events in a 24-hour period.
  • Ortto plan with 20,000 contacts: 5 x 20,000 x 10 = 2,000,000 track events in a 24-hour period.

Managing connected data sources

Once you have connected at least one data source to your Ortto account, you can manage the configured data sources through the Data sources page.

Add Segment to another Ortto account

If required, you can connect a single Segment account to more than one Ortto account (instance).