- User Syncing
- Segmentation & Taxonomy
- Data Transfer
- Mobile Audiences
- Processing Log API
- Getting Started Checklist
- Required Information
Server to Server Data Import (S2S) is a mechanism for making audience data available for buyers within MediaMath’s TerminalOne platform (T1).
The audiences can be made both publicly available, globally, or privately to a particular buyer. The method for importing the data is the same in both scenario’s, the difference being in the initial setup of the audience segment.
The basic workflow of S2S is as follows:
|Step 1||Step 2||Step 3|
|Sync and store
||Inform MediaMath of
MM UUID: The MediaMath Unique User ID (Cookie ID)
Segment ID: The partner defined ID for the audience segment. 32 bit int (maximum value of 2,147,483,647)
In order for a partner to send audience data to MediaMath, there must already be a user sync process in place. This means that the partner can refer to a user by their MediaMath Unique User ID (MM UUID).
User Synching is handled via a sync tag (also known as a sync pixel). This tag is placed by the data provider on pages with high user traffic volumes. Strategic positioning of the tag serves to maximize the distribution of synced users.
style="display:none" to hide it from view if required.
There are 2 macros available to the data provider for use within a sync tag URL:
||MediaMath Unique User ID||5f11538c-fcb6-4600-88e0-6e51bff72bbc|
||3 letter MediaMath Data Center code||ewr|
Note: MT_DC is used for optimization when importing data. It references the optimal MediaMath Data Center for that user
Sample Sync Tag
Do not use the below in production
When provided with your sync tag, there is a parameter
exsync which will contain the URL you wish to direct user syncs to. This URL will receive the MediaMath Unique User ID and Data Center value via replacement of the macros
[MT_DC]. Please note that the URL provided via the
exsync parameter should be single encoded.
For example, your user sync endpoint could be:
after encoding, this becomes:
For help with encoding, see here: http://www.w3schools.com/tags/ref_urlencode.asp
exsync like so:
Segmentation & Taxonomy
There are two ways of setting up audience segments within TerminalOne. The most popular approach is to make public segments available to all buyers via the Audience Targeting section. The second approach is to make private segments available via the Pixel Targeting section. It is possible to use both methods to achieve a hybrid of both public and private segments to suit the needs of the buyers.
Note: Since the data transfer is the same for both global and private segments, this is the only section where the two methods will be mentioned separately.
Audience Targeting (Global)
The Audience Targeting view for buyers is presented as a tree, with the first nodes being the Partner name. Within the tree is an expandable selection of segments and categories, each represented with an size estimation (number of unique users) and a CPM price (in US Dollars).
This tree is populated via a CSV file provided to MediaMath from the partner. The format of this CSV is:
|Column Name||Example Value||Description||Type|
||12345||Partner Segment ID - unique to this segment||Integer|
||1000000||Number of unique users in this segment (rounded estimate)||Integer|
||0.80||The CPM (Cost per Thousand Impressions) that MediaMath will pay the partner, in US Dollars||Decimal (2dp)|
||1.10||The CPM (Cost per Thousand Impressions) that Buyers will pay MediaMath, in US Dollars. This is the value that is shown to buyers in the T1 Audience Targeting Tab||Decimal (2dp)|
||1||Used to separate segments from non-purchasable categories (which aid navigation). When “1” it will be buyable in T1. When “0” it is not buyable and only requires
||Integer 1 or 0|
In this view, the Audience Targeting Tab has been annotated to show the elements from the Taxonomy:
Audience Tab Annotated
full_path always starts with a pipe
To submit your taxonomy, please email to email@example.com with the subject line “PartnerName Audience Taxonomy”.
Pixel Targeting (Private)
The Pixel Targeting view for buyers is presented as a list, which is private to a particular Agency. In TerminalOne, Organization is the highest-level attribute, followed by Agency (then Advertiser, Campaign and Strategy). An Agency can have multiple Advertisers underneath it, and any of these Advertisers can use the Data Pixel for targeting. An Organization represents the contractual level with MediaMath, so all Data Pixels exposed are shown only to Agencies underneath a certain contract holder.
To facilitate the privatization, MediaMath requires that the Buyer create the Data Pixel in their desired Agency within TerminalOne.
A one time step is required for each Agency, to add a
Data Provider. This step is only required the very first time a buyer wishes to make a private audience segment.
Data Provider is added on behalf of the Buyer by Advertising Operations Support: (firstname.lastname@example.org). The Buyer should use the subject line “Data Provider Request” and include the Agency Name & ID within the body of the email.
To add a Data Pixel (which will represent the Private Audience Segment), the Buyer should navigate in TerminalOne Classic to
+ ADD PIXEL ->
Add Data Pixel
T1 Add Data Pixel
The Buyer should then complete the following form:
T1 Data Pixel Form
Upon submission, a MediaMath Pixel ID will be created. The buyer should communicate that ID to the Partner. The Partner pairs this MediaMath ID with the Partner Segment ID and passes the information to MediaMath via email to: email@example.com. This pairing is referred to as “mapping”, and allows for a private link from a Partner Segment ID to an Agency specific private MediaMath Data Pixel ID.
Please use the following subject line in the email:
Subject Line: Pixel Mapping Request (s2s) [Partner Name]
The format of the email detailing the “mapping” request should be
To request multiple mappings, simply put each mapping on a new line, example:
ab:50245, mm:504525 ab:50250, mm:612340 ab:50251, mm:612344
For more information on
SegmentNamespace please refer to the Data Transfer section.
Batch file based transfer
Once a Sync Tag is in place, and Audience Segments are defined, it is possible to start sending data to MediaMath. During initial setup, you will be asked to provide a sample file for validation by MediaMath. After validation, files will be processed autonomously, on a regular basis. We ask that the contents be efficient to process (this is explained in more detail below).
Note: There are certain limits to the file size and the number of files that can be sent.
- A maximum of 20 files can be sent per hour.
- We enforce a total limit of 4 Gb of files that can be sent over an hour. Eg: If you send us 5 files in an hour, the sum of the sizes of all the files cannot exceed 4 Gb.
- The size of any one file must not exceed 4 Gb.
Audience Data is uploaded by the partner to a MediaMath-supplied SFTP (file transfer for the secure shell—SSH—protocol).
The server details are:
||Supplied by MM team|
||Supplied by MM team|
It is highly recommended you use an SFTP client other than the Linux BSD ‘sftp’ command or a library that depends on it. LFTP has been thoroughly tested and can upload files using one of these single or multi file commands:
lftp sftp://username:firstname.lastname@example.org:2222 -e "put AgencyName_PartnerName_YYYYMMDDHHSS.log.gz; bye" lftp sftp://username:email@example.com:2222 -e "mput *.gz; bye"
If you are providing private client data (using the Pixel Targeting option) please include the client name in the filename, example:
If you are providing global data (using the Audience targeting option) please omit the client name in the filename, example:
If you are providing both types of data, please provide 1 file for global data, and 1 file per private client, example (3 private clients and 1 global file):
AgencyName1_PartnerName_201407302300.log.gz AgencyName2_PartnerName_201407302300.log.gz AgencyName3_PartnerName_201407302300.log.gz PartnerName_201407302300.log.gz
The file supplied must contain unix line endings (
\n), and must be compressed with gzip.
See here for more information on gzip compression.
The audience upload file is a plain text file, containing a header section followed by rows of segment load statements, example:
Version: <VERSION NUMBER> FileIdentifier: <DESCRIPTION> DateCreated: <UNIX TIMESTAMP> UserNamespace: <TWO LETTER NAMESPACE> UserTableId: <EXCHANGE ID - LINE OMITTED WHEN USERNAMESPACE IS MM> SegmentNamespace: <TWO LETTER NAMESPACE> Mobile: <0/1> HashSegments: <0/1> CookieID SegmentID:UnixTimestamp SegmentID:UnixTimeStamp SegmentID:UnixTimeStamp ... CookieID SegmentID:UnixTimestamp SegmentID:UnixTimeStamp SegmentID:UnixTimeStamp ... CookieID SegmentID:UnixTimestamp SegmentID:UnixTimeStamp SegmentID:UnixTimeStamp ... CookieID SegmentID:UnixTimestamp SegmentID:UnixTimeStamp SegmentID:UnixTimeStamp ... CookieID SegmentID:UnixTimestamp SegmentID:UnixTimeStamp SegmentID:UnixTimeStamp ... CookieID SegmentID:UnixTimestamp SegmentID:UnixTimeStamp SegmentID:UnixTimeStamp ...
Note: The header section is followed by a blank line
Version - The version of the S2S system this should be ‘3’ for new integrations.
FileIdentifier - Print the filename. This should be unique from other uploads and follow the naming convention above.
DateCreated - Unix timestamp of file creation. For more information on Unix Time, see here. Linux example:
UserNamespace - Specifies whether the supplied User IDs are from the Partner Namespace, or from MediaMath (mm). If you are supplying our User IDs obtained from our sync pixel; this will be ‘mm’.
UserTableId - OPTIONAL: This is the Exchange ID used for identifying the match table for user IDs outside of the MediaMath namespace. This header should only be included when using a
UserNamespace that is not ‘mm’. This the same value used in our sync pixel, for example: //pixel.mathtag.com/sync/img?mt_exid=UserTableId
SegmentNamespace - Specifies whether the Segment ID values are from the Partner Namespace, or from MediaMath. Usually this is the Partner namespace assigned to you.
Mobile - A value of 1 indicates that the User IDs in this file are Mobile IDs, otherwise 0. Do not mix Mobile and Display audiences in the same file.
HashSegments - A value of 1 indicates that Segment ID values contain non-numeric values, otherwise 0.
Note: There are 2 special cases for the UnixTimestamp value when used on the segment load statements
|0||“Now”" - will add the user at point of processing|
|-1||Remove user from specified segment|
The UnixTimestamp can be used in regular form (seconds since Epoch), to define if a user should be added to a segment in the future or the past. This is useful for recurring purchases, or time sensitive deals. It also allows for the back processing of data, should the partner suffer from a failure.
We request that the partners combine user/segment load statements, so that many segments are applied on a single line, rather than duplicating the same CookieID on more than one line throughout the file. Note: As part of ongoing validation procedures, files will be checked for this efficiency. Failure to upload in a load efficient manner may lead to automatic processing being suspended until rectified.
The SFTP will not accept an upload larger than 4GB per file. Each line must be fewer than 8,000 characters. Additionally, a maximum quota is defined to prevent partners de-stablizing the service. Currently this is a maximum of 5GB per day and 20 files per hour. These quotas are reset at midnight UTC and every hour on the hour respectively.
In this example, the Partner is using MediaMath cookie IDs, and has been assigned the
Version: 3 FileIdentifier: ExamplePartner_201407302300.log.gz DateCreated: 1406761200 UserNamespace: mm SegmentNamespace: ep Mobile: 0 HashSegments: 0 2c3753c5-9a67-4600-f044-a5d7e0c5f6d7 10001:0 10003:0 10005:1406850980 3d3353c3-9a67-4651-a443-a6d7e1c4fde8 10002:-1 4e2754c5-5562-4601-1742-a9d7e2c3fef9 10002:0 4a5124c5-aab1-3222-1154-a2d7f2a33ef9 -1 10002:0 7a513b12-ab1b-3fe2-bc54-a5d7f2a33911 -1 9999999:0
- Append segments 10001 & 10003 right now, 10005 with an historical UNIX timestamp
- Remove user from segment 10002 now
- Add user to segment 10002 now
- Remove user from all segments and add to 10002 now.
- Remove user from all segments. You must use an non-existent segment to replace.
Every Android and Apple >= iOS6 device has a unique Identifier for Advertising (IDFA). The process for uploading audience files is exactly as above. Except that instead of MM UUID (Cookie ID) we use the IDFA or AdID.
When sending mobile audiences, only ensure the header is set Mobile: 1. Do not mix display and mobile audiences in the same file.
Processing Log API
You may query the following API endpoint to get job results:
You must use Basic Authentication, with the same user credentials as your SFTP.
Queries can be executed as follows, all variables should be URL encoded
https://s2s-api.datasvc.mediamath.com/logs?filename=ExamplePartner_201407302300.log.gz https://s2s-api.datasvc.mediamath.com/logs?start_date=1970-01-01%2012:00:00 https://s2s-api.datasvc.mediamath.com/logs?start_date=1970-01-01%2012:00:00&end_date=2000-01-01%2023:59:59 https://s2s-api.datasvc.mediamath.com/logs?offset=100
The processing logs will be returned in JSON format. Use the offset paramater for pagination.
Another example on a linux command line:
curl -u <username>:<password> https://s2s-api.datasvc.mediamath.com/logs?filename=ExamplePartner_201407302300.log.gz | python -m json.tool
Getting Started Checklist
- Place Sync Pixel on high volume pages
- Store MediaMath cookie IDs against own user IDs
- Inform MediaMath of Audience Taxonomy and/or Private Segments
- Upload a sample file to SFTP for approval
- Deliver files to SFTP on regular basis
- Keep MediaMath informed of changes to Global Audience Taxonomy or additional Private Segments.
If you have any questions surrounding this guide, please email firstname.lastname@example.org, where we will be happy to assist.
- All partners are required to have an active Partner Profile. To sign up, see here
- Let us know how many users you will sync per day (estimate to nearest million)
- Let us know the maximum number of segments a single user can be in, this helps with our robot detection.
- Send us a short paragraph describing your business. This will be included in T1 release notes and customer emails to let them know what’s new in T1.