> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AXE key setup in GAM

> Register the three custom-targeting keys your storefront needs in Google Ad Manager so Scope3-signalled buys can traffic against your inventory

Buyers using Scope3 audience segments target your inventory through three GAM custom-targeting keys. This page covers what to create in Google Ad Manager and what Murph will help you confirm.

## What the three keys do

| Key                                        | What it carries                                    | Used for                                                            |
| ------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------- |
| **Include** (conventionally named `axei`)  | Segment IDs the impression *is* eligible for       | Line-item targeting includes a value                                |
| **Exclude** (conventionally named `axex`)  | Segment IDs the impression is *excluded from*      | Line-item negative targeting                                        |
| **Emissions macro** (must be named `axem`) | A serve-time emissions token minted per impression | Substituted into creative tracking pixels for emissions attribution |

<Note>
  The **emissions macro key must be named literally `axem`** in your GAM network. The include and exclude key names are conventional — Scope3 recommends `axei` and `axex`, and Scope3-provisioned networks ship with those names — but your ad server source settings let you point at whatever names your GAM network uses.
</Note>

## How the keys connect to your ad stack

The three keys exist so a live buy can carry Scope3 signals into your GAM at request time. Two ends of the flow, both required:

**Publisher side — writes the values.** The **Scope3 Prebid RTD provider** runs in your header-bidding stack, calls Scope3's real-time data endpoint on every ad request, and writes the returned values into the GAM ad request as custom-targeting parameters — segment IDs under `axei` / `axex`, the emissions token under `axem`. Without this module installed, the keys exist in GAM but nothing ever populates them, and every Scope3-signalled line item will miss.

**Ad-server side — reads them.**

* **`axei` / `axex`:** GAM line items target on these keys the same way they target on any custom-targeting key-value. The Scope3 ESA writes those targeting rules onto the line items it traffics into your GAM — you don't hand-edit them.
* **`axem`:** the emissions macro key rides through the creative Scope3 serves. When the ESA uploads a creative, it substitutes `%%PATTERN:axem%%` into the impression pixel URLs, and GAM fills that at serve time with whatever value `axem` carried on the ad request. That's how the emissions token reaches Scope3 measurement.

Setting up the keys in GAM (what Murph handles below) is only half the story — the RTD module on the publisher side has to be installed too, or every buy will miss.

## Why `axem` is name-locked

Every creative Scope3 serves through your GAM contains a `{AXEM}` placeholder in its tracking pixels. When the creative is uploaded, the ad server source rewrites `{AXEM}` to the GAM creative macro `%%PATTERN:axem%%`, and GAM substitutes it at serve time with the value of the custom-targeting key **literally named `axem`** from that ad request. Renaming the key breaks emissions attribution silently — the placeholder never resolves and no emissions token travels with the impression.

The include and exclude keys don't have this constraint because line-item targeting resolves by key ID, not by name — the source looks up whichever name you declare in its settings and uses the ID.

## Setup — recommended path

**Ask Murph. That's the whole path.**

During storefront setup, Murph checks your GAM network for the three keys and handles whatever's needed:

* **All three keys already exist** — Murph presents the candidates it found, you confirm, Murph saves the mapping. Done.
* **Some or all keys are missing** — Murph offers to create them for you with the recommended names (`axei` / `axex` / `axem`, display names Scope3 Inclusion / Exclusion / Emissions, FREEFORM, reportable on). On your confirm, Murph creates them via the GAM API and immediately saves the mapping.

Only the emissions macro key must be named literally `axem` (see the section above for why). For include and exclude, you can override the names during the confirm step if your GAM already uses a different naming convention.

## Setup — manual path (fallback)

Use this only if Scope3's service account on your GAM network doesn't have `CustomTargetingKey.write` permission — Murph will tell you when that happens.

In Google Ad Manager: **Admin → Custom Targeting → New key**. Create three:

| Field            | `axei`                                                     | `axex`                                                     | `axem`                           |
| ---------------- | ---------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------- |
| **Key name**     | `axei` *(or any name your source settings will reference)* | `axex` *(or any name your source settings will reference)* | `axem` *(mandatory)*             |
| **Display name** | `Scope3 Inclusion Segments` (recommended)                  | `Scope3 Exclusion Segments` (recommended)                  | `Scope3 Emissions` (recommended) |
| **Value type**   | `FREEFORM`                                                 | `FREEFORM`                                                 | `FREEFORM`                       |
| **Reportable**   | On (recommended)                                           | On (recommended)                                           | On (recommended)                 |

`FREEFORM` is required. Scope3 segment IDs are minted dynamically per buy — enumerating them as `PREDEFINED` values ahead of time is unworkable.

You only create the three key entities once. Values under each FREEFORM key materialize automatically when the ad server source traffics a line item that references them.

After creating the keys manually, come back to chat and ask Murph to refresh — it'll pick up the new keys and save the mapping.

## Connect the publisher side

Everything above sets up **our side** of the pipe. Your side — the Scope3 Prebid RTD provider — has to be installed in your header-bidding stack so it can write values to `axei` / `axex` / `axem` on each ad request. Skip this and every Scope3-signalled line item will miss even though the mapping is saved.

<Note>
  **This step is on you, and we can't verify it from our side.** The "AXE
  Segment Keys" setup task clears the moment the mapping is saved on the
  ESA — Scope3 has no visibility into whether your Prebid.js is actually
  calling our RTD endpoint. If your line items report zero impressions
  from Scope3-signalled buys after everything else looks green, this is
  the first thing to check.
</Note>

### Prebid.js (supported)

Add the `scope3RtdProvider` module to your Prebid.js build and configure it with your Scope3 `orgId` and `authKey`. The module defaults its targeting-key names to `axei` / `axex` / `axem`, so if you accepted Murph's recommended names during setup there is nothing extra to configure. If you overrode any include/exclude names, pass them in the module config's `includeKey` / `excludeKey` so the module writes to the keys you actually created.

Minimum config:

```js theme={null}
pbjs.setConfig({
  realTimeData: {
    dataProviders: [{
      name: 'scope3',
      params: {
        orgId: '<your Scope3 orgId>',
        authKey: '<your Scope3 authKey>',
        // includeKey: 'my_include_name',   // only if you overrode
        // excludeKey: 'my_exclude_name',   // only if you overrode
      },
    }],
  },
});
```

The full install guide (module load, orgId provisioning, verification steps) lives with the Scope3 partner docs — ask Scope3 for the current partner-setup link, or ask Murph and it will pull it up.

### Prebid Server (not yet supported)

A Scope3 RTD module exists in `prebid/prebid-server`, but it currently uses different key names (`scope3_include` / `scope3_macro`) and doesn't handle the exclude signal. Because Scope3's storefront tooling downstream (the ESA's creative-macro substitution, the AXE keys endpoint) is aligned on `axei` / `axex` / `axem`, a prebid-server-based publisher can't complete the storefront setup end-to-end today. Work to reconcile prebid-server with the same names and add the exclude branch is in progress — talk to Scope3 if you're operating a prebid-server stack and need a timeline.

## Troubleshooting

**The setup task shows 0/3 configured, but the keys exist in GAM.**
The three names haven't been declared on the ad server source. Ask Murph to look them up and confirm — it'll find them and save the mapping.

**Murph can't create the keys automatically ("permission denied").**
Scope3's service account on your GAM network doesn't have the `CustomTargetingKey.write` scope. Grant a role that includes it (Trafficker or an equivalent least-privilege custom role — same grant used to create advertisers), or use the manual path above.

**Murph can't find the keys in the GAM network.**
The custom-targeting sync from your GAM hasn't picked them up yet. Confirm the keys exist in GAM (Admin → Custom Targeting), then trigger a sync — Murph can do this with `refresh_esa`. Retry after the sync completes.

**Emissions data is missing on served impressions even though `axem` is configured.**
Verify the GAM key is named literally `axem` (not `axe_macro` or another variant). The GAM creative macro `%%PATTERN:axem%%` only resolves against a key of that exact name.

**A buyer's segment isn't targeting my inventory.**
Confirm the include key exists in GAM and is `FREEFORM`, and that the segment ID appears in the GAM ad request as a value on that key. The Scope3 Prebid RTD module writes segment IDs into the include key at request time — if the module isn't installed or your `orgId` isn't registered in RTDP, no segment values reach GAM.

**Setup task cleared but no Scope3 targeting is happening on served buys.**
The mapping is saved on the ESA but the publisher-side RTD module isn't populating the keys at request time. Confirm the `scope3RtdProvider` module is installed in your Prebid.js build (see "Connect the publisher side" above). If the module is installed but the include/exclude names in your Prebid.js config disagree with the names you saved on the ESA, the module writes to one set of keys and GAM line-item targeting reads from another — align them.

**I run Prebid Server, not Prebid.js.**
Scope3 storefront setup for prebid-server publishers isn't supported end-to-end yet — see "Prebid Server (not yet supported)" above. Reach out to Scope3 for the current status if you need to integrate over that stack.

## Related

<CardGroup cols={2}>
  <Card title="TMP overview" icon="tower-broadcast" href="/v2/storefront/tmp/overview">
    How your storefront gets buyer signals at request time — the layer that populates the include/exclude/macro values.
  </Card>

  <Card title="Signal components" icon="wave-pulse" href="/v2/storefront/esa/signals">
    Create additional signal components on your ad server source.
  </Card>
</CardGroup>