trackbridge

SDK · v0.2.0 · MIT · TypeScript

Send Google Ads conversions twice.

TypeScript SDK that fires from browser and server, dedupes by transactionId, and hashes user data per Google's spec.

View on GitHubRead the docs
npm@trackbridge/sdk
1$ pnpm add @trackbridge/sdk
2 
3import { createBrowserTracker } from '@trackbridge/sdk/browser'
4// or '@trackbridge/sdk/next' for App Router
5 
6const tracker = createBrowserTracker({
7  adsConversionId: 'AW-123456789',
8})
9 
10await tracker.trackPurchase({
11  value:    order.total,
12  currency: 'USD',
13  transactionId: order.id, // dedup key
14  items, userData,
15})

Quickstart

Same call, both sides.

Pass a shared transactionId. Google merges them. Typed helpers — trackPurchase, trackSignUp, trackAddToCart, trackBeginCheckout, trackRefund — for the events you actually fire.

browserapp/checkout/success.tsx
1import { tracker } from "@/lib/tracker"
2 
3await tracker.trackPurchase({
4  value: order.total,
5  currency: "USD",
6  transactionId: order.id, // dedup key
7  items: order.items,
8  userData,
9})
✗ may be blocked: adblock, ITP, consent
serverapi/webhooks/checkout.ts
1import { serverTracker } from "@/lib/server"
2 
3await serverTracker.trackPurchase({
4  value: order.total,
5  currency: "USD",
6  transactionId: order.id, // same key → dedupes
7  items: order.items,
8  gclid: order.gclid,
9  userData,
10})
✓ always reaches Google Ads API

Delayed conversions

Checkout now, fire from the webhook later.

Capture browser state at checkout with tracker.exportContext(), persist the envelope, then replay server-side hours later via serverTracker.fromContext(envelope). Click identifiers, consent state, and client ID stay attached.

Debug

Failures log to console.

Two warnings stay loud in production — the ones only you can fix. Your checkout never crashes.

consoleDevTools

[trackbridge] ⚠ trackConversion called without transactionId

→ Auto-generated: tb_a8f3c1d2-4e7b-...

→ Dual-send disabled. Pass a transactionId you control.

fires in production · always

[trackbridge] ⚠ Ads API → 401 Unauthorized

→ Refresh-token rejected. Check GOOGLE_ADS_REFRESH_TOKEN.

→ Conversion was NOT recorded. retry: false.

[trackbridge] ✓ purchase → $338.00 USD · tid ord_b7e0a3

hash: 8c2a…f704 · gclid present · ec_user_data: 3 fields normalized

Packages

One install.

Trackbridge ships as a single package with subpaths for /browser, /server, and /next (plus /next/server).

$ pnpm add @trackbridge/sdk

Roadmap

Shipped, planned.

shipped

  • Google Ads enhanced conversions

    Browser via gtag · server via Ads API.

  • GA4 events

    Browser via gtag · server via Measurement Protocol.

  • Semantic event helpers

    trackPurchase · signUp · beginCheckout · addToCart · refund.

  • Context envelope

    exportContext on browser → fromContext on server. Webhook-friendly.

  • Next.js helpers

    @trackbridge/sdk/next + /next/server.

  • Consent Mode v2

    ad_storage gates cookie writes; deferred persistence.

  • Click identifier auto-capture

    gclid / gbraid / wbraid · 90-day first-party cookies.

  • Debug mode

    console.warn on failures.

planned

  • Cross-domain _gl linker

    v1.1+.

  • Meta CAPI adapter

    v1.1+.

  • TikTok Events API adapter

    v1.1+.

  • Trackbridge Dashboard

    Separate product, post-v1.