---

name: analytics-tracking description: >- Designs and implements website analytics tracking with Google Analytics 4 and Google Tag Manager: a written tracking plan, event and parameter names that pass GA4's rules, gtag.js or data-layer code, key events, consent mode, UTM conventions, and a verification pass. Use when someone says "set up GA4", "add conversion tracking", "track this form or button", "write a tracking plan", "GTM data layer", "UTM parameters", "why are my events missing or counted twice", or "audit our analytics setup". license: Apache-2.0 compatibility: "A GA4 property with a web data stream and either the Google tag (gtag.js) or a Google Tag Manager web container. curl for the Measurement Protocol validation server. Web only; native mobile SDKs are out of scope." metadata: author: terminal-skills version: "2.0.0" category: business tags: ["google-analytics", "ga4", "google-tag-manager", "event-tracking", "utm"]

Analytics Tracking

Overview

Tracking is finished when a named person can answer a business question from a report, not when a tag fires. This skill takes a site from "we have GA4 installed" to a short tracking plan, code that sends each event exactly once with valid names, the Admin settings that make the data usable, and proof that it works. Everything here follows Google's current documentation for GA4, the Google tag and Tag Manager; Universal Analytics concepts (categories, actions, labels, goals, anonymize_ip) do not apply.

Instructions

1. Establish what exists

Ask: which decisions the data should inform, which actions count as success (lead, signup, purchase), which regions the visitors come from (consent), and who is allowed to publish the Tag Manager container. Then look in the code:

grep -rnE "gtag\(|dataLayer\.push|googletagmanager\.com|GTM-[A-Z0-9]{4,}|G-[A-Z0-9]{8,}|@next/third-parties" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.html" \
  --exclude-dir=node_modules --exclude-dir=.next .

Choose one delivery path and keep to it. If a GTM- container is on the page, send events through the data layer and configure tags in Tag Manager; if only the Google tag is present, call gtag() directly. The same event sent through both paths is counted twice.

2. Pick events from the top of this list down

1. Already collected. With enhanced measurement on, GA4 records page_view (page loads and browser-history changes), scroll (once per page at 90% depth), click (outbound links only), view_search_results, video_start / video_progress / video_complete (embedded YouTube), file_download, form_start and form_submit. Do not re-implement these.
2. Recommended events. Use Google's exact names and parameters so built-in reports fill in: sign_up and login (method), generate_lead (currency, value, lead_source), search (search_term), view_item, add_to_cart, begin_checkout, add_payment_info, purchase (transaction_id, currency, value, items).
3. Custom events, only when nothing above fits. One name per action, with the variation in parameters: cta_click with cta_location: "pricing_hero", not a separate event name per button.

Names must pass these limits; GA4 does not log what exceeds them, and nothing in the browser reports an error:

Item	Rule
Event name	Starts with a letter; letters, digits and underscores only; case-sensitive; 40 characters
Parameters	25 per event; name 40 characters; value 100 characters (page_location 1,000, page_referrer 420, page_title 300)
User properties	25 per property; name 24 characters; value 36 characters
Reserved	Parameter names starting with _, firebase_, ga_, google_ or gtag.. Do not reuse automatic names (click, scroll, session_start, first_visit, user_engagement, form_submit, file_download) for custom events
Per standard property	30 key events, 50 event-scoped and 25 user-scoped custom dimensions, 50 custom metrics

Money: value is a number, never a string, and always travels with currency (ISO 4217, "USD"). For purchase, value is the sum of price × quantity and excludes shipping and tax; transaction_id is required and is what keeps a repeated purchase from being counted again.

3. Write the tracking plan

Create docs/tracking-plan.md with one row per event: event name, the exact moment it fires (a server-confirmed success, not a button press), parameters with example values, whether it is a key event, and which path sends it. Example 1 shows the format. Every later step works from this file.

4. Implement

Google tag with consent defaults. The consent default must run before the tag loads; the order of these blocks is the point.

<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('consent', 'default', {
    ad_storage: 'denied',
    ad_user_data: 'denied',
    ad_personalization: 'denied',
    analytics_storage: 'denied',
    wait_for_update: 500
  });
</script>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-7KQ2M4XW9P"></script>
<script>
  gtag('js', new Date());
  gtag('config', 'G-7KQ2M4XW9P');
</script>

When the visitor answers the banner, the consent tool calls gtag('consent', 'update', { analytics_storage: 'granted', ... }) with all four types, and repeats that on later pages from the stored choice. Add region: ['ES', 'FR'] to a default to scope it; the most specific region wins. Which defaults to set is the site owner's legal decision, not a technical one. In Tag Manager, use a consent template from the Community Template Gallery (or the consent APIs in a custom template), never a Custom HTML tag.

Events with gtag.js go anywhere below the snippet: gtag('event', 'generate_lead', { currency: 'USD', value: 180, lead_source: 'demo_form' }).

Events with Tag Manager. The page pushes a message that carries an event key; a GA4 Event tag listens for it with a Custom Event trigger and reads the fields through Data Layer Variables. For ecommerce events, clear the previous object first:

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'ST-20418',
    value: 43.50,
    tax: 3.48,
    shipping: 4.90,
    currency: 'USD',
    items: [
      { item_id: 'OOL-100', item_name: 'High Mountain Oolong 100 g', price: 14.50, quantity: 3 }
    ]
  }
});

Single-page apps. Enhanced measurement sends page_view on pushState, popState and replaceState when "Page changes based on browser history events" is ticked (Admin > Data collection and modification > Data streams > the stream > Enhanced measurement > Page views > advanced settings). With Tag Manager, send page_view from a GA4 Event tag on a History Change trigger and leave that option off, or every navigation counts twice. To send page views by hand, set send_page_view: false in config and turn the history option off as well.

Signed-in users. Pass an internal ID with gtag('config', 'G-7KQ2M4XW9P', { user_id: 'u_48211' }): an opaque ID, never an email address.

Server-side events (a webhook confirms payment, a CRM marks a lead qualified) go through the Measurement Protocol: POST https://www.google-analytics.com/mp/collect?measurement_id=...&api_secret=... with a JSON body holding client_id and up to 25 events. Read the browser's client_id and session_id with gtag('get', 'G-7KQ2M4XW9P', 'client_id', callback) and store them with the order. Include session_id and engagement_time_msec in params; without them the event does not count toward session and engagement metrics or show properly in Realtime. The secret is created under Admin > Data collection and modification > Data streams > the stream > Measurement Protocol API secrets and stays in a server environment variable. For EU collection use the host region1.google-analytics.com.

5. Configure GA4 Admin

• Key events (the name that replaced "conversions"): Admin > Data display > Events, star the event. purchase is one by default. Allow up to 24 hours for standard reports.
• Custom definitions: a custom parameter is invisible in reports until it is registered under Admin > Data display > Custom definitions as an event-scoped dimension; it appears 24–48 hours later. Register only what the plan needs.
• Data retention: Admin > Data Settings > Data Retention. Standard properties offer 2 or 14 months; choose 14. It affects explorations and funnels, not the standard aggregated reports.
• Data redaction: turn on email redaction and list query parameters to strip for the web stream if URLs can carry personal data.

6. Set the UTM convention

Parameter	Use
utm_source	Who sent the visit: newsletter, linkedin, partner-fieldnotes
utm_medium	Channel type; GA4 maps it to a default channel (table below)
utm_campaign	The campaign, identical across every platform it runs on
utm_id	Campaign ID, needed when cost data is imported
utm_content, utm_term	Creative variant; paid keyword

Always set source, medium and campaign together. Values are case-sensitive (Email and email become two rows), so use lowercase throughout. Keep UTMs off links between your own pages and never put personal data in them.

utm_medium value	Default channel group
email	Email
cpc, ppc, or anything starting with paid	Paid Search, Paid Social, Paid Shopping, Paid Video or Paid Other, depending on the source
social	Organic Social
affiliate	Affiliates
display, banner, cpm	Display
referral	Referral
sms	SMS

7. Verify before calling it done

1. Open Tag Assistant (tagassistant.google.com, or Preview in the Tag Manager workspace), connect to the site, and perform each action in the plan.
2. Watch Admin > Data display > DebugView. Each event must appear once, with every planned parameter, on desktop and on a phone. DebugView stays empty while analytics consent is denied, so grant it in the banner first.
3. To debug without Tag Assistant, add debug_mode: true to the event or config; remove the key afterwards, because setting it to false does not switch it off.
4. Check server-side payloads against the validation server (Example 3). The live endpoint returns 2xx even for malformed events.
5. A day later, confirm the events and key events in the standard reports and record the date in the plan.

Examples

Example 1: Lead tracking for a B2B site on Next.js

Prompt: "Kestrel Payroll's marketing site is Next.js. GA4 is installed with the Google tag. We need demo requests and signups as conversions, and we want to know which company sizes ask for demos."

The plan the agent writes to docs/tracking-plan.md:

| Event | Fires when | Parameters (example) | Key event | Sent by |
|---|---|---|---|---|
| page_view | page load and route change | automatic | no | enhanced measurement |
| file_download | click on a PDF link | automatic | no | enhanced measurement |
| generate_lead | POST /api/demo returns 200 | currency "USD", value 180, lead_source "demo_form", company_size "51-200" | yes | gtag |
| sign_up | account row created | method "email" or "google" | yes | gtag |
| cta_click | click on a primary button | cta_location "pricing_hero", cta_text "Start free trial" | no | gtag |

Custom dimensions to register (event scope): company_size, cta_location, lead_source
Lead value: 180 USD = 6% demo-to-customer rate × 3,000 USD first-year revenue
Verified in DebugView: 2026-10-02

The code:

// app/layout.tsx — loads the Google tag once for every route
import { GoogleAnalytics } from '@next/third-parties/google'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId={process.env.NEXT_PUBLIC_GA_ID!} />
    </html>
  )
}

// app/demo/DemoForm.tsx — fire only after the server accepted the request
'use client'
import { sendGAEvent } from '@next/third-parties/google'

export async function submitDemo(form: { email: string; companySize: string }) {
  const res = await fetch('/api/demo', { method: 'POST', body: JSON.stringify(form) })
  if (!res.ok) return
  sendGAEvent('event', 'generate_lead', {
    currency: 'USD',
    value: 180,
    lead_source: 'demo_form',
    company_size: form.companySize, // the email address is never sent
  })
}

Then the Admin steps: star generate_lead and sign_up as key events, register the three custom dimensions, set retention to 14 months, confirm "Page changes based on browser history events" is ticked so App Router navigations count as page views.

Example 2: A store that counts purchases twice

Prompt: "Saltmarsh Tea runs on a custom storefront with Tag Manager. GA4 shows about 30% more purchases than our order system."

The agent searches the code, finds the purchase push in the order-confirmation page with no transaction_id, and a second GA4 tag firing on the same page from a Page View trigger. Customers who reload the confirmation page, or reopen it from the order email, send the event again. The fix:

1. Push purchase once, with transaction_id set to the order number and the ecommerce: null reset before it (the code in step 4).
2. In Tag Manager keep one GA4 Event tag for purchase on a Custom Event trigger named purchase, map transaction_id, value, currency and items from Data Layer Variables, and delete the Page View tag.
3. Preview, place a test order, reload the confirmation page, and confirm in Tag Assistant that the tag fired once.
4. Compare GA4 purchases with the order system for the following week and note the remaining gap in the plan. After the fix GA4 should match the order system or sit below it, because ad blockers and declined consent only remove events.

Example 3: Checking a server-side event before it ships

The validation server accepts the same request as the live endpoint, stores nothing, and explains what is wrong. It does not check the secret or the measurement ID.

curl -s -X POST "https://www.google-analytics.com/debug/mp/collect?measurement_id=G-7KQ2M4XW9P&api_secret=$GA_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"1837264019.1759312800","validation_behavior":"ENFORCE_RECOMMENDATIONS",
       "events":[{"name":"Demo Request","params":{"value":180}}]}'

{
  "validationMessages": [ {
    "fieldPath": "events",
    "description": "Event at index: [0] has invalid name [Demo Request]. Only alphanumeric characters and underscores are allowed.",
    "validationCode": "NAME_INVALID"
  } ]
}

Renamed to generate_lead with currency, value, session_id and engagement_time_msec, the same request returns an empty validationMessages array. Only then does the agent switch the URL to /mp/collect.

Guidelines

• No personal data in any event, parameter, user property, page URL, page title or UTM value: no emails, phone numbers or names. Look for forms that submit with GET and put the email in the query string.
• A parameter that is not registered as a custom dimension cannot be used in reports, and one registered late has no history. Register on the day the event ships.
• A parameter value over 100 characters exceeds the collection limit and is not stored as sent. Send IDs and short labels, not sentences.
• Do not spend key events on steps (page views, clicks). Thirty is the ceiling, and each one dilutes the "Key events" column.
• Fire on confirmed outcomes. A click on "Submit" also counts validation errors and double clicks; the server's success response does not.
• GA4 does not log IP addresses, so there is no IP-anonymisation switch to set. Old snippets containing anonymize_ip can be deleted.
• Keep debug traffic out of reports: use Tag Assistant for your own device instead of shipping debug_mode to everyone.
• Never put the Measurement Protocol secret in browser code. Anyone who has it can write events into the property.
• This skill does not decide what the consent banner must say or which defaults are lawful in a given country; that belongs to the site owner and their counsel.
• Not the right tool for product analytics inside an app (per-user funnels, retention cohorts) or for mobile SDK setup.