MMM setup

Prerequisites

A Google BigQuery connector already set up in Settings → Connectors
Access to the client’s Google Cloud project (to create a bucket and assign IAM roles)
A trained Meridian model ready to export results

Step 1 — Create the GCS bucket

Create one Cloud Storage bucket in the client’s GCP project. This bucket is where the pipeline writes model result and scenario artifacts. GCS bucket names are globally unique, so every client gets its own bucket name. By default Interact expects:

{client}-turntwo-mmm

{client} is the organization name in lowercase, with spaces, accents and special characters removed. The exact default for your organization is shown in Insights → Settings → MMM.

Setting	Value
Bucket name	The default above, or your own name (see custom bucket)
Location	Same region as BigQuery (e.g. `europe-west4`)
Storage class	Standard
Public access	Uniform — not public

Step 2 — Grant the service account access

The BigQuery service account stored in Interact is also used to access GCS — no new credentials needed. Grant the service account the following role on the MMM bucket:

roles/storage.objectAdmin

Find the service account email

In Interact, go to Settings → Connectors, open the BigQuery connector, and copy the service account email shown in the credentials.Alternatively, open the JSON credentials file — the client_email field contains the address.

Open bucket permissions in Google Cloud

Go to console.cloud.google.com, navigate to Cloud Storage → Buckets, click on your MMM bucket, and open the Permissions tab.

Add the role

Click Grant access, paste the service account email, select the role Storage Object Admin (roles/storage.objectAdmin), and save.

If this role is missing, the Model Results and Scenario Planning pages will fail to list or load any artifacts and show a storage permission error.

Step 3 — Configure MMM in Interact

Open Insights → Settings → MMM. Only organization admins can change these settings.

Model results storage

The top of the settings page shows which bucket Interact reads from, and reminds you which role the service account needs on it.

Field	Required	Description
Use a custom bucket	No	Turn on to use a bucket other than the default `{client}-turntwo-mmm` — for example when that name is already taken, or when the client already has an MMM bucket.
Bucket name	When the switch is on	The bucket to use. 3–63 characters: lowercase letters, numbers, dots, dashes and underscores, starting and ending with a letter or number.

Labels

Add one label per market or model with Add country / label. Each label has:

Field	Required	Description
Label / country	No	Identifier shown in the selectors (e.g. `NL`, `Germany`). Leave blank for single-market configs.
Results folder	No	Folder in the bucket that holds the `model_*.json` artifacts. Defaults to `{label}/results`, or `results` when there is no label.
Scenarios folder	No	Folder in the bucket that holds the `scenario_planner_*.json` artifacts. Defaults to a `scenarios` folder next to the results folder — `NL/results` becomes `NL/scenarios`.
Data Book	—	On by default. Turn off to show model results and scenarios only, without a BigQuery Data Book for this label.

Both folder fields show their default as a placeholder. Leave them empty to use the default, or type a path to override it.

Data Book fields

These fields only appear, and are only required, when Data Book is on for a label.

Field	Required	Description
Project	Yes	Google Cloud project ID that contains the BigQuery table
Dataset	Yes	BigQuery dataset name
Table	Yes	Main MMM input table (one row per day, channels as columns)
Final table	No	Optional adjusted version of the input table, in the same project and dataset
Date column	Yes	Column name containing the date per row (e.g. `date`)
Excluded columns	No	Comma-separated columns to hide from the Data Book view (e.g. country codes)

Use Validate table after entering your BigQuery details to confirm Interact can connect and read the table before saving.

When Data Book is off for every label, the Data Book page is hidden from the MMM menu and opening it takes you to Model Results.

Who can see MMM

All members of the organization can open the Data Book, Model Results and Scenario Planning pages. When MMM is turned off in Insights → Settings, these pages are unavailable for everyone; admins are taken to the settings page instead.

Step 4 — Run the pipeline and publish results

Run your Meridian Python pipeline. Make sure its GCS bucket setting (gcs_bucket in the pipeline config) matches the bucket shown in the MMM settings. After training completes, the pipeline should export:

gs://{bucket}/{results_folder}/model_{timestamp}.json
gs://{bucket}/{scenarios_folder}/scenario_planner_{timestamp}.json

Where:

{bucket} is the bucket from Step 1 (or your custom bucket)
{results_folder} and {scenarios_folder} match what you configured in Step 3 (or their defaults)
{timestamp} is a string in YYYYMMDD_HHMMSS format, e.g. 20260511_112201

That’s all. The next time anyone opens the Model Results or Scenario Planning page, Interact will automatically discover the files and display them. No registration step is needed.

Folder structure examples

Examples for the organization Acme, using the default bucket acme-turntwo-mmm:

Config	Results path	Scenarios path
Label = `NL`	`NL/results/model_20260511_112201.json`	`NL/scenarios/scenario_planner_20260511_112201.json`
Label = `DE`	`DE/results/model_20260511_112201.json`	`DE/scenarios/scenario_planner_20260511_112201.json`
No label (single market)	`results/model_20260511_112201.json`	`scenarios/scenario_planner_20260511_112201.json`
Results folder = `clients/acme/nl/results`	`clients/acme/nl/results/model_20260511_112201.json`	`clients/acme/nl/scenarios/scenario_planner_20260511_112201.json`
Scenarios folder = `planning/nl`	Default for the label	`planning/nl/scenario_planner_20260511_112201.json`

Results artifact format

The pipeline must produce a valid JSON file. See the sections below for the full schema your pipeline should follow.

meta — run metadata

Field	Type	Description
`model_timestamp`	string	`YYYYMMDD_HHMMSS` — must match the filename
`data_book_label`	string	Market label; empty string `""` for single-book configs
`start_date`	string	ISO date of the first observation
`end_date`	string	ISO date of the last observation
`kpi_type`	`"revenue"` \| `"non_revenue"`	Type of KPI being modelled
`kpi_label`	string	Human-readable KPI name shown in the UI
`n_observations`	integer	Total number of rows in the training dataset
`pipeline_version`	string	Semver version of the pipeline (e.g. `"1.2.0"`)

All fields are required.

health — Meridian diagnostic checks

Field	Type	Description
`score`	float	Composite health score (0–100)
`overall_status`	string	`"PASS"` or `"FAIL"`
`convergence.max_rhat`	float	Highest R-hat value across all parameters
`convergence.max_parameter`	string	Name of the parameter with the highest R-hat
`convergence.status`	string	`"PASS"` when `max_rhat < 1.05`
`negative_baseline.probability`	float	Posterior probability of baseline going negative
`negative_baseline.status`	string	`"PASS"` when probability ≈ 0
`bayesian_ppp.value`	float	Bayesian posterior predictive p-value (0–1)
`bayesian_ppp.status`	string	`"PASS"` when value is not extreme
`goodness_of_fit.r2`	float	Overall R²
`goodness_of_fit.mape`	float	Overall MAPE (%)
`goodness_of_fit.wmape`	float	Overall wMAPE (%)
`goodness_of_fit.r2_train`	float	Training R²
`goodness_of_fit.mape_train`	float	Training MAPE (%)
`goodness_of_fit.wmape_train`	float	Training wMAPE (%)
`goodness_of_fit.r2_test`	float	Hold-out R²
`goodness_of_fit.mape_test`	float	Hold-out MAPE (%)
`goodness_of_fit.wmape_test`	float	Hold-out wMAPE (%)
`goodness_of_fit.status`	string	`"PASS"` when fit metrics are acceptable
`roi_consistency.status`	string \| null	Optional check — `null` when not computed
`roi_consistency.channels`	object	Per-channel detail if the check was run
`prior_posterior_shift.status`	string \| null	Optional check — `null` when not computed
`prior_posterior_shift.no_shift_channels`	string[]	Channels with no detected prior/posterior shift

All fields are required. Optional checks (roi_consistency, prior_posterior_shift) must still be present with status: null and empty collections when not computed.

predictive_accuracy — hold-out metrics

Field	Type	Description
`r2_train`	float	R² on training set
`r2_test`	float	R² on hold-out test set
`mape_train`	float	Mean Absolute Percentage Error on training set (%)
`mape_test`	float	MAPE on test set (%)
`wmape_train`	float	Weighted MAPE on training set (%)
`wmape_test`	float	Weighted MAPE on test set (%)

All fields are required.

fit_series — time-series fit data

All arrays must be the same length (n_observations).

Field	Type	Description
`dates`	string[]	ISO date strings, one per observation
`actual`	float[]	Observed KPI values
`expected`	float[]	Model-fitted KPI values
`baseline`	float[]	Baseline (non-media) KPI contribution per period

channels — per-channel results

The channels object contains one entry per channel (keys matching channels_order). Each entry:Required fields:

Field	Type	Description
`spend`	float \| null	Total spend over the modelling period; `null` when spend data is not available in the artifact
`incremental_outcome`	float	Total incremental KPI attributed to this channel
`pct_contribution`	float	Share of total KPI (0–1)
`roi`	float	Return on investment (`outcome / spend`)
`mroi`	float	Marginal ROI at the observed spend level
`cpik`	float	Cost per incremental KPI unit
`response_curve.spend_grid`	float[]	Strictly increasing spend values
`response_curve.outcome_grid`	float[]	Outcome at each spend level (same length)

Optional fields:

Field	Type	Description
`adstock_alpha`	float \| null	Geometric decay rate (0–1)
`adstock_max_lag`	integer \| null	Memory window in periods
`saturation_ec50`	float \| null	Hill saturation EC50 parameter
`saturation_slope`	float \| null	Hill slope parameter
`credible_interval.lower`	float[]	5th-percentile response curve
`credible_interval.upper`	float[]	95th-percentile response curve

Validation rules:

spend_grid must be strictly increasing
spend_grid.length === outcome_grid.length
If credible_interval is present, lower and upper must have the same length as spend_grid
Recommend 10–20 grid points for a smooth curve in the UI

Troubleshooting

Symptom	Likely cause	Fix
Model Results page shows “No model results available”	No `model_*.json` files found in the configured folder	Check the pipeline ran and the GCS path matches the configured Results Folder
Page shows a storage permission error	SA missing `roles/storage.objectAdmin`	Add the role on the MMM bucket in the client’s GCP project
Page shows a “bucket does not exist” error	Interact is looking at a different bucket than the pipeline writes to	Compare the bucket shown in Insights → Settings → MMM with the pipeline’s `gcs_bucket`; set a custom bucket if needed
Scenario Planning shows “No scenario artifacts available”	No `scenario_planner_*.json` files in the scenarios folder	Check the pipeline’s scenario export path matches the Scenarios folder in the settings
”Failed to decrypt service account credentials”	KMS issue	Check `GOOGLE_PROJECT_ID` and `GOOGLE_CREDENTIALS` environment variables on the server
Validation error: “spend_grid must be strictly increasing”	Pipeline export bug	Fix the response curve export in the Python pipeline
”No BigQuery connector configured”	Connector not set up or deleted	Re-add a BigQuery connector in Settings → Connectors
Data Book shows no columns	Wrong dataset/table reference	Use Validate Table in the MMM settings to confirm the table is accessible

Agents

Marketing

Intelligence

Teamwork

Workspace

Deprecated

Prerequisites

Step 1 — Create the GCS bucket

Step 2 — Grant the service account access

Step 3 — Configure MMM in Interact

Model results storage

Labels

Data Book fields

Who can see MMM

Step 4 — Run the pipeline and publish results

Folder structure examples

Results artifact format

Troubleshooting

​Prerequisites

​Step 1 — Create the GCS bucket

​Step 2 — Grant the service account access

​Step 3 — Configure MMM in Interact

​Model results storage

​Labels

​Data Book fields

​Who can see MMM

​Step 4 — Run the pipeline and publish results

​Folder structure examples

​Results artifact format

​Troubleshooting

Prerequisites

Step 1 — Create the GCS bucket

Step 2 — Grant the service account access

Step 3 — Configure MMM in Interact

Model results storage

Labels

Data Book fields

Who can see MMM

Step 4 — Run the pipeline and publish results

Folder structure examples

Results artifact format

Troubleshooting