Analytics Setup — us.buywhere.com

Overview

BuyWhere uses Google Tag Manager (GTM) to manage tracking tags including Google Analytics 4 (GA4). This setup enables comprehensive tracking of user interactions across the site for US launch analytics.

Configuration

Environment Variables

Add the following to your .env.local file in /home/paperclip/buywhere-api/frontend/:

# Google Tag Manager Container ID
NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX

# Google Analytics 4 Measurement ID (configured within GTM)
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

GTM Container Setup

1. Create a GTM container at Tag Manager
2. Set the container ID in NEXT_PUBLIC_GTM_ID
3. Within GTM, configure:
   • GA4 Configuration tag: Set Measurement ID to your GA4 property
   • Enable Enhanced Measurement for automatic pageviews, scroll tracking, outbound clicks, site search, and video engagement
   • Set Cross-domain tracking if needed for affiliate redirects
4. Create triggers for custom events (see Events section below)

Events Tracked

Automatic (via GTM/GA4 Enhanced Measurement)

Custom Events

Event Details

search

Fires when a user submits a search query.

gtag('event', 'search', {
  event_category: 'engagement',
  event_label: '<search_term>',
  value: <result_count>
});

select_item (Price Comparison Click)

Fires when a user clicks on a retailer from the comparison table.

gtag('event', 'select_item', {
  event_category: 'engagement',
  event_label: '<retailer_name>',
  items: [{
    item_id: '<product_name>',
    item_name: '<product_name>',
    price: <price>
  }]
});

click_affiliate

Fires when a user clicks an affiliate link on the product page.

gtag('event', 'click_affiliate', {
  event_category: 'conversion',
  event_label: '<product_name> - <retailer_name>'
});

sign_up

Fires when a user successfully subscribes to the US waitlist.

gtag('event', 'sign_up', {
  event_category: 'conversion',
  event_label: 'email - us-waitlist'
});

Verification

GA4 DebugView

1. Install GA4 DebugView Chrome Extension
2. Enable Debug mode on the site
3. Navigate and interact with the site
4. View events in real-time at DebugView

GTM Preview Mode

1. Open GTM container and click Preview
2. Enter your site URL to connect
3. Interact with the site to see tags firing
4. Check the DataLayer tab to see event payloads

File Structure

frontend/
├── app/
│   ├── layout.tsx          # GTM snippet + AnalyticsTracker
│   └── ...
├── components/
│   └── AnalyticsTracker.tsx # Client-side pageview tracking
├── lib/
│   └── ga4.ts              # GA4/GTM event tracking functions
├── .env.example            # Environment variable template
└── public/
    └── sitemap-us.xml      # US site sitemap

Server-Side Conversion Tracking (Measurement Protocol)

BuyWhere also uses GA4 Measurement Protocol for server-side conversion tracking, which captures events that client-side tracking cannot (e.g., affiliate redirects via 302, API-based signups).

Environment Variables

Add to your .env file in /home/paperclip/buywhere-api/:

# GA4 Measurement Protocol (server-side conversion tracking)
# Get Measurement ID from GA4 Admin → Data Streams → Web Stream → Measurement ID
GA4_MEASUREMENT_ID=G-XXXXXXXXXX

# Generate API secret from GA4 Admin → Data Streams → Web Stream → Measurement Protocol → Create
GA4_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Set to "true" to disable GA4 tracking (e.g., in dev)
GA4_DISABLED=false

Conversion Events Tracked (Server-Side)

Marking Events as Conversions in GA4 Admin

After server-side events are flowing, mark them as conversions:

1. Go to GA4 Admin → Conversions
2. Click New conversion event
3. Enter the exact event name:
   • affiliate_click
   • price_alert_set
   • signup_complete
4. Click Save

Wait 24-48 hours for events to appear as available for conversion marking (GA4 processing delay).

GTM Trigger Setup (Client-Side)

If using GTM for client-side event capture alongside Measurement Protocol:

1. Open your GTM container
2. Go to Triggers → New
3. Create a Custom Event trigger for each:
   • Event name: affiliate_click (or click_affiliate for client-side)
   • Trigger fires on: Custom Event with regex match .*
4. Attach these triggers to your GA4 Event tag
5. Mark as conversion: GA4 Admin → Conversions → New conversion event (same as above)

Creating the High-Intent Users Audience

Create a GA4 audience to track users with 1+ affiliate clicks in 7 days:

1. Go to GA4 Admin → Audiences
2. Click New Audience
3. Click Create a custom audience
4. Configure:
   • Audience name: high-intent users
   • Conditions:
     • Add condition: Event → affiliate_click
     • Count matches: at least 1
     • Time range: 7 days
5. (Optional) Add additional conditions like Session → Country equals United States
6. Click Save

This audience powers US revenue ROI reporting and can be used for remarketing.

Key Implementation Notes

• GTM loads asynchronously; custom events use window.dataLayer queue
• The AnalyticsTracker component (in layout.tsx) initializes GA and tracks page views
• The gtag function is shimmed to push events to dataLayer for GTM processing
• GA4 is configured with send_page_view: false — page views are tracked via the AnalyticsTracker component
• All custom events follow GA4's recommended naming and parameter conventions
• Server-side Measurement Protocol tracking (app/services/analytics/ga4.py) captures events that client-side cannot, particularly affiliate click redirects which use 302 redirects