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

# GTM integration

> Install the Thrad Tag and fire events via Google Tag Manager. The path most advertisers use.

If you already use Google Tag Manager, this is the easiest path. You'll create **one loader tag** plus event tags for the actions you want to track. Your site must expose completed order/submission values in its data layer.

## 1. Install the Thrad loader (once)

In GTM, create a **Custom HTML** tag called `Thrad — Loader` and paste this. Set the trigger to **All Pages**, and **firing priority** to a high value (e.g. `100`) so the loader runs before any event tag below.

```html theme={null}
<script>
  window.thradTag = window.thradTag || function () {
    (window.thradTag.q = window.thradTag.q || []).push(arguments);
  };
  window.thradTag("set", {
    tag_id: "<YOUR_TAG_ID>",
    channel: "web"
  });
</script>
<script async src="https://cdn.thrad.ai/tag.min.js"></script>
```

Replace `<YOUR_TAG_ID>` with the tag ID Thrad sent you (`adv_<name>_<id>`).

For attributed visits, page views and dwell time are [tracked automatically](https://docs.thrad.ai/advertisers/attribution/tag/events.md). Follow your existing measurement-consent setup; installing a loader alone does not verify a completed purchase.

For an existing **Custom Image** installation, use the
[image-pixel URL and cache-buster guidance](https://docs.thrad.ai/advertisers/attribution/tag/image-pixel.md).
Its Image URL must contain `tag_id=<YOUR_TAG_ID>`, supported event/data fields
and individually encoded values. A fired image tag or GIF response is not proof
that Thrad stored the event.

## 2. Track custom events

For each event you want to track, create a **Custom HTML** tag in GTM, attach it to the trigger that matches the action (the dataLayer event your theme already emits, a click trigger, a form submit, etc.), and paste a snippet like the ones below.

`{{DLV - …}}` references in the snippets are GTM Data Layer Variables — replace them with the variables you've set up in your container (or hard-code values if you prefer).

### Items added to cart

```html theme={null}
<script>
  window.thradTag("event", "items_added", {
    content_id: {{DLV - ecommerce.items.0.item_id}},
    quantity:   {{DLV - ecommerce.items.0.quantity}},
    value:      {{DLV - ecommerce.value}},
    currency:   {{DLV - ecommerce.currency}}
  });
</script>
```

### Checkout started

```html theme={null}
<script>
  window.thradTag("event", "checkout_started", {
    value:    {{DLV - ecommerce.value}},
    currency: {{DLV - ecommerce.currency}}
  });
</script>
```

### Lead created (form submission)

```html theme={null}
<script>
  window.thradTag("event", "lead_created", {
    event_id: {{DLV - lead_submission_id}},
    form_id: {{DLV - form_id}}
  });
</script>
```

### Registration completed (signup)

```html theme={null}
<script>
  window.thradTag("event", "registration_completed", {
    event_id: {{DLV - registration_submission_id}}
  });
</script>
```

Fire these tags after a successful submission. Set each submission variable to
its stable opaque ID. Reuse that ID for another callback for the same submission;
use a different ID for a different submission. Leads and signups do not require
an order ID, purchase value or currency. Do not invent those fields. For OpenAI
measurement, the configured event map must map these names to `lead_created`
and `registration_completed`; aliases such as `lead` and `signup` need their own
matching mappings. See [general-event identity](https://docs.thrad.ai/advertisers/attribution/tag/events.md#leads-and-signups).

See the full list of standard events in [Track events](https://docs.thrad.ai/advertisers/attribution/tag/events.md). Custom event names are accepted — just call `thradTag("event", "<any_name>", { … })`.

## 3. Track conversions

Create a **Custom HTML** tag called `Thrad — Conversion`. Trigger it on the **order confirmation / thank-you page only** — either by URL match (`Page URL contains /order-confirmation`) or on the GTM `purchase` dataLayer event.

```html theme={null}
<script>
  window.thradTag("conversion", {
    order_id: {{DLV - ecommerce.transaction_id}},
    value:    {{DLV - ecommerce.value}},
    currency: {{DLV - ecommerce.currency}}
  });
</script>
```

Purchases require a final stable `order_id`, a nonnegative total `value` in major
currency units and a three-letter `currency`. An `event_id` cannot replace the
order ID. The tag supplies the timestamp and captured source context:

* Signed Thrad links carry `thrad_click_id`, `exp` and `sig` on the landing URL.
* OpenAI traffic carries referral context such as `oppref`; it does not need a fabricated Thrad signature.
* Mixed traffic retains both sources. Invalid signed fields cannot be bypassed by an OpenAI reference.

An organic visit with no supported attribution context is not submitted by this
attributed-event tag. The browser `conversion` command sends a canonical purchase
to `/v1/collect`; the direct legacy `/v1/conversion` endpoint has its own signed
contract. See [purchase fields and outcomes](https://docs.thrad.ai/advertisers/attribution/tag/conversions.md).

> **Where to fire it** Submit confirmed purchases only. Repeat callbacks use the
> same canonical identity for the configured tag and final order. Do not use a
> cart/checkout ID, generate a new ID on every render, or add a second purchase tag.

For an existing setup, update its purchase tag instead of creating a duplicate.
If a server sender also reports purchases, coordinate its canonical IDs and
historical order mapping with Thrad before cutover; see
[browser/server migration](https://docs.thrad.ai/advertisers/attribution/tag/conversions.md#using-the-browser-tag-and-server-to-server-capi-together).

## 4. Verify delivery

In GTM Preview, confirm one loader and the intended completed-action trigger.
Check the outgoing purchase request contains the real final order, value and
currency, then inspect the collector receipt. A fired GTM tag or HTTP 2xx alone
is not proof of stored attribution. Temporary network/429/5xx failures have at
most three attempts; permanent rejection stops. Follow the
[delivery troubleshooting](https://docs.thrad.ai/advertisers/attribution/tag/conversions.md#delivery-outcomes)
steps before repeating a failed purchase.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.