Introduction
This document provides a step-by-step approach to pushing client data from the Salesforce Data Management Platform to Activation/Execution Partners such as Demand Side Platforms (DSP), Supply Side Platforms (SSP), Ad Networks, and Exchanges. For simplicity the rest of the document refers to all Activation/Execution Partners as Data Receivers.
Salesforce Audience Studio supports data transfer via the Server-to-Server method. This method involves user matching and subsequent pushing of data in batch. In addition to supporting device types that require user matching, hashed email addresses, OTT devices, and other customer first party IDs are supported. The server-to-server method is described in greater detail below.
When a mutual customer establishes a connection between Audience Studio and an Activation Partner, that customer must explicitly choose to send readable segment names instead of segment IDs.
Server-to-Server Integration
Server-to-Server integration involves the following steps in addition to an initial integration configuration where you will have the opportunity to define the types of devices supported, such as cookies, mobile ids, hashed email address OTT devices, and the specific supported hash methods and OTT device types.
Step 1: User Matching
Partner to provide Audience Studio with Partner user match pixel.
Step 2: Data Location
Audience Studio will grant access to the Audience Studio Amazon credential generation tool, giving the Data Receiver access to user audience segment map via an Amazon S3 folder in Audience Studio's Amazon account.
The data is specified in the following folder:
s3://<partner_home_directory>/<date>/<client_name>/<account_name>/<files>Where:<partner_home_directory>: directory provided to the partner by Audience Studio <date>: date which is of the format YYYY-MM-DD (2019-09-01). The date corresponds to the date that the data was uploaded
<client_name>: Audience Studio client for which data is provided<account_name>: Audience Studio Client account name for which data is provided<files>: One or more files with data. The content of these files are described below in Step 4
Step 3: File Details
Audience Studio will deliver one or more .gz compressed data files each day to partner specific S3 bucket containing the daily segment map information. The delivery location will remain constant, though the number and naming of files may vary due to back end processing.
Audience Studio will send file uploads each day. Once the Data Receiver specifies the type of match keys accepted (cookie, mobile ID), Audience Studio will configure the jobs to push the accepted types. Files will be separated based on Match Key, and the file name will be prepended accordingly.
A <YYYY-MM-DD>.COMPLETE file will be available when all files per day have been generated. This indicates files are ready for import into your platform. If the Data Receiver does not see any data files on Amazon S3, then either there were no segments to be pushed that day, or the push timed out, in which case Audience Studio will be notified by our monitoring systems and will work to fix the issue. The Data Receiver is responsible for picking up the files from S3 for ingestion. Audience Studio ensures User Audience files stay in the folder for at least 7 days.
Following is an example of a daily push of cookies, mobile IDs, hashed email addresses, and OTT devices into a Data Receiver’s folder. HEM hash types and OTT device types are delivered via separate files based on the methods and types configured for your integration. You must request to configure supported device types before that device type data will be delivered to your S3 location.
2019-09-01.COMPLETE
AAID_<account_name>_segments_map_2019-09-01.csv-r-00000.gz
AAID_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
AAID_<account_name>_segments_map_2019-09-01.csv-r-00002.gz
COOKIE_<account_name>_segments_map_2019-09-01.csv-r-00000.gz
COOKIE_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
COOKIE_<account_name>_segments_map_2019-09-01.csv-r-00002.gz
IDFA_<account_name>_segments_map_2019-09-01.csv-r-00000.gz
IDFA_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
IDFA_<account_name>_segments_map_2019-09-01.csv-r-00002.gz
HEM_SHA256_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
HEM_SHA1_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
HEM_MD5_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
OTT_RIDA_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
OTT_AAID_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
OTT_IDFA_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
OTT_AFAI_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
OTT_MSAI_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
Step 4: File Delivery and File Format
There are four options for file delivery, and corresponding file formats. With all options, Audience Studio provides the Data Receiver User Audience Segment Map files in CSV format. The file uses a Caret (^) as the delimiter and has 2 columns:
User ID^SegmentsWhere:
the User ID is either the matched User ID via the cookie matching process described above (KUID will be sent) or the IDFA and or AAID in the case of mobile app, or HEM, OTT, FPID device types.
If there are multiple segments per user ID the separator is Comma (,). Segment IDs are unique, alphanumeric segment IDs in Audience Studio.
Option 1: Incremental Refresh with Full Update
File format: UserID^SegmentID1,SegmentID2,SegmentID3
With this option, the partner specifies a refresh cadence X, and then Audience Studio will send incremental files for X-1 days and a full refresh every X days. On the incremental refresh days, there will be a corresponding COMPLETE.INCR file. On the full refresh days, there will be a corresponding COMPLETE.FULL file.
Note: Partners requesting this option must also provide the refresh cadence (eg: 30 days) for integration configuration, and we recommend it align to the user match recency supported by the partner if the system is heavily cookie-based.
Option 2: Incremental Refresh with Add/Remove/Final
File format: UserID^add:SegmentID1,SegmentID2;remove:SegmentID3;final:Segment1,Segment2,Segment4
This option has a different file format than the full and incremental options, but has the benefit of denoting which segments were added and removed. This may be helpful for partners who do not want a full refresh but who want to track which users are removed from which segments for the purpose of respecting consumer consent.
Option 3: Incremental Refresh (Standard)
File format: UserID^SegmentID1,SegmentID2,SegmentID3
In incremental pushes, each UserID line is a full refresh of segments for that user, which means that if if Day1 the UserID were in 3 segments, but Day2 the User dropped out of Segment3, the files would look like:
Day1: UserID^SegmentID1,SegmentID2,SegmentID3
Day2: UserID^SegmentID1,SegmentID2
In this option it is expected that the partner removes the user from Segment3.
Option 4: Full Refresh
File format: UserID^SegmentID1,SegmentID2,SegmentID3
With full refreshes, the file will contain the full list of users and segments.
OTT File Format
All OTT files contain device ID prefixes.
Example file: OTT_IDFA_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
File format: idfa:UserID^SegmentID1,SegmentID2
Example file: OTT_RIDA_<account_name>_segments_map_2019-09-01.csv-r-00001.gz
File format: rida:UserID^SegmentID1,SegmentID2
Upon Client Request: Segment Mapping File
When a mutual customer establishes a connection between Audience Studio and an Activation Partner, that customer must explicitly choose to send readable segment names instead of segment IDs. When this is enabled, Audience Studio will provide a mapping file that maps SegmentIDs to Segment Names.
The mapping file has the following columns:
- Segment ID
- Name
Sample Segment Mapping File:
File Name: segment_metadata.csv
File Format: SegmentID^Name
**Data** B8Y6OuXS^TEST001_ Xeneto in Lia
Accessing Data on S3
Please review the S3 Credentials article for information related to how to manage credentials. If you do not have access to manage credentials, please contact your Audience Studio administrator or submit a support request.
Usage Reporting
Usage reporting must be provided on a monthly basis and may be delivered to an S3 location. Please see our article that describes the required monthly usage reporting requirements.
Preparing for a Cookie-less World
We support several cookie-less options, such as mobile ids (MAIDs), connected TV or over-the-top (OTT) devices, and hashed email addresses (HEMs). If you have a current integration, have not yet adopted one or more of these device types, and are able to support them, please submit a support ticket and ask to have your integration configuration updated. Please provide the specific device types you wish to receive and along with the supported hash method where applicable.
0 Comments