Server-to-server (S2S) data import is a mechanism for making audience data available for buyers within MediaMath’s TerminalOne platform (T1).
The audience 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:
|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 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.
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:
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.
- The size of any one file may not exceed 4 GB.
- A maximum of 20 files may be sent per hour.
- 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.
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 MediaMath|
||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:email@example.com:2222 -e "put AgencyName_PartnerName_YYYYMMDDHHSS.log.gz; bye" lftp sftp://username:firstname.lastname@example.org:2222 -e "mput *.gz; bye"
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:
If you are providing generally available data (using a global taxonomy) 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
Example File Explanation
- 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
Taxonomies & External Data Segments
There are two ways to expose the audience segments onboarded in TerminalOne:
- 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.