createBrowserTracker()

The browser tracker. Captures Google Ads click identifiers from the URL on initialization, persists them to first-party cookies (gated on consent), and exposes methods to fire conversions and events through window.gtag.

Signature

import { createBrowserTracker } from '@trackbridge/browser';

function createBrowserTracker(config: BrowserTrackerConfig): BrowserTracker;

`BrowserTrackerConfig`

type BrowserTrackerConfig = {
  adsConversionId: string;
  ga4MeasurementId?: string;
  /** Default: 'off'. */
  consentMode?: 'v2' | 'off';
  /** Default: 'cookie'. */
  clickIdentifierStorage?: 'cookie' | 'memory' | 'none';
  cookieDomain?: string;
  /** Default: 90. */
  cookieExpiryDays?: number;
  debug?: boolean;
  io?: BrowserIO;
};

Field	Required	Notes
`adsConversionId`	yes	The Google Ads property of the form `AW-XXXXXXXXX`. Used to construct `send_to` on every conversion event.
`ga4MeasurementId`	no	The GA4 property of the form `G-XXXXXXXXXX`. Required if you’ll call `tracker.trackEvent`.
`consentMode`	no, default `'off'`	When `'v2'`, click-identifier cookies are gated on `ad_storage` consent. Pre-grant values are held in memory.
`clickIdentifierStorage`	no, default `'cookie'`	`'cookie'` persists across sessions; `'memory'` lasts until tab close; `'none'` discards captured values immediately.
`cookieDomain`	no	Optional `Domain=` attribute for the `_tb_*` cookies — set to `.example.com` to share across subdomains.
`cookieExpiryDays`	no, default `90`	Lifetime of the `_tb_*` cookies.
`debug`	no, default `false`	When `true`, gtag exceptions are surfaced via `console.warn`. The auto-`transactionId` warning fires regardless of this flag.
`io`	no	Test seam for overriding URL reads, cookie reads/writes, gtag pushes, and `transactionId` generation. You’ll only set this in tests.

Returns

type BrowserTracker = {
  getClickIdentifiers(): ClickIdentifiers;
  updateConsent(update: ConsentUpdate): void;
  trackEvent(input: BrowserEventInput): Promise<void>;
  trackConversion(input: BrowserConversionInput): Promise<void>;
};

See:

Behavior on initialization

Reads window.location.search for gclid, gbraid, and wbraid.
Reads document.cookie for the corresponding _tb_* cookies.
Merges both sources — URL values win on conflict.
If clickIdentifierStorage === 'cookie' and consentMode === 'off' (or ad_storage is already 'granted'), writes cookies for any captured values immediately.
If clickIdentifierStorage === 'cookie' and consent is unknown or denied, holds the captured values in memory; they will be persisted later if updateConsent({ ad_storage: 'granted' }) is called.

Errors

Throws synchronously at init if adsConversionId is missing or empty:

Error: [trackbridge] adsConversionId is required

After initialization, the tracker never throws on network or gtag failures. Failures are reported via console.warn if debug: true.

Example

import { createBrowserTracker } from '@trackbridge/browser';

export const tracker = createBrowserTracker({
  adsConversionId: process.env.NEXT_PUBLIC_GOOGLE_ADS_CONVERSION_ID!,
  ga4MeasurementId: process.env.NEXT_PUBLIC_GA4_MEASUREMENT_ID!,
  consentMode: 'v2',
  cookieDomain: '.example.com',
  debug: process.env.NODE_ENV !== 'production',
});