> For the complete documentation index, see [llms.txt](https://docs.roadwayai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadwayai.com/data-requirements/warehouse-requirements/mobile-measurement-partners-mmps.md).

# Mobile Measurement Partners (MMPs)

Attributing app installs and in-app conversions

## Overview

If you acquire users through a mobile app, a Mobile Measurement Partner (MMP), such as AppsFlyer, Adjust, Branch, Singular or Kochava, is the system that attributes app installs and in-app events to the ad network and campaign that drove them. Roadway reads your MMP's user-level exports from your warehouse and uses the pre-signup touchpoints as attribution touchpoints, side by side with the web visits captured by the Roadway tag.

Roadway does not connect to MMPs directly. Instead, use your MMP's data export (most MMPs offer a scheduled "user-level" or "raw data" export to BigQuery, Snowflake, S3, etc.) to land the tables below in your warehouse.

{% hint style="warning" %}
MMP support is at an early stage and has so far been built around a single customer's setup. The requirements on this page are likely to change as we support more MMPs, and we will confirm the exact tables we need with you during onboarding.
{% endhint %}

## Required Tables

### User Attributions (Touchpoints)

This table is your MMP's user-level attribution export, with one row per attributed touchpoint (install, re-engagement or re-attribution) per user. The schema is as follows:

| **Column Name**        | **Data Type** | **Description**                                                                     | **Required** |
| ---------------------- | ------------- | ----------------------------------------------------------------------------------- | ------------ |
| `custom_user_id`       | varchar       | Your user identifier as set in the MMP SDK. Must match `user_id` in the Users table | Required     |
| `touchpoint_timestamp` | timestamp     | UTC timestamp of the touchpoint (click, impression or install)                      | Required     |
| `platform`             | varchar       | App platform, e.g. `ios`, `android`                                                 | Required     |
| `partner`              | varchar       | Ad network / media source the MMP attributed the touchpoint to                      | Required     |
| `campaign_name`        | varchar       | Campaign name reported by the partner                                               | Required     |
| `campaign_id`          | varchar       | Campaign identifier reported by the partner                                         | Optional     |
| `creative_name`        | varchar       | Creative / ad name                                                                  | Optional     |
| `creative_id`          | varchar       | Creative / ad identifier                                                            | Optional     |
| `country`              | varchar       | Country of the device at the time of the touchpoint                                 | Optional     |
| `utm_source`           | varchar       | UTM parameters, when the MMP passes them through (deep links, web-to-app)           | Optional     |
| `utm_medium`           | varchar       |                                                                                     | Optional     |
| `utm_campaign`         | varchar       |                                                                                     | Optional     |
| `utm_content`          | varchar       |                                                                                     | Optional     |
| `utm_term`             | varchar       |                                                                                     | Optional     |

**Key Notes**:

* `custom_user_id` is the identifier you attach to a user in your MMP's SDK once they sign up or log in (AppsFlyer calls it `customer_user_id`, Adjust and Singular call it a custom user ID, Branch calls it `developer_identity`). It **must** be the same value as `user_id` in your [Users](https://docs.roadwayai.com/data-requirements/warehouse-requirements/users.md) table
* Roadway joins MMP touchpoints to users on `custom_user_id` only. Touchpoints where it is empty, or does not match a user in the Users table, cannot be attributed and are dropped. Device IDs, IDFA/GAID and the MMP's own anonymous IDs are not used
* The export must be at the user level. Aggregated or cohort reports cannot be joined to users
* A user can have several rows, one per touchpoint. Roadway only uses the touchpoints that happened before the user's signup
* During onboarding, we map the partner names in your export to a traffic source and channel (e.g. a social network's partner name maps to traffic source `Performance Marketing` and channel `<Network> Ads`). Please send us the list of partners in your export
* Campaign names are looked up by `campaign_id`, using the same campaign mapping as your web traffic, since MMP campaign names are often truncated or renamed. Populate `campaign_id` whenever the partner provides it

### App Events (Optional)

This table contains one row per in-app event per user. It is only needed for in-app funnel metrics (e.g. app opens to purchases), not for attribution. The schema is as follows:

| **Column Name**   | **Data Type**             | **Description**                                                        | **Required** |
| ----------------- | ------------------------- | ---------------------------------------------------------------------- | ------------ |
| `user_id`         | varchar                   | Your user identifier. Must match `user_id` in the Users table          | Required     |
| `event_name`      | varchar                   | Event name as sent to the MMP SDK (including the install event)        | Required     |
| `event_timestamp` | timestamp                 | UTC timestamp of the event                                             | Required     |
| `platform`        | varchar                   | App platform, e.g. `ios`, `android`                                    | Required     |
| `revenue`         | decimal (nullable)        | Revenue of the event in your reporting currency. Null for other events | Required     |
| `arguments`       | json / varchar (nullable) | Event properties as sent to the MMP SDK                                | Required     |

**Key Notes**:

* `revenue` and `arguments` must be present in the table, but can be null
* Some MMPs truncate long event names in their exports. Please check that the exported names match what you expect
* During onboarding, let us know the name of your install event and of the conversion events you want to track

## How Roadway Uses MMP Data

MMP touchpoints that happened before a user's signup are used as attribution touchpoints. The traffic source and channel of each touchpoint are assigned as follows:

1. If the touchpoint has UTM parameters, your UTM attribution rules are applied
2. Otherwise, the partner-to-channel mapping is used
3. If the partner is not in the mapping, the traffic source is `Performance Marketing` and the channel is the raw partner name (or `Mobile - Unmapped` when the partner is empty)

The campaign is the campaign name mapped from `campaign_id`, falling back to the exported `campaign_name`.

When a user also has a pre-signup web visit captured by the Roadway tag, the web visit is used for attribution and the user's MMP touchpoints are ignored. MMP touchpoints are only used for users without a pre-signup web visit.

## Data Validation

* **Non-null custom\_user\_id**: Touchpoints without it are dropped from attribution
* **Custom user ID consistency**: `custom_user_id` values should match `user_id` values in the Users table. The share of matched touchpoints should be close to the share of users who signed up in the app
* **Non-null touchpoint\_timestamp and platform**: Every touchpoint must have a timestamp and a platform
* **Stable partner and campaign names**: Renamed partners or campaigns show up as new values


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.roadwayai.com/data-requirements/warehouse-requirements/mobile-measurement-partners-mmps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
