Introduction

Server-to-server (S2S) data import is a mechanism for making audience data available for buyers within TerminalOne (T1).

The data can be made available globally, so every MediaMath customer can access it, or permissioned to a particular customer. The method for importing the data is the same in both scenarios.

The workflow of S2S is as follows:

  1. Sync and store MM UUID
  2. Apply Segment Identifier to user
  3. Inform MediaMath of MM UUID:Segment Identifier

MM UUID: MediaMath Unique User ID (Cookie ID or Mobile Advertising ID)

Segment Identifier: The partner defined identifier for the segment. 32 bit integer is supported (maximum value of 2,147,483,647); if you are using a segment identifier that is not a 32-bit integer, declare HashSegments: 1 in the file header to ensure proper processing.


User Syncing

In order for a data provider to send audience data to MediaMath, there must be a user sync process in place. This means that the provider can refer to a user by a MediaMath Unique User ID (MM UUID).

User syncing 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

Data Transfer

Batch file based transfer

Once a sync tag is in place, 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 limits to the file size and the number of files that can be sent.

  1. The size of any one file may not exceed 4 GB.
  2. A maximum of 20 files may be sent per hour.
  3. We enforce a total limit of 5 GB of files that can be sent per day, e.g. if you send us 10 files in a day, the sum of the sizes of all the files cannot exceed 5 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 MediaMath
Password Supplied by MediaMath

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 a permissioned taxonomy or external data segment options) please include the client name in the filename, example:

AgencyName_PartnerName_YYYYMMDDHHSS.log.gz

If you are providing generally available data (using a global taxonomy) 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

Example File 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. Messages include:

  • OK
  • File is empty
  • File is invalid
  • File is not in GZIP format
  • Invalid headers
  • Integration {x} is not authorized to write into namespaces {y}

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

Taxonomies & External Data Segments

There are two ways to expose the audience segments onboarded in TerminalOne:

Taxonomies

  • These can be global, meaning all MediaMath customers will have access to the segments within the taxonomy via TerminalOne.
  • These can be permissioned so that only select MediaMath customers have access to the segments within the taxonomy in TerminalOne.

External Data Segments

  • These represent a single segment of users and are always permissioned.
  • These are also referred to as Data Pixels.

It’s possible to use both methods to achieve a mix of global and permissioned taxonomies & external data segments to suit your needs and the needs of your customers.

Note: The S2S data import process is the same for both global and permissioned taxonomies, as well as external data segments.