Google Analytics 4 and GTM
Throttle sends the GA4 ecommerce funnel from hosted pages, embedded checkout and your own
storefront. It sends purchase and refund from its server, so ad blockers and closed tabs do not
lose a sale.
What runs where
| Surface | Google tag | Funnel events | Purchase and refund |
|---|---|---|---|
| Hosted pages | Throttle loads gtag.js for your G-ID. GTM never loads on a Throttle domain. | Sent by the hosted page. | Throttle server. |
| Embedded checkout (iframe) | None in the iframe. Your page owns the tag. | The iframe forwards each event to your page. @usethrottle/scripts or onAnalyticsEvent sends it. | Throttle server. |
| Secure Fields (your own card form) | Your page owns the tag. | You send them. See Secure Fields. | Throttle server. |
| Headless storefront | @usethrottle/scripts loads gtag.js, GTM, or both. | You publish storefront events. The loader maps them to GA4. Checkout events come from Throttle. | Throttle server. |
Set up
Create the GA4 property and a Measurement Protocol API secret
In GA4 Admin, open your web data stream. Copy the Measurement ID (G-XXXXXXXXXX). Under Measurement Protocol API secrets, create a secret. The secret is what lets Throttle send purchases and refunds from its server.
Save both in Throttle
Dashboard, Tracking settings, or PUT /api/v1/tracking-settings. Settings are per application and per environment, so a sandbox environment can point at a test property. The secret is stored server-side and comes back masked.
Add the checkout domain to GA4 cross-domain linking
In the data stream settings, open Configure tag settings, Configure your domains, and add checkout.usethrottle.dev. Hosted pages accept the _gl linker parameter, so the buyer stays in one GA4 session.
Send a test event
In Tracking settings, press Send test event, or call POST /api/v1/tracking-settings/test-event. Open GA4 Admin, DebugView, and look for throttle_test.
curl -X PUT https://api.usethrottle.dev/api/v1/tracking-settings \
-H "X-API-Key: sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"ga4MeasurementId": "G-XXXXXXXXXX",
"ga4ApiSecret": "your-measurement-protocol-secret"
}'
The server sends a purchase whenever both the Measurement ID and the API secret are saved.
serverSideEnabled no longer controls GA4. It now gates the
Meta Conversions API only. With an ID and no secret, purchases come from the browser, and the
dashboard shows a warning that ad blockers and embedded checkouts will miss them.
Hosted pages
No code. Once the ID is saved, these pages load your G-ID and send the events in the event table.
| Page | Sends |
|---|---|
/c/:sessionId, /s/:sessionId | page_view, begin_checkout, add_shipping_info, add_payment_info. The Meta pixel runs here too. |
/cart/:cartSessionId | page_view, view_cart, add_to_cart, remove_from_cart. |
/q/:token | page_view, view_quote, accept_quote. |
/q/request/:formToken | page_view, generate_lead. |
/billing/:token | page_view only. |
- URLs are redacted. Hosted URLs contain a capability id. GA4 receives
/c/:tokenaspage_locationandpage_referrer, with onlyutm_*andgclidkept from the query. This holds whatever your data stream's Google tag settings are, including "Ignore duplicate instances of on-page configuration". - Enhanced measurement does not see hosted pages. Your tag runs in a hidden,
token-free frame on the hosted page, so the automatic
page_viewis the only page-level event it sends there. Scrolls, outbound clicks, form interactions and file downloads on hosted pages are not measured. - Page titles. Each page has its own: Checkout, Cart, Quote, Request a quote and Update payment method.
- Meta pixel. Only
/cand/sload it. The other pages do not. - Consent. Append
?consent=grantedor?consent=deniedto the hosted URL. See Consent. - Abandoned-cart links (
/r) render nothing. They, the hosted cart's Checkout button, the quote page's accept and continue-to-checkout buttons, and the/cto/sredirect passconsent,utm_*,gclid,gbraid,wbraid,_gland_tgaon to checkout. - Never in the iframe. Hosted analytics does not run in embed mode.
Embedded checkout
The iframe runs no Google tag. It posts each funnel event to your page as throttle.scriptEvent, only to origins in the application's
allowed origins. Your page sends them to GA4. Pick one of two ways.
Option 1: the loader on your page
Install @usethrottle/scripts (see Headless below). It listens
for the iframe, maps each event, and sends it. On throttle.ready
it also hands the iframe your GA client id, session id, UTMs and consent.
Option 2: the React embed
import { CheckoutEmbed } from '@usethrottle/checkout-react';
<CheckoutEmbed
sessionId={sessionId}
parentOrigin="https://shop.example.com"
// Your visitor's consent, if your page tracks it. Sent to the checkout.
consent={{ analytics: true, marketing: false }}
// Each funnel event, already shaped for GA4. Use this when you do not run
// @usethrottle/scripts on the page.
onAnalyticsEvent={({ name, params }) => window.gtag?.('event', name, params)}
onSucceeded={({ orderId }) => router.push('/thanks?order=' + orderId)}
/>; onAnalyticsEvent receives GA4 names and params. It does not
fire purchase when the server is already sending it. The
embed reads your _ga cookies and posts them into the iframe,
because the iframe's own cookies are third-party.
purchase yourself from throttle.completed or onSucceeded,
remove it. With an API secret saved, Throttle sends the purchase from the server, and a
second one double-counts revenue. If you must keep yours, turn off Throttle sends purchase events in Tracking settings
(sendPurchaseEvents: false).
// Before: you sent purchase yourself.
onSucceeded={({ orderId, total, currency }) => {
gtag('event', 'purchase', { transaction_id: orderId, /* ... */ }); // remove this
}} Secure Fields (your own card form)
With Secure Fields the whole checkout page is yours, so Throttle sends no browser events from it. Purchases and refunds still come from Throttle's server.
What is automatic
- Purchase and refunds. Once the Measurement ID and API secret are saved,
Throttle sends
purchasewhen the payment is captured andrefundfor each refund, from its server. - The visit. When
pay()orcomplete()runs,useSecureCardreads your page's_gaand_ga_<stream>cookies, UTMs and click ids, and sends them asclientContexton/complete. The server purchase then joins the buyer's GA4 session. Reading the context can never fail the payment. - Overrides. Pass the
clientContextprop onSecureCardProviderto set keys yourself, for example{ consent: { analytics: false } }when the visitor declined, or agaSessionIdwhen your page runs more than one GA4 property. Your keys win, one by one. With a customcompleteFn, the hook passes the context asclientContextin its arguments; send it on your own/completecall.
Funnel events
Send the funnel from your own page. With @usethrottle/scripts,
publish the cart events (cart.viewed, cart.item_added, ...) and use Throttle.track() for custom events. track() refuses purchase, refund, begin_checkout, add_shipping_info and add_payment_info, and publish()
refuses every checkout.* name. Send the three checkout steps
with gtag directly. Do not send purchase from the browser: the server already sends it, and a
second one double-counts revenue.
// Your own checkout page, with @usethrottle/scripts loaded (it owns gtag).
// Cart events go through the loader:
Throttle.publish('cart.viewed', {
currency: 'USD',
items: [{ itemId: 'SKU-1', name: 'Trail shoe', unitPrice: 12900, quantity: 1 }],
});
// The checkout steps are names the loader keeps for Throttle's own checkout,
// so Throttle.track() refuses them. Send them to GA4 with gtag yourself:
const ecommerce = {
currency: 'USD',
value: 129,
items: [{ item_id: 'SKU-1', item_name: 'Trail shoe', price: 129, quantity: 1 }],
};
gtag('event', 'begin_checkout', ecommerce);
gtag('event', 'add_shipping_info', { ...ecommerce, shipping_tier: 'Standard' });
gtag('event', 'add_payment_info', { ...ecommerce, payment_type: 'card' });
// Never send purchase: Throttle's server sends it. Passing the visit from your server instead
You can also send clientContext when your server creates the
checkout session. Read it in the browser with Throttle.analyticsContext() and pass it through. At completion
the hook's context is merged over it, key by key, and the completion value wins.
// Browser: read the visit and send it to your server with the cart.
const clientContext = Throttle.analyticsContext();
// Your server: pass it on when you create the checkout session.
await fetch('https://api.usethrottle.dev/api/v1/checkout/sessions', {
method: 'POST',
headers: { 'X-API-Key': process.env.THROTTLE_SECRET_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
applicationId,
cartId,
returnUrl: 'https://shop.example.com/thanks',
cancelUrl: 'https://shop.example.com/cart',
clientContext, // the keys analyticsContext() returns; unknown keys are refused here
}),
}); Headless storefronts
Throttle cannot see your own pages. You publish storefront events, and the loader sends them
to GA4 and GTM. The loader reads your tracking settings from GET /api/v1/storefront/scripts, which needs storefront_scripts:read on your publishable key. Your
storefront origin must be in the application's allowed origins.
Script tag
<script
src="https://cdn.jsdelivr.net/npm/@usethrottle/scripts/dist/t.js"
data-publishable-key="pk_live_xxx"></script>
<script>
// Optional. Calls made before the loader is ready are queued, not dropped.
Throttle.publish('product.viewed', {
currency: 'USD',
itemId: 'SKU-1', name: 'Trail shoe', unitPrice: 12900, quantity: 1,
});
Throttle.track('size_guide_opened', { product: 'SKU-1' });
</script> npm
import { createThrottleScripts } from '@usethrottle/scripts';
const throttle = await createThrottleScripts({
publishableKey: 'pk_live_xxx',
// Every key here is optional. Each one you set overrides the same setting
// from Throttle's Tracking settings.
google: {
measurementId: 'G-XXXXXXXXXX',
gtmContainerId: 'GTM-XXXXXXX', // headless only
requireConsent: true,
spaPageViews: true,
},
consent: { analytics: false, marketing: false },
});
throttle.publish('page.viewed', { url: location.href, title: document.title });
throttle.track('quiz_completed', { step: 3 });
// When the visitor accepts your banner:
await throttle.setConsent({ analytics: true, marketing: true }); Next.js App Router
Set spaPageViews: true. The tag's automatic page view
counts the page the visitor lands on, and each page.viewed
you publish for a later route becomes one page_view (a page.viewed for the landing URL, or a repeat of the last
one, is skipped). Turn off "Page changes based on browser history events" under
Enhanced measurement in your GA4 data stream, or GA4 counts each route twice.
// app/throttle-provider.tsx
'use client';
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';
import { ThrottleScriptsProvider, useThrottleScripts } from '@usethrottle/scripts/react';
function PageViews() {
const { publish } = useThrottleScripts();
const pathname = usePathname();
useEffect(() => {
publish('page.viewed', { url: window.location.href, title: document.title });
}, [pathname, publish]);
return null;
}
export function ThrottleProvider({ children }: { children: React.ReactNode }) {
return (
<ThrottleScriptsProvider
publishableKey={process.env.NEXT_PUBLIC_THROTTLE_PK!}
google={{ spaPageViews: true }}
>
<PageViews />
{children}
</ThrottleScriptsProvider>
);
}
// app/layout.tsx wraps {children} in <ThrottleProvider>.
// In any client component: const track = useThrottleTrack(); track('quiz_completed'); Options
| Option | Meaning |
|---|---|
google.measurementId | GA4 Measurement ID. Defaults to the saved setting. |
google.gtmContainerId | GTM container. Loaded on your storefront only. |
google.tagMode | load (default) injects the Google scripts. existing attaches to a tag your page already has and loads nothing. |
google.spaPageViews | Send a page_view for each page.viewed after the landing page. Turn off history-based page views in Enhanced measurement. |
google.requireConsent | Start with all four consent signals denied. |
google.consentDefaults | Per-signal defaults. They can only tighten when consent is required. |
google.consentRegionScope | all or eea_uk. See Consent. |
google.events | Turn a mapped event off by GA4 name or Throttle name, for example {'{ view_item: false }'}. |
google.constantParams | String params added to every event. |
google.userId | GA4 user_id for the config call. Never an email. |
google.gtagConfig | Extra gtag config params. |
storefront_scripts:read, logs a console error that names the
scope. Your sandboxed scripts stay off, but the GA4 tag still starts from your google options.
GTM and a Google tag together
If you set both a Measurement ID and a GTM container, events go to both. Do not also add a
GA4 configuration tag for the same ID inside the container, or GA4 counts each event twice.
If your page already loads the tag, set tagMode: 'existing'
so Throttle does not load a second copy.
GA4 inside your GTM container only
If GA4 runs from your container (a GA4 Event tag on the ecommerce events, with your G-ID as
the destination), keep the Measurement ID in Tracking settings, because the server purchase
needs it, and pass google: { measurementId: null }
to createThrottleScripts. With the script tag, add data-google-mode="gtm" to the tag instead; it means the same
thing. The loader then loads GTM only and
pushes every event to dataLayer; it loads no gtag.js and sends no gtag
events of its own. Consent Mode still applies: with requireConsent the denied default is pushed before gtm.js loads. Trigger your tag on the event names in the event table (Throttle never sends a browser purchase when the server sends it), and add event
parameters such as search_term to the tag if you want them
in GA4.
Event and dataLayer reference
Names and params follow GA4's recommended ecommerce schema, so GA4 reports and GTM's built-in ecommerce variables work without mapping. Money is in major units of the record's own currency. A currency is never guessed: an ecommerce event with no currency is not sent.
| Throttle event | GA4 event | Key params | Source |
|---|---|---|---|
page.viewed | page_view | page_location, page_title, page_path. Only when spaPageViews is on. | You |
product.viewed | view_item | currency, value, items | You |
collection.viewed | view_item_list | item_list_id, item_list_name, items | You |
search.submitted | search | search_term | You |
cart.item_added | add_to_cart | currency, value, items | You, hosted /cart |
cart.item_removed | remove_from_cart | currency, value, items | You, hosted /cart |
cart.item_updated | add_to_cart or remove_from_cart | From quantityDelta: positive adds, negative removes. Zero sends nothing. | You, hosted /cart |
cart.viewed | view_cart | currency, value, items | You, hosted /cart |
checkout.started | begin_checkout | currency, value, items, coupon | Throttle |
checkout.shipping_submitted | add_shipping_info | shipping_tier, plus the begin_checkout params | Throttle |
checkout.payment_submitted | add_payment_info | payment_type: card, net30 or paypal | Throttle |
checkout.completed | purchase | Browser only when the server cannot send it (no API secret) and sendPurchaseEvents is on. | Throttle |
quote.viewed | view_quote | currency, value. items reach the dataLayer only: GA4 drops items on custom events. | Throttle |
quote.accepted | accept_quote | currency, value. items reach the dataLayer only: GA4 drops items on custom events. | Throttle |
quote.requested | generate_lead | none | Throttle |
custom.<name> | <name> | Whatever you pass | You |
(server) | purchase, refund | transaction_id = order id. See Server-side. | Throttle server |
Ecommerce params
currency, value, items[], coupon, shipping, tax, transaction_id, shipping_tier, payment_type, item_list_id, item_list_name. Each item may carry item_id (the SKU or reference id), item_name, price, quantity, item_variant, item_brand, item_category
to item_category5, discount, coupon, index.
Browser events from checkout also carry throttle_session_id.
Any other key in data.ecommerce is dropped, so no buyer data
rides along. No event or param carries an email, phone, name or address.
What you publish
Either pass a ready data.ecommerce object in GA4 shape, or
pass the older flat fields and the loader builds it. Flat money fields are in minor units.
| Flat field | Becomes |
|---|---|
currency | currency. Required for ecommerce events. |
itemId / sku / productId, name | item_id, item_name |
unitPrice, quantity | price, quantity. value = total or unitPrice x quantity. |
items[] | The same fields per item. |
variant / variantName | item_variant |
coupon / couponCode | coupon |
orderId / transactionId, shipping, tax | transaction_id, shipping, tax |
quantityDelta | On cart.item_updated only: sets the quantity and the add or remove. |
The dataLayer shape
For every ecommerce event the adapter first pushes { ecommerce: null }
to clear the previous object, then pushes { event, ...extras, ecommerce }. Non-ecommerce events
push { event, ...params }. The adapter pushes to dataLayer always, and calls gtag('event', ...) when a Measurement ID is set. So a GTM
trigger on view_item works whether or not you use gtag.
// A product page, with GTM loaded by @usethrottle/scripts.
// dataLayer after Throttle.publish('product.viewed', ...):
[
{ ecommerce: null },
{
event: 'view_item',
ecommerce: {
currency: 'USD',
value: 129,
items: [{ item_id: 'SKU-1', item_name: 'Trail shoe', price: 129, quantity: 1 }],
},
},
] Custom events
Throttle.track('quiz_completed', { step: 3 }) publishes custom.quiz_completed on the Throttle bus, so your sandboxed
scripts see it, and sends GA4 event quiz_completed. A custom. prefix is accepted and stripped. Names are cut to
GA4's rules: letters, digits and underscore, 40 characters.
These names are refused with a console warning, because only Throttle's own surfaces may
send them: purchase, refund, begin_checkout, add_shipping_info, add_payment_info. Publishing any checkout.*
name is refused too.
In React, useThrottleTrack() returns the same function.
Calls made before the loader is ready are queued.
Consent and Consent Mode v2
Throttle shows no consent banner. You tell it what the visitor chose.
- Off by default.
requireConsentisfalseuntil you turn it on. With it off, no consent default is declared, unless you setconsentDefaults. - Required and not given. The tag still loads, with
analytics_storage,ad_storage,ad_user_dataandad_personalizationalldenied. Google sends cookieless pings and can model them. This is Advanced Consent Mode. The default is set before the tag loads. - consentDefaults can only tighten. While consent is required, a default of
grantedis ignored. Only a real signal grants consent. With consent not required,consentDefaultssets signals either way. Saving a signal asnull(for example{ "ad_storage": null }) clears it. - Region scope.
consentRegionScope: 'eea_uk'limits the default to the EEA, UK and Switzerland. Visitors elsewhere are not denied. - Granting. On hosted pages, use
?consent=granted. On headless, callThrottle.setConsent({ analytics, marketing }). In the React embed, pass theconsentprop. Theanalyticsflag maps toanalytics_storage. Themarketingflag maps to the other three. A category you leave out ofsetConsentis treated as denied.
// Consent required, nothing granted yet: the tag loads with all four signals denied.
gtag('consent', 'default', {
analytics_storage: 'denied',
ad_storage: 'denied',
ad_user_data: 'denied',
ad_personalization: 'denied',
});
// Throttle.setConsent({ analytics: true, marketing: true }) then sends:
gtag('consent', 'update', {
analytics_storage: 'granted',
ad_storage: 'granted',
ad_user_data: 'granted',
ad_personalization: 'granted',
}); curl -X PUT https://api.usethrottle.dev/api/v1/tracking-settings \
-H "X-API-Key: sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"requireConsent": true,
"consentRegionScope": "eea_uk",
"consentDefaults": { "ad_storage": "denied" },
"events": { "view_item_list": false },
"constantParams": { "store_region": "emea" },
"userIdSource": "customerId"
}'
Throttle records the visitor's choice on the order, as clientContext.consent. The server reads it for purchases and
refunds. See Server-side.
Cross-domain
Add checkout.usethrottle.dev to the GA4 cross-domain list.
When a hosted URL carries _gl, the hosted tag accepts it
(gtag('set', 'linker', { accept_incoming: true })), so the
checkout keeps your page's client id and the server purchase joins your visit. If you use
a custom checkout domain, add that one.
Joining the purchase to the visit
GA4 attaches a server purchase to a visit by the visit's client id and session id. They live in
your site's _ga and _ga_<stream>
cookies, which Throttle cannot read from its own domain. Hand them over in one of these ways.
| Your flow | How the ids arrive |
|---|---|
| Embedded checkout | Automatic. The loader or CheckoutEmbed posts them into the iframe as throttle.analyticsContext. |
| Secure Fields | Automatic. useSecureCard sends them as clientContext on /complete. See Secure Fields. |
| @usethrottle/cart on the page | Automatic. If Throttle.analyticsContext() exists, the cart SDK attaches it as clientContext on the checkout hand-off, unless you pass your own. |
| Hosted redirect | Use Throttle.checkoutUrl(url), or _gl linking. The hosted page reads _tga when it has no _ga cookie. |
| Your own server | Send clientContext yourself. |
analyticsContext()
Returns gaClientId, gaSessionId, utmSource, utmMedium, utmCampaign, utmTerm, utmContent, gclid, fbclid, msclkid, ttclid, landingPage, referrer, fbp, fbc and consent. Keys and
lengths match the server's strict clientContext schema. landingPage is the first page of the current GA4 session in
this browser tab. It and referrer are redacted: no Throttle
capability id, consent flag, key or #fragment; only campaign and click-id params stay.
// cart is your @usethrottle/cart cart-session client.
// With @usethrottle/scripts on the page, clientContext is attached for you.
const { checkoutUrl } = await cart.checkout({
returnUrl: 'https://shop.example.com/thanks',
cancelUrl: 'https://shop.example.com/cart',
});
location.href = checkoutUrl; // Hosted redirect without cross-domain linking:
location.href = Throttle.checkoutUrl('https://checkout.usethrottle.dev/c/SESSION_ID');
// -> .../c/SESSION_ID?_tga=123456789.1700000000.1700000000&utm_source=google&gclid=... clientContext on cart routes
These routes now accept an optional clientContext, the same
object as on POST /api/v1/checkout/sessions:
POST /api/v1/cart-sessions/:id/checkout-sessionPOST /api/v1/carts/:id/finalizePOST /api/v1/carts/:id/checkout, the legacy alias
On these routes and on checkout completion, a clientContext
that fails validation (an unknown key, a blank or over-length value, more than 8192 bytes) is
dropped with a server warning and the request goes ahead: analytics never fails a checkout.
Values are trimmed; the caps are 512 characters, 2048 for
landingPage and referrer.
On POST /api/v1/checkout/sessions unknown keys are still
rejected. At completion, the checkout page merges what it sees over what you sent, key by key.
The completion-time value wins.
// Your storefront page (a publishable key; this route is called from the browser).
// Send Throttle.analyticsContext() as clientContext. Shown as curl for the shape.
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/checkout-session \
-H "X-API-Key: pk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"returnUrl": "https://shop.example.com/thanks",
"cancelUrl": "https://shop.example.com/cart",
"clientContext": {
"gaClientId": "123456789.1700000000",
"gaSessionId": "1700000000",
"utmSource": "google",
"gclid": "Cj0KCQjw...",
"consent": { "analytics": true, "marketing": true }
}
}' Server-side purchases and refunds
- When. Card payments send
purchaseatpayment.captured. Net-N invoices send it atpayment.authorized, when the invoice is issued. Paying the invoice later sends nothing. - Requires a saved Measurement ID and API secret. It does not need
serverSideEnabled. - Fields.
transaction_idis the order id. It also sendsvalue,currency,shipping,tax,coupon, items with per-itemdiscount,session_idandengagement_time_msec: 1. The payment time goes astimestamp_microswhen it is under 72 hours old. - Refunds. Each refund sends one
refundwith the sametransaction_id, the amount of that refund asvalue, and the same client id as the purchase. Full and partial refunds both send. Refunds issued in the payment processor's dashboard are sent too, once each. - Never sent. Subscription renewals, for purchase and for refund. Orders with no currency.
- user_id. Off by default. Set
userIdSourcetocustomerIdorexternalId. It is never an email, and it is dropped when consent is denied. - Consent denied. With
requireConsenton and analytics consent not given, the server still sends the purchase. It setsad_user_dataandad_personalizationtoDENIED, omitsuser_idandsession_id, and uses a synthetic client id, so GA4 can model it. When consent is given, the two ad flags followadUserDataandadPersonalization, elsemarketing. - No retry. A failed send is logged and not retried.
- Endpoint.
www.google-analytics.com/mp/collect. The EU endpoint is not configurable.
Status
GET /api/v1/tracking-settings/status reports the last seven
days for this application and environment: sent, failed, unattributed (no real client id),
skipped by reason, the last success, and the last error. The dashboard shows the same panel.
It needs applications:read and the
application-settings permission.
curl https://api.usethrottle.dev/api/v1/tracking-settings/status \
-H "X-API-Key: sk_live_xxx"
{
"data": {
"last7d": { "sent": 41, "failed": 0, "unattributed": 3, "skipped": { "renewal": 12 } },
"lastSuccessAt": "2026-11-14T09:12:44.000Z",
"lastError": null
}
} Debugging
Test the server path
Press Send test event in Tracking settings, or call the route below. Throttle first validates your ID and secret against the Measurement Protocol debug endpoint. If GA4 returns validation messages, nothing is sent and the messages come back. Otherwise it sends throttle_test with debug_mode.
Open DebugView
GA4 Admin, DebugView. throttle_test appears in the live stream. For browser events, turn on the Google Analytics Debugger browser extension, then watch the funnel events arrive.
Check the status panel
Sent, failed, unattributed and skipped counts tell you whether purchases leave Throttle.
Inspect the dataLayer
On a headless page, open the console and read window.dataLayer. Each ecommerce event is preceded by an object with ecommerce: null.
curl -X POST https://api.usethrottle.dev/api/v1/tracking-settings/test-event \
-H "X-API-Key: sk_live_xxx"
{ "data": { "validationMessages": [], "sent": true } }
The test route needs applications:write and the
application-settings permission. It answers 422 tracking_not_configured
when the ID or secret is missing, and 502 ga4_request_failed
when Google cannot be reached.
FAQ
Purchases show as Unassigned or Direct in GA4
The server purchase did not carry your visitor's client id and session id. Check, in order:
the embedded checkout gets them from the loader or from CheckoutEmbed;
a Secure Fields page needs @usethrottle/checkout-react 2.4.0 or
later, or a custom completeFn that forwards clientContext;
a hosted redirect needs Throttle.checkoutUrl() or _gl linking; a server-minted session needs clientContext. The visitor must also have granted analytics
consent when consent is required. Compare the Unattributed count in status.
I see two purchases
Remove your own purchase call, or turn off Throttle sends purchase events. See the upgrade note above.
I get no events on a headless site
Check the console for a message naming storefront_scripts:read. Confirm your origin is in allowed
origins. If your page already loads the Google tag, set tagMode: 'existing'.
Events fire twice on a Next.js site
Either leave spaPageViews off and let GA4's
history-based page views count routes, or set it on, publish page.viewed on route change and turn off "Page changes
based on browser history events" in Enhanced measurement. Doing both counts each route
twice.
Which environment does a sandbox use?
Tracking settings are per application and per environment. A sandbox environment can use a different property and secret.
Does Throttle change my GTM container?
No. It pushes to dataLayer and you build the tags.
Related
- Track conversions, the Meta Conversions API and attribution capture.
- Your own scripts, the event catalog for sandboxed scripts.
- Embedded checkout, the postMessage contract.
- Cart sessions, the hand-off to checkout.