gtm-tracking
Use when adding GTM analytics, tracking events, impressions, or click tracking to components - ensures consistent event shape, naming conventions, and correct implementation pattern
SKILL.mdmisc/gtm-tracking/SKILL.md
GitHubGTM Event Tracking
Overview
All GTM events use sendGTMEvent from @next/third-parties/google. Events follow a standard shape with four core fields plus optional domain-specific fields.
Standard Event Shape
import { sendGTMEvent } from '@next/third-parties/google';
sendGTMEvent({
event: 'click', // what happened
eventGroup: 'search_expansion', // feature/domain grouping
section: 'search', // where in the page
element: 'confirm_button', // what was interacted with
// + optional domain-specific fields
});
Quick Reference
Event Types
event value |
When to use |
|---|---|
click |
User clicks/taps an interactive element |
impression |
Element enters viewport |
contact |
User initiates contact (phone, email) |
form_submit |
Form submission |
swipe |
Carousel/swipe gesture |
virtual_pv |
SPA page navigation (handled by GTMVirtualPageView) |
Existing eventGroup Values
Before creating a new group, check if one of these fits:
search_expansion, stories, calculators, semantic_search, amenities, travel_time, credits, place_relation, odrednice, website_interactions, user_data, extended_search
Some older events use eventGroup: '' — avoid this in new code.
Naming Conventions
eventGroup:snake_case, describes the feature domainsection:snake_case, describes page area (e.g.search,detalji_oglasa,kod_filtera,cenovnik)element:snake_case, describes the specific UI element or action (e.g.confirm_button,open_selection)- Domain-specific fields:
camelCase(e.g.amenityCategory,adId,searchCount)
Implementation Patterns
Inline (default — use for 1-2 events)
Direct sendGTMEvent() call in an event handler:
const handleClick = () => {
sendGTMEvent({
event: 'click',
eventGroup: 'your_feature',
section: 'your_section',
element: 'your_element',
});
};
Typed Tracker Module (use for 3+ distinct events)
Create a dedicated track-{feature}.ts file with discriminated union types. Reference implementation: src/app/(base)/pretraga/[transactionType]/[[...otherSegments]]/_components/search-expansion/track-search-expansion.ts
Pattern:
- Define a
Payloaddiscriminated union (component-friendly names) - Define a
GTMEventdiscriminated union (exact GTM shape) - Write a mapper function between them
- Export a single
trackFeatureName(payload)function with try/catch
Viewport Impressions
Use ImpressionSenderWrapper from src/components/gtm/impression-sender-wrapper.tsx:
<ImpressionSenderWrapper
event="impression"
eventGroup="your_feature"
section="your_section"
element="your_element"
unique // only fire once
>
{children}
</ImpressionSenderWrapper>
Note: this adds a wrapping <div> — be mindful of layout impact.
Checklist Before Shipping
- Component is client-side (
'use client'or guarded with window check) -
eventGroupreuses existing value or new value is justified - All new field names use
snake_case(section, element) orcamelCase(domain fields) - Impression events use
uniqueflag if they should only fire once - Events with 3+ variants use typed tracker module pattern
- GTM event shape is documented in the feature spec or PR description