Quick Integration¶

This guide shows the minimal steps to install the tag, record page events, and send conversions.

Tag ID format¶

• adv_001 is only an example.
• tag_id accepts any non-empty string.
• If omitted on collect, server derives site:<host> (for example site:shop.example.com), so avoid using the site: prefix for your own IDs.
• Recommended convention: adv_<name_slug>_<random> (example: adv_acme_store_3k9p7tq4).

Generate one with the helper script:

cd ad_server
make tag-id-generate name="Acme Store"

1) Install the tag¶

Add the script to your site and point it at your hosted bundle. The tag sends events to https://events.thrad.ai and does not require a config step.

Choose one install pattern below.

1a) Quick and easy¶

Use a normal script tag, then call thradTag right after it loads.

<script src="https://cdn.thrad.ai/tag.min.js"></script>
<script>
  window.thradTag("set", {
    tag_id: "adv_001",
    channel: "web",
  });
  window.thradTag("event", "page_view");
</script>

1b) Async + queue bootstrap (recommended)¶

Use this if you want non-blocking script load and safe early calls before tag.min.js has finished loading.

<script>
  window.thradTag =
    window.thradTag ||
    function () {
      (window.thradTag.q = window.thradTag.q || []).push(arguments);
    };
  window.thradTag.q = window.thradTag.q || [];

  window.thradTag("set", {
    tag_id: "adv_001",
    channel: "web",
  });
  window.thradTag("event", "page_view");
</script>
<script async src="https://cdn.thrad.ai/tag.min.js"></script>

1c) Dynamic loader¶

Use this when your site injects tags programmatically.

<script>
  (function (w, d, n, s, src) {
    w[n] =
      w[n] ||
      function () {
        (w[n].q = w[n].q || []).push(arguments);
      };
    w[n].q = w[n].q || [];
    var t = d.createElement(s);
    t.async = 1;
    t.src = src;
    var y = d.getElementsByTagName(s)[0];
    y.parentNode.insertBefore(t, y);
  })(window, document, "thradTag", "script", "https://cdn.thrad.ai/tag.min.js");

  window.thradTag("set", {
    tag_id: "adv_001",
    channel: "web",
  });
  window.thradTag("event", "page_view");
</script>

2) Set shared settings once (recommended)¶

Set shared identifiers/defaults once after load (or in the queue), then emit events without repeating the same keys every time.

<script>
  window.thradTag("set", {
    tag_id: "adv_001",
    channel: "web",
    campaign_id: "spring_2026",
  });
</script>

3) (Optional) Sync impression link for view-through¶

If you support view-through attribution, call linkImpression() once after the tag loads. This reads the 3P impression cookie (when the browser allows it) and stores it first-party on the advertiser domain.

<script>
  if (typeof window.thradTag?.linkImpression === "function") {
    window.thradTag.linkImpression();
  }
</script>

4) Track events (collect)¶

Use event to send any site interaction. The tag posts to https://events.thrad.ai/v1/collect and includes page/referrer/user-agent data automatically.

<script>
  window.thradTag("event", "page_view", {
    page_url: window.location.href,
  });
</script>

Common event examples¶

Product view

<script>
  window.thradTag("event", "product_view", {
    product_id: "sku_123",
    name: "Jet Black Tee",
    price: 29.0,
    currency: "USD",
  });
</script>

Add to cart

<script>
  window.thradTag("event", "add_to_cart", {
    product_id: "sku_123",
    quantity: 2,
    value: 58.0,
    currency: "USD",
  });
</script>

Checkout start

<script>
  window.thradTag("event", "begin_checkout", {
    cart_id: "cart_abc",
    value: 120.0,
    currency: "USD",
    items: [
      { product_id: "sku_123", quantity: 2, price: 29.0 },
      { product_id: "sku_456", quantity: 1, price: 62.0 },
    ],
  });
</script>

Optional event fields you can include¶

• event_id - use if you want dedupe for retries
• timestamp - unix seconds if you want to override client time
• tag_id/send_to - override the default target set by thradTag("set", ...)
• page_url, referrer, user_agent - override auto-captured values
• params - free-form object for anything else you want to store

Attribution fields (auto-attached when available)¶

When the tag has stored attribution data, it will include it automatically:

• click_id (from the redirect token)
• impression_id (from impression link sync)
• bid_id (from redirect token or impression link)

5) Track conversions¶

The tag captures thrad_click_id, thrad_exp, and thrad_sig from the landing URL and stores them. You only need to pass the order details.

<script>
  window.thradTag("conversion", {
    order_id: "order_123",
    value: 99.99,
    currency: "USD",
  });
</script>

Required fields sent by the tag:

• click_id, exp, sig (captured from the landing URL)
• order_id
• event_ts (set automatically to current time)

Optional fields:

• tag_id/send_to - override the default target set by thradTag("set", ...)
• page_url, referrer, user_agent, event_id, client_id

6) View-through conversions¶

If you want view-through attribution, send a view conversion. The tag uses the stored impression_id (from linkImpression()) if you don't pass it explicitly.

<script>
  window.thradTag("view_conversion", {
    order_id: "order_123",
    value: 99.99,
    currency: "USD",
  });
</script>

Required fields:

• order_id
• event_ts (set automatically to current time)
• impression_id (if not stored from link sync)

7) Server-side conversions¶

7a) Signed click-token flow (compatible with tag click params)¶

If the tag cannot run (e.g., Stripe Checkout), capture the click params on your landing page and store them with the order/session. When the payment completes, send a server-to-server request to:

POST https://events.thrad.ai/v1/conversion
{
  "click_id": "from_landing",
  "exp": 1737480000,
  "sig": "from_landing",
  "order_id": "order_123",
  "event_ts": 1737480050,
  "value": 99.99,
  "currency": "USD",
  "page_url": "https://example.com/thank-you"
}

7b) API-key flow (partner S2S integrations)¶

For backend-to-backend partner integrations, use:

POST https://events.thrad.ai/v1/api/conversion
Authorization: Bearer <partner_api_key>
{
  "click_id": "from_redirect_or_partner_tracking",
  "conversion_time": "2026-02-19T18:00:00Z",
  "conversion_value": 99.99,
  "currency": "USD",
  "order_id": "order_123"
}

Legacy alias: POST /v1/partner/conversion.

For view-through server-side conversions:

POST https://events.thrad.ai/v1/view-conversion
{
  "impression_id": "from_link_sync",
  "order_id": "order_123",
  "event_ts": 1737480050,
  "value": 99.99,
  "currency": "USD",
  "page_url": "https://example.com/thank-you"
}

8) Verify it worked¶

• In the browser: confirm the network request to https://events.thrad.ai/v1/collect and https://events.thrad.ai/v1/conversion.
• On the server: check your database for new rows in clicks and events.