tracker.trackConversion()

Fires one Google Ads conversion through window.gtag. Normalizes and hashes any userData provided, attaches the _tb_* click identifiers automatically, and uses your transactionId as the dedup key for the matching server-side call.

Signature

tracker.trackConversion(input: BrowserConversionInput): Promise<void>;

BrowserConversionInput

type BrowserConversionInput = {
  label: string;
  value?: number;
  currency?: string;
  transactionId?: string;
  userData?: UserData;
};

type UserData = {
  email?: string;
  phone?: string;
  firstName?: string;
  lastName?: string;
  address?: {
    street?: string;
    city?: string;
    region?: string;
    postalCode?: string;
    country?: string;
  };
};

Field	Required	Notes
label	yes	The gtag conversion label. Combined with adsConversionId to form send_to: '${adsConversionId}/${label}'.
value	no	Conversion value, in your currency. Float.
currency	no	ISO 4217 currency code (e.g. 'USD', 'EUR'). Required by Google when value is set.
transactionId	no — but always pass one	The dedup key. Pass the same string on the matching server-side call. If omitted, the SDK auto-generates tb_<uuid> and warns.
userData	no	Identity fields for enhanced conversions. Pass raw — the SDK normalizes and hashes.

Returns

Promise<void>. Resolves after the gtag push has been queued. Does not wait for Google’s response — gtag is fire-and-forget on the browser side. Errors thrown by gtag are caught and silently swallowed unless debug: true, in which case they’re logged via console.warn.

Behavior

1. If userData is provided, calls window.gtag('set', 'user_data', { ... }) first, with hashed email, phone, firstName, lastName, and address.street, plus plaintext address.city, address.region, address.postalCode, and address.country.
2. Then calls window.gtag('event', 'conversion', { send_to, transaction_id, gclid?, gbraid?, wbraid?, value?, currency? }).
3. Click identifiers are pulled from the tracker’s internal state — whatever was captured from the URL or cookies at init time, plus any updates from updateConsent.

Errors and warnings

If transactionId is missing or empty, the SDK auto-generates one and always emits this warning (regardless of debug):

[trackbridge] ⚠️ trackConversion called without transactionId
  → Auto-generated: tb_<uuid>
  → Dual-send disabled for this call. Pass a transactionId you control
    to enable cross-side dedup.
  → See: trackbridge.dev/docs/dedup

When transactionId differs between the browser and server calls, Google has no way to deduplicate them and counts the conversion twice. See Deduplication & transactionId.

If gtag throws (typically because window.gtag is missing or the page hasn’t loaded gtag.js), the error is caught. With debug: true:

[trackbridge] gtag conversion failed: <error>

Example

app/checkout/success/page.tsx

'use client';
import { useEffect } from 'react';
import { tracker } from '@/lib/tracker.client';

export function FireConversion({ order }: { order: Order }) {
  useEffect(() => {
    tracker.trackConversion({
      label: 'purchase',
      value: order.total,
      currency: order.currency,
      transactionId: order.id,
      userData: {
        email: order.customer.email,
        phone: order.customer.phone,
        firstName: order.customer.firstName,
        lastName: order.customer.lastName,
        address: {
          street: order.billingAddress.street,
          city: order.billingAddress.city,
          region: order.billingAddress.region,
          postalCode: order.billingAddress.postalCode,
          country: order.billingAddress.country,
        },
      },
    });
  }, [order]);
  return null;
}

See also

• serverTracker.trackConversion() — the matching server-side call.
• The dual-send pattern
• Enhanced conversions: normalization & hashing