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.
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.
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.
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
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.
Visit your Promoter account and choose to create a new campaign.
- Choose for your campaign to be a Segment campaign.
- Select/Edit an email template to your liking.
- Choose a contact list for the campaign.
- This contact list doesn't need to have any contacts previously added. As you survey contacts, this is where they'll be added and stored. You can click to create a new list and name it 'Segment List' if you'd like.
- Distribution set to 'Instant'.
- Reminder duration of your choosing.
- Forwarding email if you'd like.
- Delivery delay of X days.
- The 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.
- With no delivery delay (0 days), a survey will be sent immediately upon being triggered.
- Set a survey throttle.
- A throttle is recommended if the Segment 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.
When your campaign settings are ready, click Activate Campaign. Activating the campaign simply gets the campaign ready to receive Segment events.
To connect your Segment account to Promoter, all you will need is:
- A Segment campaign created and ready in Promoter
- Your Promoter API key.
When you have a Segment campaign ready and activated:
- Login to your Segment account and find Promoter on the integrations page.
- Insert your Promoter API key.
- Save and you're done!
Once a valid track event comes through matching the one you entered on the campaign settings, your campaign will update from Ready to an Active status.
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.