Salesforce Marketing Cloud Destination
Getting Started
Segment’s Salesforce Marketing Cloud destination allows you to add contacts without using SOAP APIs.
A Note About ExactTarget
ExactTarget was recently acquired by Salesforce and renamed “Salesforce Marketing Cloud.” Throughout Segment, we’ll stick to the name Salesforce Marketing Cloud, but know that the names “Salesforce Marketing Cloud” and “ExactTarget” refer to the same product.
API Access
First, you’ll need to provide Segment access to your Salesforce Marketing Cloud account. We’ll do that by creating a Salesforce Marketing Cloud application.
- Log in to your Salesforce Marketing Cloud account.
- Click your name in the top-right corner of the screen and select “Administration”.
- Click the “Account” menu at the top-left corner of the page and select “Installed Packages”.
- If you want to use an existing package, click on that one or click “New” to create a new one. We recommend giving it a name like “Segment”.
- Click “Add Component”.
- Select “API Integration” and click “Next”.
- Select Server-to-Server
- Enable the following permissions that Segment will need to create contacts and then click “Save”.
You should now see a Summary page with a Components section. This section lists your Client ID and Client Secret settings.
Set Up Contact Data Storage
Segment will pass any traits you specify in an identify
call through to the Identify Data Extension you specify in the Segment UI. You’ll need to create this Data Extension manually in SMC’s Contact Builder UI. When creating a Data Extension in SMC, you can set up as many or as few traits as you would like, but a good starting point for your schema is to include Segment’s standard identify traits.
Set up your subdomain
Segment will use your unique Salesforce subdomain to make API calls to SFMC. Your subdomain is represented by a 28-character string starting with the letters “mc” in any of your base URIs. For example, in the base URI mc563885gzs27c5t9-63k636ttgm.rest.marketingcloudapis.com
, the subdomain is mc563885gzs27c5t9-63k636ttgm
.
If you do not set your subdomain, Segment will use the legacy V1 endpoint and your events can result in authentication errors.
Data Formatting
SMC is very strict about the format of your data, and will reject most calls that don’t fit an expected format. We format your data in a very consistent way to make setting up your destination as easy as possible.
To keep your data format consistent, predictable, and readable within SMC’s interface, we convert all your property keys to Title Case
before sending them to SMC. For example, the following example data:
{
"name": "firstLast",
"email": "first@example.com",
"createdAt": "1970-01-01T00:00:01.989Z"
}
or
{
"name": "first_last",
"email": "first@example.com",
"createdAt": "1970-01-01T00:00:01.989Z"
}
Will both be converted into:
{
"Name": "First Last",
"Email": "first@example.com",
"CreatedAt": "1970-01-01T00:00:01.989Z"
}
There are a few more things you should to know about sending data to SMC:
- Your Identify Data Extension must have a Primary Key called
Contact Key
(we’ll use theuserId
from your Segment events to populate this field) so we can link users to SMC’s built-in Contact Key property. (Yourtrack
events can use whichever Primary Key you specify.) - SMC does not allow colon characters (“:”) in the
Contact Key
field, so youruserId
fields will need to be scrubbed of these characters. - SMC doesn’t have a good way of handling nested objects, so we exclude them from data we send over.
- SMC accepts ISO-8601-formatted dates, and will reject any calls that include dates which don’t match that format. Be sure to send your dates in ISO format.
- SMC ignores casing differences (e.g.
created at
andCreated At
are interpreted the same way), so don’t worry about that. - SMC ignores keys that don’t exist in the target data extension, so if you send a trait
"nonexistent": "xyz"
with your data but there’s no matchingnonexistent
column on SMC’s end, that trait will simply be ignored.
Identify
When you call identify
, we’ll create a Salesforce Marketing Cloud Contact and upsert the user’s traits
into the Data Extension you specified in the Segment UI.
Note: You must include an email
trait or a userId
trait with all calls; we won’t forward any identify
calls that are missing both.
Track
When you call track
, we’ll fire an event using Salesforce Marketing Cloud’s eventing API. This flexible API allows you to upsert information related to a contact, the properties you pass in the track
event to Segment, into any Data Extension you choose.
First, you’ll need to set up event mappings in the Segment UI, which tells us which Segment events we should forward to Salesforce Marketing Cloud, and to which Data Extension we should send any given event. When you fire a mapped event through Segment, we’ll send those properties through to the Data Extension you specified. These data extensions upsert data so whatever you specify as the primary key, new data will be upserted off of the value of that key. For instance, if you use “Contact Key”, we’ll pass through your calls userId
as the value and that data extension will only have 1 row per userId
, updated with the latest values for each attribute.
We also let you choose other properties so that you can have 1 row per product, or 1 row per transaction based on a property on your call. If you are creating a data extension table for an Order Completed
event, you could use “Order Id” to grab the value from the orderId
property.
Similar to our conversions above, we will titlecase all properties so order_id
and orderId
both become “Order Id”.
Finally, we have a checkbox, UUID Primary Key
that will override whatever you have in the Primary Key Field and we will pass through a Primary Key with a key of ‘Uuid’ and the value being a UUID, the messageId
.
Multiple Primary Keys
If the data extension you are mapping to has more than one primary key, please enter each one seperated by a comma in the Primary Key Field. For example, if your primary keys were “Contact Key” and “Product Id”, you would just enter “Contact Key, Product Id” (without the quotations). The ordering is not important.
Features
Contextual Properties
Our destination with SFMC supports passing in many of the contextual properties that our SDK’s and libraries collect automatically as Data Extension attributes. Please reference our documentation for more information on contextual properties and the SDK’s/libraries that collect them.
In order to take advantage of this functionality, you will need to create attributes in your Data Extensions that adhere to specific naming conventions. The table below outlines the Segment contextual properties availble with this feature and the corresponding Data Extension attribute names they will map to.
app.name | App Name |
app.version | App Version |
app.build | App Build |
campaign.name | UTM Campaign |
campaign.source | UTM Source |
campaign.medium | UTM Medium |
campaign.term | UTM Term |
campaign.content | UTM Content |
locale | Locale |
userAgent | User Agent |
ip | IP Address |
device.adTrackingEnabled | Ad Tracking Enabled |
device.manufacturer | Device Manufacturer |
device.model | Device-model |
device.name | Device Name |
device.type | Device Type |
network.bluetooth | Bluetooth Enabled |
network.carrier | Network Carrier |
network.cellular | Cellular Enabled |
network.wifi | Wifi Enabled |
screen.density | Screen Density |
screen.height | Screen Height |
screen.width | Screen Width |
Personas
You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.
For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true
, and when this user no longer satisfies we will set that value to false
.
When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.
Supported Sources and Connection Modes
The first step is to make sure Salesforce Marketing Cloud supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.
Web | Mobile | Server | |
---|---|---|---|
📱 Device-mode | |||
☁️ Cloud-mode | ✅ | ✅ | ✅ |
To learn more about about Connection Modes and what dictates which we support, see here.
This destination requires a Device-based Connection Mode for Mobile data. Follow the steps above to ensure you have packaged the Salesforce Marketing Cloud SDK with Segment’s.
Settings
Segment lets you change these destination settings from your Segment dashboard without having to touch any code.
Client ID
Your Salesforce Marketing Cloud Client ID. For instructions on how to find your Client ID, check out our documentation.
Client Secret
Your Salesforce Marketing Cloud Client Secret. For instructions on how to find your Client Secret, check out our documentation.
Do Not Create or Update Contacts
By default, identify
events will create or update contacts in SFMC. If you would like to disable this functionality, set this option to true.
Conversion events
Use these fields to map your Segment event names to Salesforce Marketing Cloud Data Extensions. We’ll only send SMC the conversion events you specify.
Identify Data Extension External Key
Use this setting if you would like Segment identify
events to create or update Data Extensions in SFMC. The External Key of the Salesforce Marketing Cloud Data Extension to which you’d like to send Identify data. You can find this in the SFMC interface by navigating to Data & Analytics > Contact Builder > Data Extensions; the extension’s name will appear in the External Key column.
Subdomain
Your subdomain is represented by a 28-character string starting with the letters “mc” in any of your base URIs. For example, in the base URI mc563885gzs27c5t9-63k636ttgm.rest.marketingcloudapis.com
, the subdomain is mc563885gzs27c5t9-63k636ttgm
API Events
Trigger API Events in SFMC in response to Segment events.
This setting is a Beta release. You can read more about Beta features in Segment First Access and Beta Terms and Conditions. By using this feature, you agree to these terms.
Need support?
Questions? Problems? Need more info? Contact us, and we can help!