Integrating with Segment

Integrating Segment with Ortto is only available to Ortto customers on the Professional or higher plans.

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.

      These data members are not required when a traits object’s data is captured within a track event’s context object.

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.

An Ortto (Autopilot) source is not available for Segment. The AutopilotApp destination and the Segment data source integration you configure in Ortto, only allows data to flow from Segment to your Ortto account.
The Autopilot Source available for Segment is for Ortto’s older product, Autopilot Journeys.

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.

    At this point, since your customer and customer action data in Segment is bespoke, Ortto does not list any Activities on this page.
  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.
    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.

  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.

    • If you have not yet finished configuring your Segment source (and its identify and track events are not yet being pushed by Segment), then the Waiting for Segment to send us an Identify event message may appear in the middle of the Map page instead. If this is the case, you can close this page and once your Segment account’s source pushes event data to Ortto, you are sent an email notification informing you of this event.
      Alternatively, you could also send an event from Segment to the Ortto destination manually, sending a modified version of the identify and track (with traits data) example events below.

    • Ensure that the data types between your Segment source’s traits members and their matched Ortto CDP fields, are also compatible. If there is a mismatch in data types between a Segment traits member and Ortto field on this page, and that member’s data value from Segment cannot be converted, then that data value is ignored by Ortto.

  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:

    1. Click Add activity  Select activity (dialog) from this page.

    2. Select the generated Segment activity and click Select.

    3. 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.

    • On the Add activity dialog, you can click Enter manually to add an activity and its attributes for a track event you intend to add future support for in Segment.

    • The following Ortto plans support up to the following number of activities from Segment:

      • Ortto Professional plan - 5 activities from Segment track events, and

      • Ortto Business plan - 10 activities from Segment track events.

      You can purchase additional activities via the Activities + add-on, where each additional activity to track a Segment track event costs 1 x Activities + add-on.

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
{
  "type": "identify",
  "userId": "lana.romeijn.myonlinestore-studio", (1)
  "anonymousId": "507f191e810c19729de860ea", (1)
  "traits": { (2)
    "firstName": "Lana",
    "lastName": "Romeijn",
    "email": "lana.romeijn@example.org",
    "street": "6th St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "USA"
  }
}
1 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.
2 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
{
  "type": "track",
  "userId": "lana.romeijn.myonlinestore-studio", (1)
  "anonymousId": "507f191e810c19729de860ea", (1)
  "event": "Sign-in button clicked",
  "properties": { (2)
    "action": "sign-in-button-clicked",
    "count": 3
  }
}
1 The userId and anonymousId member values are used to link track event with identify event data in Ortto, thereby allowing Ortto to associate this activity and its attribute data in Ortto (being added or updated through this example track event) with the person (being added or updated through the example identify event above) who conducted it. Only one of these member values is required for Ortto to establish this association.
2 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
{
  "type": "track",
  "userId": "lana.romeijn.myonlinestore-studio", (1)
  "context" : { (2)
    "traits": { (3)
      "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": { (4)
    "action": "sign-in-button-clicked",
    "count": 3
  }
}
1 The userId value is not required since this track event contains a context object with the traits data of an associated identify event.
2 The context object containing the traits data of an associated identify event.
3 As for identify events, each member of the traits object must be siblings. Nesting objects within a traits object is not supported by Ortto.
4 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 standard, 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 that Ortto supports from Segment:

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

  • 2021-01-21

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 Professional plan - 10 x 5,000 = 50,000 identify events in a 24-hour period.

    • Ortto Business plan - 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 Professional plan - 5 x 5,000 x 5 = 250,000 track events in a 24-hour period.

    • Ortto Business plan - 5 x 20,000 x 10 = 2,000,000 track events in a 24-hour period.