Analytics & Attribution User Guide

1. Executive Summary

The Aegis Analytics module is a high-performance telemetry engine designed to solve the "data gap" in modern E-commerce. By combining server-side webhook ingestion with real-time edge tracking, it provides a 100% accurate view of your marketing performance, bypassing browser ad-blockers and iOS privacy restrictions.

2. Managing Paid Channels

To keep your dashboard clean and focused on ROI, Aegis uses a Known Channels system.

Why Register Channels?

Aegis tracks every click, including bot traffic, internal testing, and random referrals. Registering your paid channels (Google Ads, Meta, TikTok, etc.) allows the dashboard to:

  • Filter Noise: Focus only on traffic that matters to your bottom line.
  • Normalize Data: Group various referral strings into a single, clean channel name.
  • Calculate Attribution: Correctively attribute conversions to the right paid source.

How to Register a Channel

  1. Navigate to Settings > Known Channels in the Admin Panel.
  2. Add the Source Name (e.g., google, facebook, tiktok).
  3. Assign a Default Medium (typically paid_social or cpc).
  4. Once added, the dashboard will immediately begin grouping historical and future data under these official headers.

3. The Analytics Dashboard

The dashboard provides real-time visibility into the health of your marketing funnel.

Key Performance Indicators (KPIs)

  • Click Velocity: Monitor traffic spikes in real-time across Today, 7-Day, and 30-Day windows.
  • GA4 Firing Rate: A critical health metric showing the % of clicks where the GA4 server-side signal was successfully dispatched. If this drops below 95%, it indicates a potential configuration issue.
  • UTM Coverage: Tracks how much of your traffic is properly tagged. High "Untagged" traffic suggests your ad creative team needs to audit their tracking templates.

Advanced Attribution Models

  • Customer Touchpoints: See a distribution of how many visits it takes for a customer to convert. This helps understand the length of your sales cycle.
  • Session Distribution: Analyze how often customers return to your site, helping you distinguish between new acquisition and returning brand loyalty.

4. Performance by Page Type

Aegis categorizes every route (Home, Collection, Product, Search, etc.) to show you where your revenue is actually coming from.

  • Revenue vs. Clicks: Identify "high-intent" page types that generate revenue despite lower traffic.
  • Optimization: Use these insights to decide which page types need speed optimizations or better UX to maximize their conversion potential.

5. Data Export & Integration

For teams using specialized BI tools (Tableau, PowerBI) or custom Python models, Aegis provides a high-performance export API.

Automated Exports

Use the /api/analytics/export endpoint to pull raw CSV or JSON data directly into your workflows.

  • App Token Auth: Authenticate via the X-App-Token header for secure, session-less access.
  • Parameters:
    • start / end: Date range (YYYY-MM-DD).
    • source: Filter by a specific marketing channel.
    • format: Choose between csv or json.

6. Server-Side CAPI & GA4

Aegis automatically handles the heavy lifting of sending data to ad networks:

  • Meta CAPI: Every purchase is sent directly to Meta's servers with advanced matching keys to maximize your ad bidding efficiency.
  • GA4 Measurement Protocol: Conversion events are dispatched server-side, ensuring that your Google Analytics data matches your internal database exactly.

7. User & Session Tracking

Aegis uses a multi-layered identity system to track the user journey with 100% precision, even across refreshes and deep-linked navigation.

Identity Tokens

  • Client ID (client_id): Derived from the standard Google Analytics _ga cookie. If blocked, a random UUID is generated to maintain tracking integrity.
  • Session ID (session_id): Stored in the aegis_sid cookie. This persists for the duration of the browser session and groups individual clicks into a single visit.
  • Visitor ID (visitor_id): Stored in the aegis_vid cookie. This is a long-term identifier (2-year expiry) that allows Aegis to recognize returning customers even months later.

Session Persistence & URL Restoration

To solve the common problem of "lost UTMs" on page refreshes or internal links, Aegis implements Session Persistence:

  1. KV Locking: The first time a user lands from an ad, their marketing source is "locked" into a server-side session store (Cloudflare KV).
  2. URL Restoration: If a user refreshes their page and the UTMs disappear from the address bar, Aegis automatically restores them from the session store.
  3. Attribution Continuity: This ensures that downstream tools (like Shopify checkout) always receive the correct utm_source regardless of how the user navigated through the site.

7.3 GA Firing Verification (ga_fired)

Aegis provides a unique health metric called GA Firing Verification to measure the "tracking gap" between server-side logs and browser-side analytics.

  • How it works: When a user lands, the server logs a "Pending" event (ga_fired = 0). Once the GA4 script successfully loads and fires in the user's browser, a hidden heartbeat signal is sent back to Aegis to update the record to ga_fired = 1.
  • Interpreting the Data:
    • Success (1): Confirms that the user's browser is not blocking your tracking and GA4 has recorded the visit.
    • Failure (0): Indicates that the user is likely using an Ad-Blocker, a privacy-focused browser (like Brave), or they closed the page before GA4 could load.
  • Dashboard View: In the Visitor Explorer, events with a green checkmark signify a successful GA fire, while orange indicators highlight users who are "invisible" to standard Google Analytics.