Learn below how to set up your campaign for Segment. With this integration, you'll be able to trigger a survey when a specific track event is triggered in Segment.

Integration Overview

Here's a quick overview before we get started of how the Segment identify and track events function when they're sent to Promoter. You can also view our docs on the Segment website.

Segment Identify Events

Whenever you send an identify event to Segment it will either:

  • create a contact in Promoter (if that contact doesn't already exist)
  • update a contact in Promoter (if that contact already does exist).

All of the traits associated with the Identify event will get added as contact attributes in Promoter. If a userId is not provided in the identify event, we will not store the contact. The userId is how we connect the Track event to the correct contact that was stored.

If the email address provided with a Segment Identify event already exists within Promoter, we will not create a new contact record. Instead, we will merge the existing contact (including contact attributes, surveys, and feedback data) into the new Segment contact record.

If the Segment user id provided with a Segment Identify event is already associated with a contact in Promoter, but under a different email address, we will also merge the existing contact (including contact attributes, surveys, and feedback data) into the Segment contact for the given Segment user id.

Segment Track Events

Whenever you send a track event to Segment:

  • Promoter will look up the track event name and see if it matches the specified event entered in your campaign settings
  • If the track event name matches, we'll look to see if the userId was previously identified
    • If the userId was previously identified, a survey will be sent to that contact
    • If not previously identified, a survey will not be sent

Server-side Race Condition

Because our server-side libraries batch calls by default, it may happen that an identify call intended to create a user arrives simultaneously with a track event associated with this user. If the track event is processed before the user is created, an error will result and the event will not be recorded.

Adding a Flush method immediately following the identify, and before any subsequent track event, will help the identify call reach Promoter first to create the user. Generally, this prevents the race condition, but an additional timeout can be used if necessary.

Setting up your Segment campaign

Set a Survey Throttle!

A survey throttle is recommended if the Segment track event you choose to trigger surveys on can be triggered by a contact multiple times in your app within a short time-frame. The throttle ensures your contacts are not over-surveyed.

Learn more about the Survey Throttle

  1. Visit your Promoter account and create a campaign. You'll need to send at least one survey manually to activate a campaign.

  2. Visit the Integrations section of your account and click 'Configure' for Segment.

  1. In the lower portion, click 'Configure' and select your campaign from the list given.
  1. Enter the Track event name to trigger surveys on. If further filtering is needed, you can specify a specific property and value within the Track event on which surveys should be triggered.
  1. Several send options will be available to choose from.

Delivery Delay - Surveys are scheduled and sent instantly to our email client when they're triggered, but they will not be delivered to your contact until X amount of days later. This is optional of course, but can help if you're trying to set up a transactional workflow. This is a perfect setting for when users sign up for your service or purchase a product, and you don't want them to receive a survey until 7-30 days later after their trial period ends or they've had time to receive their product.

Time of send- Choose if you want your surveys scheduled to go out at the time the survey was triggered (Send Immediately) or at a specific time (Schedule to send later)

Choose a delivery delay of 0 and "send immediately" to have surveys sent immediately upon being triggered.

Reminders - We'll make sure anyone who hasn't responded to your survey in 3/5/7 days since they received their initial survey, will receive a reminder survey. Reminder surveys will only be sent once.

Recurring surveys - Set if you'd like your contacts to receive more than one survey after their initial survey.

  1. Click 'Save' when done.

Setup in Segment

To connect your Segment account to Promoter, all you will need is:

  • A campaign created in Promoter
  • A segment connection enabled for that campaign in the Segment integration
  • Your Promoter API key

When you're ready to connect Segment:

  1. Login to your Segment account and find Promoter on the integrations page.
  2. Insert your Promoter API key.
  3. Save and you're done!

Modify your Segment tracking plan

The Promoter.io Segment integration will only process 50,000 Segment requests per day. Due to this, we recommend curating your Segment tracking schema so you're not sending Promoter unnecessary track events that could bring you up to that throttled limit. This is also best practice as this makes sure that for any app you use Segment with, you're only sending the information you want them to have, and not everything possible.

In your Segment account, navigate to Sources > (Project) > Schema > Tracks

Next, click on a track event name in the list. This will take you to the settings for that Track event. You'll then click on Filters to see which apps are being sent this track event.

Turn ON Promoter.io for the Track event you would like surveys sent on and that you've specified in your campaign settings.

Turn OFF Promoter.io for all the Track events you would NOT like to send to Promoter.io. You would need to do this for all the other track events that you're not using to trigger surveys on.