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

The identify events are used to add contacts to your Promoter account. Contacts must exist in Promoter before they can be surveyed.

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 event name entered in your campaign settings

  • If the track event name matches, we'll look at the userId in the data

    • If the userId matches an existing contact, a survey will be sent to that contact

    • If not, a survey will not be sent

Overall, track events are used to trigger surveys for your contacts.

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

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.

This can be set in your main settings in the upper right of the app.

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.

3. In the lower portion, click 'Configure' and select your campaign from the list given.

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

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

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

Did this answer your question?