Quick Integration¶

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

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.