# 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](http://www.mediamath.com/legal/terms/audiencedata_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](mailto: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** (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](#common-parameters) section at the end of this document.

### 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:


```json
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

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

**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.
**Note**: *The value for advertiser_ID is tied to your mapping id and cannot
change once the mapping is created. The value in advertiser_ID may be
overwritten for on each record by specifying an attribute of mt_adid. This will
allow you to use the same main advertiser_ID and mapping for additional
advertisers in your organization.*

**Attributes**: (attributes) is required and an Array of Objects. Each object
is a dictionary of attributes and their values. Here we will hold all the
attributes associated with the event record. The remaining parameters belong
inside of the attributes field.

**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** (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.

For complete parameter specifications, data types, and usage notes, see the
[Common Parameters](#common-parameters) section at the end of this document.

### 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(s)`

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


```json
{
    "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`*


```json
{ 
    "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]" 
                } 
            ] 
        } 
    ]      
}
```

### Review Responses

| Code | Message | Description |
|  --- | --- | --- |
| 200 | Ok | Event(s) received |
| 400 | Invalid request body | Request missing required fields |
| 400 | Mapping not found | Mapping ID does not exist |
| 403 | Forbidden | Missing or invalid x-api-key |
| 415 | Unsupported media type | Content-Type is not application/json |
| 429 | Too many requests | Rate limit exceeded |


## 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

| Attribute | Parameter | Data Type | Example use case |
|  --- | --- | --- | --- |
| Revenue | v1 | numeric | Representing the total value of the transaction, revenue value is used to inform MediaMath Platform attribution (for ROAS / ROI goals) and can be used to build 1P audience segments based on transaction size |
| Currency | v2 | string | Representing the currency in which the transition was recorded, currency value is important for brand's that operate in more than one currency type |


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

| Attribute | Parameter | Data Type | Example use case |
|  --- | --- | --- | --- |
| Order ID | order_id | string | Representing a consumer's order in your system, this value can be useful for [log level data](/apis/log-level-data-service) analytics, like customer classification and sales insights |
| Revenue | v1 | numeric | Representing the total value of the transaction, revenue value is used to inform MediaMath Platform attribution (for ROAS / ROI goals) and can be used to build 1P audience segments based on transaction size |
| Currency | v2 | string | Representing the currency in which the transition was recorded, currency value is important for brand's that operate in more than one currency type |
| Product ID | product_id | string | Representing a SKU, this value uniquely identifies the products you sell. The value can be used to build 1P audience segments for remarketing and cross-selling purposes |
| Product Name | product_name | string | Representing the name of the product, this value can be used to build 1P audience segments for product level marketing efforts |
| Product Category | product_catgory | string | Representing a higher-level grouping of products, this value can be used to build 1P audience segments for product level marketing efforts |


### Recommended parameters for B2B

| Attribute | Parameter | Data Type | Example use case |
|  --- | --- | --- | --- |
| Client Status | client_status | string | Representing your classification of your customers (e.g. new, existing, preferred, etc.), this value can be used to build 1P audience segments for loyalty marketing efforts |
| Hashed Customer ID | mt_excl | string | Representing the currency in which the transition was recorded, currency value is important for brand's that operate in more than one currency type |
| Hashed Email Address | mt_exem | string | Representing the currency in which the transition was recorded, currency value is important for brand's that operate in more than one currency type |
| Page Name | page_name | string | Representing the page the consumer visited, this value can be used to build 1P audience segments based on content consumption over a period of time |


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

## Common Parameters

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

| Parameter | Required/Optional | Data Type | Description |
|  --- | --- | --- | --- |
| mt_id | Required | integer | MathTag (event pixel) ID |
| mt_aid | Required | integer | Advertiser ID |
| mt_uuid | Required | string | UUID for the event. Accepted values: MediaMath 3P cookie IDs, mobile advertising IDs, Connected TV device IDs. Format: standard GUID (128-bit hexadecimal: 8-4-4-4-12). Required for all use cases except when mt_ip is specified. |
| mt_ts | Optional | 10-digit epoch (seconds) | UNIX timestamp. Overwrites transaction timestamp. Historical timestamps are subject to event processing rules. |
| mt_ip | Recommended | string | IPv4 address where the event occurred. When specified, mt_uuid becomes optional. |


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

### IP Address (mt_ip)

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