Overview
The Segment integration enables Cordial as a Segment Destination, allowing you to send contact data from your Segment account to Cordial. Segment contact data is seamlessly integrated into the appropriate data collections within Cordial. You can then use Cordial's powerful data and messaging tools to build audiences, personalize message content, and trigger messages across multiple channels.
The types of Segment contact data Cordial currently ingests:
- Identify - Contact identification data unique to each contact.
- Group - Contact group associations, which are mapped to Cordial's lists.
- Track - Actions and action properties, also known as events, the contact has performed.
- Page - Contact's website page view records including page properties.
Enable the Segment Integration
You can enable the Segment integration by following the steps outlined below. Please complete the steps for activating the destination using the Cordial API key as well as enabling the integration via API call.
Activate the Destination Using Cordial API Key
- Create an API key in your Cordial account using the wildcard IP address of: 0.0.0.0/0. Learn more about creating API keys in Cordial.
- Log into your Segment account.
- Once logged in, paste this URL into your browser:
https://app.segment.com/WORKSPACE/destinations/catalog/cordial
Replace WORKSPACE with your Segment workspace name.
In the example below, WORKSPACE is acme (use all lower case).
- Paste your Cordial API key and activate the destination.
Enable the integration using an API call
In order to enable the integration in your Cordial account, you must make the following API call:
POST https://admin.cordial.io/api/integrations/segment
Method | URI Path |
---|---|
POST | https://admin.cordial.io/api/integrations/segment |
Enables the Segment integration using the appropriate JSON body. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
*name | string | The name of the integration to be enabled. "segment" should be used to enable the Segment integration. | segment |
*enabled | boolean | Enables or disables the integration. | true or false |
Supported Segment Functions
Cordial supports the identify
, track
, group
, and page
methods.
Data should post to: http://integrations.cordial.io/segment
Identify
Segment data is passed through to Cordial using this endpoint, where user in the URL parameters should be set to the Segment API key. The userId
in the dataset will be saved to a Cordial attribute designated to store the Segment identifier.
If the userId
passed is valid and known, the contact in Cordial will be updated with any mapped values set up in the integration. Based on the example configuration above, first_name
, userId
, address.state
, and email
will populate or replace the corresponding values in Cordial.
If the userId
passed is valid but does not correspond to a Cordial contact, the contact will be created and assigned any mapped values.
If the userId
passed is invalid, an error will be returned.
Group
Supported data parameters:
Segment key | Type | Cordial mapping |
---|---|---|
userId |
string | Primary or secondary contact identifier value such as cID, email or a custom identifier. |
groupId |
string | list ID |
If the userId
passed is valid and known, and the groupId
passed is valid and known, the contact will be added to the list in Cordial.
If the userId
passed is invalid, an error will be returned.
Note: Make sure that there is a minimum delay of 5 seconds between the identify call and the group call for new users.
Cordial lists: add or remove contacts
To make the process of adding and removing contacts from existing Cordial lists more efficient, the list names can be prefixed by grp_
and passed as traits of an identify call. Lists prefixed by grp_
accept the following values: 1 and 0 or true and false to indicate if a contract should be added or removed from the list.
The example below demonstrates how to add a new contact to existing Cordial WelcomeSeries and NewUsers lists. To remove a contact from your lists instead, simply use 0 or false values in place of 1 and true.
grp_
must match the names of your lists in Cordial. If the list names do not match, or the lists do not already exist in Cordial, the request will not be successful."traits": { "grp_WelcomeSeries": 1, "grp_NewUsers": true }
Track
Supported data parameters:
Segment key | Type | Cordial mapping |
---|---|---|
userId |
string | Primary or secondary contact identifier value such as cID, email or custom identifier. |
event |
string | Event name. |
properties |
object | Event properties (optional). |
If the userId
passed is valid and known, the event and its properties will be attributed to the contact in Cordial.
If the userId
passed is invalid, an error will be returned.
Page
Supported data parameters:
Segment key | Type | Cordial mapping |
---|---|---|
userId |
string | Primary or secondary contact identifier value such as cID, email or custom identifier. |
If the userId
passed is valid and known, a page view event will be attributed to the contact in Cordial.
If the userId
passed is invalid, an error will be returned.
Optional Advanced Configuration
PUT https://admin.cordial.io/api/integrations/segment
Method | URI Path |
---|---|
PUT | https://admin.cordial.io/api/integrations/segment |
Updates the Segment integration using the appropriate JSON body.
You can remap segment fields using the optional attributeMapping parameter. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
attributeMapping | Comma separated array of 2 name/value pairs. | Used to remap Segment fields to Cordial attribute keys. | true or false |
ignoreFields | Array of comma separated values. | Used to blacklist Segment fields from being passed to Cordial. | ["website"] |
Example JSON Request (with attributeMapping and ignoreFields)
The following will remap Segment fields to existing Cordial attribute keys and ignore the "website" field.
{ "name":"segment", "enabled":true, "attributeMapping":[ {"segmentField":"first_name","cordialKey":"fname"}, {"segmentField":"user_id","cordialKey":"extid"}, {"segmentField":"address.state","cordialKey":"state"}, {"segmentField":"email","cordialKey":"channels.email.address"} ], "ignoreFields":["website"] }
GET https://admin.cordial.io/api/integrations
Retrieve a JSON list of integrations you have set up with Cordial.
Comments
0 comments
Article is closed for comments.