Introduction

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 MM UUID Apply Segment ID to user Inform MediaMath of MM UUID:Segment ID

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)


User Syncing

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.

The tag operates by first loading on a MediaMath domain (pixel.mathtag.com) and then either redirecting to a partner domain with the MM UUID appended (image tag) or loading a partner domain asynchronously (JavaScript tag).

In all cases the JavaScript sync tag is preferred, and the image tag is provided only when JavaScript is not approved to run on the partner pages. The rendered output of the tag is a 1x1 clear gif, and the tag can be wrapped in a <div> with 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:

Name Description Sample Value
[MM_UUID] MediaMath Unique User ID 5f11538c-fcb6-4600-88e0-6e51bff72bbc
[MT_DC] 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

<script type="text/javascript" src="//pixel.mathtag.com/sync/js?exsync=//partner.com/usersync%3Fmmuuid=[MM_UUID]"></script>

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 [MM_UUID] and [MT_DC]. Please note that the URL provided via the exsync parameter should be single encoded.

For example, your user sync endpoint could be:

https://sync.partner.com/mediamath?user_id=[MM_UUID]&dc=[MT_DC]

after encoding, this becomes:

https%3A%2F%2Fsync.partner.com%2Fmediamath%3Fuser_id%3D%5BMM_UUID%5D%3Cdc%3D%5BMM_DC%5D

For help with encoding, see here: http://www.w3schools.com/tags/ref_urlencode.asp

append to exsync like so:

http://pixel.mathtag.com/sync/js?sync=auto&exsync=https%3A%2F%2Fsync.partner.com%2Fmediamath%3Fuser_id%3D%5BMM_UUID%5D

JavaScript is preferred; however, you may also use a pixel tag as follows:

//pixel.mathtag.com/sync/img?redir=https%3A%2F%2Fsync.partner.com%2Fmediamath%3Fuser_id%3D%5BMM_UUID%5D

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).

Audience Tab

Audience Tab

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
full_path Data.com Age
code 12345 Partner Segment ID - unique to this segment Integer
uniques 1000000 Number of unique users in this segment (rounded estimate) Integer
wholesale_cpm 0.80 The CPM (Cost per Thousand Impressions) that MediaMath will pay the partner, in US Dollars Decimal (2dp)
retail_cpm 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)
buyable 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 full_path field to be populated. Integer 1 or 0

In this view, the Audience Targeting Tab has been annotated to show the elements from the Taxonomy:

Audience Tab Annotated

Audience Tab Annotated

Sample Taxonomy

full_path code uniques wholesale_cpm retail_cpm buyable
|BlueKai 0
|BlueKai|Group 1 0
|BlueKai|Group 1|Segment 1 0
|BlueKai|Group 1|Segment 2 0
|BlueKai|Group 1|Segment 3 245244 661,664 0.85 1 1
|BlueKai|Group 1|Segment 4 245245 3,585,118 0.85 1 1
|BlueKai|Group 1|Segment 5 245246 5,247,410 0.85 1 1
|BlueKai|Group 2 0
|BlueKai|Group 2|Segment 1 245247 34,355 0.85 1 1
|BlueKai|Group 2|Segment 2 245248 13,248 0.85 1 1
|BlueKai|Group 2|Segment 3 245249 8,242,543 0.85 1 1
|BlueKai|Group 2|Segment 4 245250 9,857,983 0.85 1 1
|BlueKai|Group 2|Segment 5 245251 34,324 0.85 1 1

Note: The full_path always starts with a pipe

To submit your taxonomy, please email to developers@mediamath.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.

The Data Provider is added on behalf of the Buyer by Advertising Operations Support: (adops_support@mediamath.com). 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 Pixels -> + ADD PIXEL -> Add Data Pixel

T1 Add Data Pixel

The Buyer should then complete the following form:

T1 Data Pixel

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: t1_support@mediamath.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

SegmentNamespace:Partner_Segment_ID, mm:MediaMath_Pixel_ID 

Example:

ab:50245, mm:504525

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.

Data Transfer

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.

  1. A maximum of 20 files can be sent per hour.
  2. 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.
  3. The size of any one file must not exceed 4 Gb.

SFTP

Audience Data is uploaded by the partner to a MediaMath-supplied SFTP (file transfer for the secure shell—SSH—protocol).

The server details are:

Name Value
Host sftp.datasvc.mediamath.com
Port 2222
Protocol SFTP
Username Supplied by MM team
Password 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:password@sftp.datasvc.mediamath.com:2222 -e "put AgencyName_PartnerName_YYYYMMDDHHSS.log.gz; bye"
lftp sftp://username:password@sftp.datasvc.mediamath.com:2222 -e "mput *.gz; bye"

Audience File

If you are providing private client data (using the Pixel Targeting option) please include the client name in the filename, example:

AgencyName_PartnerName_YYYYMMDDHHSS.log.gz

If you are providing global data (using the Audience targeting option) please omit the client name in the filename, example:

PartnerName_YYYYMMDDHHSS.log.gz  

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 (LF, \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: date +"%s"

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

Value Meaning
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.

Quota

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.

Example File

In this example, the Partner is using MediaMath cookie IDs, and has been assigned the SegmentNamespace ‘ep’.

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
Explanation
  1. Append segments 10001 & 10003 right now, 10005 with an historical UNIX timestamp
  2. Remove user from segment 10002 now
  3. Add user to segment 10002 now
  4. Remove user from all segments and add to 10002 now.
  5. Remove user from all segments. You must use an non-existent segment to replace.

Mobile Audiences

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:

https://s2s-api.datasvc.mediamath.com/logs

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 developers@mediamath.com, where we will be happy to assist.

Required Information

  • 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.