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

Server Events vs Client (Browser) Events

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 a 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?

Getting Started

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)

Data Partners: What to Expect During the Setup Process

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:

From | To | Data Type

sku | product_id | String

order_id | order_id | String

price | product_price | String

Clients: What to Expect During the Setup Process

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.

Event API Limits

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

Real-time Server-Side Event Collection

Confirm Required Parameters

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 section of the MediaMath platform or to reach out to their account team for assistance.

UUID (mm_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.

At this point in time, only standard GUID format UUIDs (128 bits; hexadecimal format grouped as 8-4-4-4-12 and separated by four hyphens: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}) are accepted. As 1P cookie IDs do not always align with this format you will not be able to distribute them to MediaMath using this service until they are supported.

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.

Optional Parameters

Timestamp (mt_ts) is an optional parameter and a 10-digit epoch. When a UNIX epoch timestamp is provided, it will overwrite the transaction timestamp. Note: setting a historical timestamp will subject the event record to MediaMath event processing rules and may impact data processing downstream.

Generate Pixel ID

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.

Test Individual Event Distribution

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 

Verify Event Distribution

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

Set-up & Distribute Event Parameters

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.

Batch Server-Side Event Collection

Confirm Required Parameters

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.

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.

Type is a required parameter and a string.

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

Pixel ID is a required parameter and an integer. If you’ve already set up a MathTag for your website, we recommend that you use the same Pixel ID for your browser and server events.

UUID (mm_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.

At this point in time, only standard GUID format UUIDs (128 bits; hexadecimal format grouped as 8-4-4-4-12 and separated by four hyphens: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}) are accepted. As 1P cookie IDs do not always align with this format you will not be able to distribute them to MediaMath using this service until they are supported.

Frequently Used Optional Parameters

Timestamp (mt_ts) is an optional parameter and a 10-digit epoch. When a UNIX epoch timestamp is provided, it will overwrite the transaction timestamp. Note: setting a historical timestamp will subject the event record to MediaMath event processing rules and may impact data processing downstream.

Generate Pixel ID

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.

Test Batch Event Distribution

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

Individual event request

{  
            "version": 4.0,  
            "type": "event",  
            "mapping_id": "[YOUR_MAPPING_ID]",  
            "advertiser_id": [YOUR_ADVERTISER_ID],  
            "attributes": [ 
                { 
                    "[YOUR_KEY]": "[YOUR_VALUE]" 
                } 
            ] 
     } 

Batch event request

{ 
            "events": [ 
                { 
                    "version": 4.0,  
                    "type": "event",  
                    "mapping_id": "[YOUR_MAPPING_ID]",  
                    "advertiser_id": [YOUR_ADVERTISER_ID],  
                    "attributes": [ 
                        { 
                            "[YOUR_KEY]": "[YOUR_VALUE]" 
                        } 
                    ] 
                }, 
                { 
                    "version": 4.0,  
                    "type": "event",  
                    "mapping_id": "[YOUR_MAPPING_ID]",  
                    "advertiser_id": [YOUR_ADVERTISER_ID],  
                    "attributes": [ 
                        { 
                            "[YOUR_KEY]": "[YOUR_VALUE]" 
                        } 
                    ] 
                }, 
                { 
                    "version": 4.0,  
                    "type": "event",  
                    "mapping_id": "[YOUR_MAPPING_ID]",  
                    "advertiser_id": [YOUR_ADVERTISER_ID],  
                    "attributes": [ 
                        { 
                            "[YOUR_KEY]": "[YOUR_VALUE]" 
                        } 
                    ] 
                } 
            ]      
     } 

Review Responses

Recommended Parameters

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

Recommended parameters for conversions

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.

Recommended parameters for retailers

Recommended parameters for B2B

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