> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.leadtruffle.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Widget attribution tracking and the manual attribution API

# Widget attribution tracking and the manual attribution API

*Capture UTM and ad click data automatically from your LeadTruffle widgets, or push values manually with setAttribution for advanced installs.*

LeadTruffle's JavaScript widgets automatically capture marketing attribution and page context whenever a visitor submits a lead — UTM parameters, ad click IDs, page URL, referrer, and more. Most businesses don't need to set anything up. This guide explains what gets captured, how it works, where to find it, and how agencies or developers can push attribution manually when needed.

---

## Table of contents

* [Overview](#2-overview)
* [What gets captured](#2-what-gets-captured)
* [How automatic attribution works](#2-how-automatic-attribution-works)
* [Google Ads cookie fallback](#2-google-ads-cookie-fallback)
* [Pushing attribution manually](#2-pushing-attribution-manually)
* [Supported widgets and fields](#2-supported-widgets-and-fields)
* [Where attribution shows up in LeadTruffle](#2-where-attribution-shows-up-in-leadtruffle)
* [Sending attribution to webhooks and Zapier](#2-sending-attribution-to-webhooks-and-zapier)
* [Troubleshooting](#2-troubleshooting)

---

## Overview

Every time a visitor submits a lead through a LeadTruffle JavaScript widget, the widget records where that lead came from — the ad campaign, the search click, the page they were on, and more. This is called **attribution**.

You can use attribution to see which ads and campaigns are actually producing leads, send that data into your CRM, and report on revenue by source.

|| Most customers need zero setup. If your widget is installed and your ads use UTM tags or click IDs, attribution is captured automatically. The manual setup later in this article is only for advanced installs with a tag manager or developer.

---

## What gets captured

When a lead is submitted, the widget collects whatever tracking values are available, including:

* **Campaign details** — UTM source, medium, campaign, term, and content
* **Ad click IDs** — Google, Meta, Microsoft, TikTok, Snapchat, and more
* **Page context** — page URL, page title, and referrer
* **Analytics IDs** — Google Analytics client/session IDs and the HubSpot user token when present

If none of these values are available for a lead, the attribution section simply won't appear on that lead — lead capture is never blocked.

---

## How automatic attribution works

The widget uses **first-touch attribution**. It remembers where a visitor originally came from, even if they browse to other pages before submitting.

When the widget loads, it:

1. Checks the browser for a recently saved attribution record.
2. If a fresh record exists, it keeps it — this preserves the original first touch.
3. If no record exists, it reads tracking values from the current page URL.
4. If a Google `gclid` isn't in the URL, it tries the Google Ads cookie as a fallback.
5. If it finds any tracking values, it saves them in the browser.

Saved first-touch attribution lasts **7 days**.

When the visitor submits, the widget builds the final attribution in this priority order:

1. Current page URL values win first.
2. Missing fields are filled from the saved first-touch record.
3. A missing `gclid` is filled from the Google Ads cookie.
4. Remaining gaps can be filled from a same-domain referrer URL.

This means a visitor can land on a tagged ad URL, browse to another page, submit from there, and the lead still includes the original campaign data — as long as the widget loaded on that first page and the browser allowed storage.

| The widget only remembers attribution if it loaded on the first tagged landing page. For best results, install the widget on **every** landing page and keep your tracking parameters intact through any redirects.

---

## Google Ads cookie fallback

Google Ads can store click data in a first-party cookie called `_gcl_aw`. If a visitor's `gclid` is no longer in the page URL, the widget can read this cookie as a backup so the Google click ID still makes it onto the lead.

A few things to know:

* A `gclid` in the page URL always wins over the cookie.
* A saved first-touch `gclid` also wins over the cookie.
* The cookie only recovers `gclid` — it does **not** contain UTM fields.
* If the cookie is missing, blocked by a consent tool, or unreadable, the widget just continues without it.

||| Don't rely on the cookie to recover UTM tags. If you need UTMs after a visitor navigates between pages, the widget must load on the first tagged landing page, or you must push the values manually (see below).

---

## Pushing attribution manually

For advanced installs, you can push attribution values directly into the widget using `setAttribution(...)`. This is useful when your site, tag manager, consent manager, or analytics script already has the values and needs to hand them to LeadTruffle before the visitor submits.

|| This section is intended for developers or marketing agencies comfortable editing site code or a tag manager. If that's not you, the automatic capture above already handles most cases.

Call `setAttribution(...)` **after** the widget script loads and **before** the visitor submits the form. Here's the recommended pattern for the Website Texting / Chat Widget:

```js
const script = document.createElement('script')
script.src = 'https://embeds-v1.leadtruffle.com/widget/tooldesk-widget.js'
script.onload = function () {
  window.LTWidget.initialize({
    companyId: 'YOUR_COMPANY_UUID',
  })

  if (window.LTWidget && typeof window.LTWidget.setAttribution === 'function') {
    window.LTWidget.setAttribution({
      gclid: 'GOOGLE_CLICK_ID',
      utm_source: 'google',
      utm_medium: 'cpc',
      utm_campaign: 'spring-service',
    })
  }
}
document.head.appendChild(script)
```

A few important behaviors:

* **It merges, it doesn't replace.** Manual values are added to whatever attribution was already captured. Sending only `gclid` won't wipe out an existing `utm_source`.
* **Manual values can overwrite the same field.** If saved attribution has one `gclid` and you push a new one, the new value is kept.
* **The current page URL still wins at submit time.** If the submission URL contains a `gclid`, that value takes priority over a manually pushed one.
* **Bad input is ignored safely.** Empty strings, non-text values, and unknown fields are dropped — a bad call won't break your page or the lead form.

| Don't use `prefillLead(...)` for attribution. That method is for visible lead fields and custom metadata like name, email, or phone. Always use `setAttribution(...)` for `gclid`, UTMs, and other click IDs.

---

## Supported widgets and fields

Manual attribution works on every current LeadTruffle JavaScript widget. Replace `LTWidget` in the example above with the global for your widget:

| Widget | Global |
| ---- |
| Website Texting / Chat Widget | `window.LTWidget` (legacy alias: `window.Tooldesk`) |
| Webchat Widget | `window.LTWebchat` |
| Pop-Up Widget | `window.TPOPWidget` |
| JavaScript Lead Form | `window.TJSFormWidget` |
| Franchise Widget | `window.FranchiseLeadtruffle` |

||| The legacy **iframe lead form** does not support full attribution tracking or manual injection. If you need attribution, switch to the JavaScript Lead Form widget.

`setAttribution(...)` accepts any of these fields — send only the ones you have:

| Field | What it tracks |
| ---- |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | Campaign details |
| `gclid`, `gbraid`, `wbraid`, `gad_source`, `gclsrc` | Google Ads |
| `fbclid` | Meta (Facebook / Instagram) |
| `msclkid` | Microsoft Ads |
| `ttclid` | TikTok Ads |
| `snapcid` | Snapchat Ads |
| `igshid` | Instagram |
| `srsltid` | Google Search / Shopping |

---

## Where attribution shows up in LeadTruffle

### Lead details

Open any lead on the **Leads** tab and expand **Attribution & Tracking**. You'll see campaign details, ad platform tracking, other tracking IDs, and page context. If no attribution was captured, this section won't appear for that lead.

### Inbox and conversation details

The inbox uses attribution signals to label a lead's source — for example, a lead with a Google click ID can be shown as a Google lead and grouped accordingly.

### Dashboard lead sources

Your lead source analytics turn stored attribution into readable source labels, such as:

* **Google Ads** (from `gclid`, `gbraid`, `wbraid`, or `gad_source`)
* **Meta Ads** (from `fbclid`)
* **TikTok Ads** (from `ttclid`)
* **Microsoft Ads** (from `msclkid`)
* **Snapchat Ads** (from `snapcid`)
* Campaign labels from UTM fields, and referrer labels like **Google Search**, **YouTube**, **Yelp**, **Thumbtack**, or **Angi**

### CSV exports

Lead exports include attribution columns such as Referrer, Submission URL, all UTM fields, GCLID, GBRAID, WBRAID, Google Ads source, IGSHID, GCLSRC, SRSLTID, and GA Client ID.

---

## Sending attribution to webhooks and Zapier

For outgoing webhooks and Zapier, LeadTruffle maps stored attribution into a `trackingData` object. You can map fields like `trackingData.gclid`, `trackingData.utm_source`, and the rest into HubSpot, Google Sheets, your CRM, or an offline conversion step.

```json
{
  "trackingData": {
    "source": "chat-widget",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring-service",
    "gclid": "Cj0KCQ...",
    "ga_client_id": "123456789.987654321",
    "pageInfo": {
      "currentUrl": "https://example.com/services/plumbing",
      "referrer": "https://www.google.com/",
      "title": "Plumbing Services"
    }
  }
}
```

---

## Troubleshooting

### `gclid` is still empty in Zapier or HubSpot

Check each of the following:

1. Was the visitor's landing page URL tagged with `gclid`, `gbraid`, or `wbraid`?
2. Did the LeadTruffle widget load on that landing page?
3. Did the visitor submit within the 7-day saved attribution window?
4. Does the visitor's browser allow local storage for your site?
5. Is the `_gcl_aw` cookie present and readable on the submission page?
6. Is a consent manager blocking ad cookies or widget storage until after submission?
7. Is your site running the current widget version?
8. If pushing values manually, is `setAttribution(...)` called after the widget loads and before submission?

### UTM fields are missing but `gclid` is present

The Google Ads cookie can recover `gclid`, but it never contains UTM fields. To keep UTMs after page navigation, load the widget on the first tagged landing page or push the UTM values with `setAttribution(...)`.

### You want to push values before the widget loads

The widget global must exist before it can receive attribution. Store the values in your own variable, cookie, or data layer first, then call `setAttribution(...)` from the script's `onload` handler.

### You're using the iframe form

The legacy iframe form doesn't support attribution tracking or manual injection. Switch to the JavaScript Lead Form widget.

| When troubleshooting a specific lead with support, it helps to share: the landing page URL from the ad click, the final submission URL, whether the widget loaded on the landing page, the exact widget you're using, and a screenshot or export of the `trackingData`.

---

Need help? Contact us at support@leadtruffle.com or message the team via the chat on this article or in-app.