Introduction

Server-to-server (S2S) data distribution is a mechanism for making audience data available for buyers within MediaMath.

The data can be made available globally, so every MediaMath client can access it, or [permissioned](apis/audience-taxonomies/section/audience-segments-and-taxonomies/taxonomies-(permissioned) to a particular customer. The method for distributing the data is the same in both scenarios.

The workflow is as follows:

1. Sync and store MM UUID, if using third-party (3P) cookie-based identifiers
2. Apply Segment Code to user
3. Inform MediaMath of MM UUID:Segment Code

MM UUID: MediaMath Unique User ID (3P Cookie ID, Mobile Advertising ID, Connected TV ID). Note that in cases where 1P cookie IDs are being delivered to MediaMath, the MM UUID field in the examples below represents the 1P cookie ID value.

Segment Code: 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 and do the same when creating your audience taxonomies.

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 automatically, 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. Sizes below represent gzip file sizes.

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 provider to a MediaMath-supplied SFTP (file transfer for the secure shell—SSH—protocol) account.

The server details are:

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_YYYYMMDDHHMMSS.log.gz

If you are providing generally available data (using a global taxonomy) please omit the client name in the filename, example:

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

Filenames

The alphanumeric and special characters below can be used in filenames.

Alphanumeric characters:

• 0-9
• a-z
• A-Z

Special characters:

• Underscore (_)

Example File Format

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>
HashIDs: <0/1>

CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ...
CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ...
CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ...
CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ...
CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ...
CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ...

Note: The header section is followed by a blank line

Version - The version of the MediaMath audience data onboarding 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 MediaMath User IDs, obtained from our sync pixel, or device IDs this will be 'mm'. If you are delivering 1P cookie IDs, this will reflect the value provided to you by MediaMath for that 1P cookie ID.

UserTableId - OPTIONAL: This is the 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' and user IDs that are not 1P cookie IDs. This the same value used in our sync pixel, for example: //pixel.mathtag.com/sync/img?mt_exid=UserTableId

SegmentNamespace - Specifies whether the Segment Code 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 or CTV device IDs, otherwise 0. Do not mix Cookie based and Mobile/CTV audiences in the same file.

HashSegments - OPTIONAL: A value of 1 indicates that segment identifer is not a 32-bit integer, otherwise 0.

HashIDs - OPTIONAL: Only use this feature with express permission from MediaMath. A value of 1 indicates that user ID values should be hashed upon upload, otherwise 0. A value of 1 should only be used if the user ID is not in GUID Version 4 format.

Note: There are 2 special cases for the UnixTimestamp value when used on the segment load statements

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 you combine user/segment load statements, so that many segments are applied on a single line, rather than duplicating the same User ID 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; this represents the gzipped file size. 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

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

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

Mobile & other Connected Device Audiences

Every Android and Apple device (>= iOS6) has a unique identifier. The process for uploading audience files is exactly as above, except that instead of a 3P Cookie ID, the IDFA or GAID is used. Similarly, other connected devices - like TVs - have unqiue identifiers.

When sending non-cookie based audiences, ensure the header of the file declares Mobile: 1. While Apple's iOS advertising IDs are typically all in upper case and Google's Android advertising IDs are typically all in lower case, we don't distinguish between case during the data onboarding process. Do not mix cookie and non-cookie based 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. We recommend implementing retry logic with exponential backoff.

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 MediaMath Platform:

Taxonomies

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

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.