Audience Event Onboarding

Collect, activate, and measure marketing events with the Event API through server-side data collection. Linked to a MathTag (aka MediaMath event pixel), server-side events are processed like events from a MediaMath JavaScript or image tag but avoid the placement of code on your site or in your app. These events can be used just like an on-site MathTag, collecting marketing events for use in targeting, optimization, segmentation & lookalike modeling, and measurement.

We offer two options for collecting marketing events via the Event API:

• Individual event collection, recommended for server-side tag manager integrations and any real-time marketing event collection
• Batch event collection, recommended for CDPs, DMPs, visitation measurement, and other offline conversion event collection in bulk

On the web, a client refers to a web browser or mobile device—whatever the consumer is using to navigate the Internet. The server refers to a program or device that returns web pages to be rendered in a browser or mobile app. Collecting a marketing event client-side means the action takes place on the consumer's browser or device and collecting a marketing event server-side means the action takes place on a server.

There are different reasons and pros/cons to both options, which is why MediaMath offers a variety of audience data onboarding solutions. Consider the questions below when deciding whether the Event API is right for you:

• Is site latency a concern?
• Is the activity you want to distribute to the MediaMath platform happening offline or offsite?
• How important is real-time activation & optimization?
• What percentage of your site visitors employ ad blockers?
• Do you have engineering resources to support server-side event collection?

As part of the provisioning process, you will receive the following from MediaMath:

For individual, real-time server-side event collection:

• MathTag (aka MediaMath event pixel) ID (_this may be provided by a mutual client, created in the MediaMath platform, &/or created with the MediaMath API)

For batch, server-side event collection:

• Batch event API key (note: this key is separate from the Client ID & Secret used to authenticate with other MediaMath APIs)
• Mapping ID (1 per MathTag ID)
• MathTag (aka MediaMath event pixel) ID (_this may be provided by a mutual client, created in the MediaMath platform, &/or created with the MediaMath API)

All data partners distributing data to MediaMath need a MediaMath vendor account. The vendor account organizes your data for use in our systems and, for certain data providers, will be referenced for reporting & financial purposes.

There are several steps prior to onboarding data with MediaMath:

1. Choose the integration method(s) best suited for your needs. Depending on the marketing data you have, one or more audience data onboarding solutions from MediaMath may meet your needs. This set of server-side event collection solutions are best suited for using audience data for retargeting, optimization, 1P segmentation & modeling, and attribution in the MediaMath platform.
2. Engage with the partnerships team. They will help you establish a vendor account and, in some cases, determine the structure of a commercial agreement (i.e. for 3rd party data providers). Prior to reaching out to the partnerships team, familiarize yourself with the MediaMath Audience Data Policy.
3. Verify Batch Event API access and deliver a Batch Event payload. With confirmation of successful event delivery, access to deliver data on behalf of MediaMath customer accounts will be granted.
4. Determine the appropriate attribute fields: MediaMath will provide you with our Event API Mapping Template along with a complete list of attributes we support. Use the template to determine the appropriate "From" fields - what the attribute fields are named in the partner's system, and determine the appropriate "To" fields - the attribute fields used by MediaMath, and which the "From" fields will be mapped to. Once you fill out the mapping template with the appropriate Advertiser Name, Advertiser ID and mapping attributes, submit a request to support@mediamath.com for a new API key (if you already do not have one) and a new mapping ID.

Example:

All MediaMath clients may distribute their 1P data to MediaMath for their use as part of a standard services agreement.

If you wish to monetize your data assets, you will follow the steps above as a data partner so that financial reporting can take place.

The Event API has rate limiting in place. If you have concerns about the limits outlined below, please contact the data partnerships team to discuss your needs.

For individual, real-time server-side event collection:

• 1k QPS

For batch, server-side event collection (rate limited by API key):

• 10 QPS
• Up to 5 concurrent requests
• 50k total requests per day, per Batch event API key

Pixel ID (mt_id) is a required parameter and an integer. If a MathTag is already set-up on your website, you can use the same Pixel ID for your browser and server-side events.

Advertiser ID (mt_aid) is a required parameter and an integer. If you’re a data partner, ask your client to locate their advertiser ID in the Admin data partner, ask your client to locate their advertiser ID in the Admin section of the MediaMath platform or to reach out to their account team for assistance.

UUID (mt_uuid) is a required parameter and a string. Accepted values in MediaMath 3P cookie IDs, obtained via syncing, mobile advertising IDs, and Connected TV device IDs.

Source (source) is a required parameter and a string. You'll append &source=s2s to every record produced, which enables tracking and monitoring of the data collected.

For complete parameter specifications, data types, and usage notes, see the Common Parameters section at the end of this document.

If you don’t already have a Pixel ID, it can be created in the MediaMath platform, &/or created with the MediaMath API. If you’re a data partner, ask your client to provide a pixel ID in the Audiences section of the MediaMath platform or to reach out to their account team for assistance.

Requests To send events, POST a request to pixel-s2s.mathtag.com from this path:

https://pixel-s2s.mathtag.com/event/img?mt_id=(pixel_id)&mt_adid=(advertiser_id)&mt_uuid=(browser or device ID)&source=s2s 

After you send events, confirm they have been received in the MediaMath platform. Note, if you are a data partner working on behalf of a mutual client, ask the client or MediaMath support to confirm loads & uniques for the pixel ID(s).

Once you have verified event distribution, review the website or app and the list of recommended parameters below to determine if any additional metadata should be distributed to MediaMath. For marketing use cases that include 1P segmentation & modeling or attribution, selecting relevant recommended parameters will support activation in the MediaMath platform.

Version (version) is a required parameter and an integer. Set this to 4.0.

Type (type) is a required parameter and a string.

Mapping ID (mapping_id) is a required parameter and a string. This will be provided by the MediaMath team during initial set-up. As there is a 1:1 relationship between Mapping ID and MathTag (aka MediaMath event pixel) ID, subsequent mapping IDs may be required.

Advertiser ID (advertiser_id) is a required parameter and an integer. If you’re a data partner, ask your client to locate their advertiser ID in the Admin section of the MediaMath platform or to reach out to their account team for assistance.

• The advertiser_id is tied to your mapping id and cannot be changed once the mapping is created.
• It serves as the "primary advertiser-ID", acting as the default for all events in the batch.
• You can override it per record using the mt_adid attribute, allowing multiple advertisers to share the same mapping.

Attributes: (attributes) is required and must be an array of objects. Each object represents a transaction event that occurred on the advertiser’s site and contains a set of attribute key-value pairs. All remaining parameters should be included within this field, and mappings are applied at the attribute level.

• Pixel ID (mt_id) is a required parameter and an integer. If you've already set up a MathTag for your website, use the same Pixel ID for both browser and server events. In many cases, this is the same pixel used as the campaign's merit pixel.
• UUID (mt_uuid) is a required parameter and a string. Accepted values include MediaMath 3P cookie IDs (obtained via cookie syncing), mobile advertising IDs (MAID), Connected TV device IDs, or Universal IDs (1P IDs).
• Advertiser ID (mt_adid) is optional and an integer. Use this to specify the advertiser for the attribute object when it differs from the primary advertiser.

For complete parameter specifications, data types, and usage notes, see the Common Parameters section at the end of this document.

If you don't already have a Pixel ID, it can be created in the MediaMath platform, &/or created with the MediaMath API. If you're a data partner, ask your client to provide a pixel ID in the Audiences section of the MediaMath platform or to reach out to their account team for assistance.

Requests The batch endpoint supports individual and batch event distribution (up to 100 events per request) to MediaMath. To send events, POST a request to https://ingest-default.prod.octane.mediamath.com/v1/event(s)

Individual event request Use: https://ingest-default.prod.octane.mediamath.com/v1/event

{
    "version":       4.0,  
    "type":         "event",  
    "mapping_id":   "[YOUR_MAPPING_ID]",  
    "advertiser_id": [YOUR_ADVERTISER_ID],  
    "attributes": [
        {
            "mt_id":   "[YOUR_PIXEL_ID]",
            "mt_adid": "[YOUR_ADVERTISER_ID]", // If not specified the value in
                                               // advertiser_id field above will be used 
            "mt_uuid":  "[DIVICE_UUID]",

            "[YOUR_KEY]": "[YOUR_VALUE]" 
            ...
        } 
    ] 
} 

Batch event request Use: https://ingest-default.prod.octane.mediamath.com/v1/events

{ 
    "events": [ 
        { 
            "version":       4.0,  
            "type":         "event",  
            "mapping_id":   "[YOUR_MAPPING_ID]",  
            "advertiser_id": [YOUR_ADVERTISER_ID],  
            "attributes": [ 
                { 
                    "mt_id":      "[YOUR_PIXEL_ID]",
                    "mt_adid":    "[YOUR_ADVERTISER_ID]", // If not specified the value in 
                                                         // advertiser_id field above will be used 
                    "mt_uuid":    "[DIVICE_UUID]",

                    "[YOUR_KEY]": "[YOUR_VALUE]" 
                    ...
                } 
            ] 
        }, 
        { 
            "version":       4.0,  
            "type":         "event",  
            "mapping_id":   "[YOUR_MAPPING_ID]",  
            "advertiser_id": [YOUR_ADVERTISER_ID],  
            "attributes": [ 
                { 
                    "mt_id":      "[YOUR_PIXEL_ID]",
                    "mt_adid":    "[YOUR_ADVERTISER_ID]",
                    "mt_uuid":    "[DIVICE_UUID]",
                    "[YOUR_KEY]": "[YOUR_VALUE]" 
                } 
            ] 
        }, 
        { 
            "version":       4.0,  
            "type":         "event",  
            "mapping_id":   "[YOUR_MAPPING_ID]",  
            "advertiser_id": [YOUR_ADVERTISER_ID],  
            "attributes": [ 
                { 
                    "mt_id":      "[YOUR_PIXEL_ID]",
                    "mt_adid":    "[YOUR_ADVERTISER_ID]",
                    "mt_uuid":    "[DIVICE_UUID]",
                    "[YOUR_KEY]": "[YOUR_VALUE]" 
                } 
            ] 
        } 
    ]      
} 

We support 200+ optional marketing event attributes, including up to 40 custom attributes per MediaMath event pixel. An attribute is a key and the information you transmit to MediaMath is the value paired with it.

• If an attribute is not relevant for a given marketing event record, leave the value blank (e.g. &page-name=).
• Do not include a currency symbol when passing revenue; use the currency attribute to declare currency.
• Only include salted & hashed values when passing email addresses or customer IDs; never include personally identifiable information (PII).

Additional parameters may be useful, but for most conversion attribution use cases we recommend providing revenue captured from the conversion activity. Revenue attribution is used to inform the MediaMath Brain which attribute to use for revenue when optimizing towards ROI. If your site or app supports multiple currencies, provide that value as well. MediaMath supports either fixed or dynamic currency, if your site or app supports multiple currencies.

Note: if you're considering passing your customer's IDs or email addresses, we recommend only passing one of the hashed values. This aligns with the approach of privacy by design to minimizes the amount of personal data shared. If you opt to only pass one hashed value, the unused attribute's parameter can be omitted or passed without a value (e.g. mt_excl=). All hashed values should be salted & hashed with SHA256 and only include salted & hashed values when passing email addresses or customer IDs; never include personally identifiable information (PII).

The following parameters are used across both real-time and batch event collection methods.

UUID Requirement Note: mt_uuid is required for all use cases except when mt_ip is specified. When mt_ip is provided and mt_uuid is not, a random UUID will be generated internally. This generated ID will not be used for retargeting and attribution. Our system knows to ignore these transient UUIDs.

The mt_ip parameter allows you to specify the IPv4 address where an event occurred. This is useful for server-to-server event collection when the original client IP address is available.

• Format: Valid public IPv4 address (e.g., "203.0.113.1"). Do not use private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) or loopback addresses (127.0.0.0/8) as these have little usefulness for retargetting or attribution
• When mt_ip is specified, mt_uuid becomes optional
• If mt_uuid is not provided when mt_ip is used, a random UUID will be generated