Implement tracking

Author: Jason Cook

README.md

@@ -29,6 +29,165 @@ All content lives in `/content`. All logic lives in `/src`. All output is static
 
 Content processing uses gray-matter for frontmatter parsing, remark and rehype for markdown transformation.
 
+## Tracking And Analytics
+
+### Architecture Overview
+
+SIGIL.ZERO uses a browser-side tracker at `/public/assets/js/tracking.js` with a GTM-first pipeline.
+
+- `tracking.js` is vendor-agnostic and only pushes normalized objects into `window.dataLayer`.
+- Google Tag Manager (GTM) is installed once in the root app shell.
+- GA4 and Meta are configured in GTM, not in application code.
+- No direct `gtag()` or `fbq()` calls exist in the app code.
+
+### GTM-First Rationale
+
+This keeps analytics implementation centralized and safer to evolve:
+
+- Application code emits one stable event contract.
+- Tag vendors are configured in GTM without redeploying app code.
+- Event governance, filtering, and mapping live in one place.
+- Privacy controls remain inside a single normalization layer.
+
+### Container Configuration
+
+- GTM Container ID: `GTM-TLP35C5T`
+- GA4 Measurement ID (configured in GTM): `G-K5W8ENE0DH`
+
+### Event Schema Contract
+
+All custom events must push with:
+
+- `event: "sigilzero_event"`
+
+Core contract:
+
+- `entity`
+- `action`
+- `target`
+
+Events missing any of those three required fields are blocked and not pushed.
+
+### Supported Payload Fields
+
+`tracking.js` emits a flat payload (no arrays/objects) and allows these keys:
+
+- `event`
+- `entity`
+- `action`
+- `target`
+- `platform`
+- `page_type`
+- `page_path`
+- `page_title`
+- `release_title`
+- `release_catalog_id`
+- `artist_name`
+- `track_title`
+- `cta_type`
+- `section`
+- `component`
+- `link_url`
+- `link_text`
+- `destination_domain`
+- `is_external`
+- `debug_source`
+
+### Debug Mode
+
+Enable debug mode either way:
+
+- Set local storage: `localStorage.setItem("sigilzero_debug_tracking", "true")`
+- Or use URL param: `?debug_tracking=true`
+
+When enabled, events include:
+
+- `debug_source: "tracking.js"`
+
+And helper methods are available in the console:
+
+- `window.SigilZeroTracking.debugStatus()`
+- `window.SigilZeroTracking.testEvent()`
+- `window.SigilZeroTracking.getConsoleTestExamples()`
+
+### GTM Setup Workflow
+
+1. Open GTM container `GTM-TLP35C5T`.
+2. Create a Custom Event trigger where `Event name = sigilzero_event`.
+3. Create Data Layer Variables for fields you need (for example `entity`, `action`, `target`, `platform`, `page_type`, `link_url`).
+4. Attach GA4/Meta tags to the custom event trigger.
+5. Use GTM Preview to validate payload values before publishing.
+
+### GA4 Setup Workflow
+
+1. In GTM, create a GA4 Configuration tag using measurement ID `G-K5W8ENE0DH`.
+2. Create a GA4 Event tag triggered by `sigilzero_event`.
+3. Map Data Layer Variables to GA4 event parameters.
+4. Validate in GTM Preview, then GA4 DebugView.
+
+### Meta Setup Workflow
+
+1. Add a Meta Pixel tag in GTM (no direct pixel script in app code).
+2. Trigger from `sigilzero_event` (or filtered subsets).
+3. Map only approved, non-PII fields.
+4. Validate in Meta Test Events.
+
+### Embed play_intent Behavior
+
+Embed interactions (Spotify/SoundCloud) push:
+
+- `entity: "embed"`
+- `action: "play_intent"`
+- `target: "spotify_embed"` or `target: "soundcloud_embed"`
+
+Embed events are deduped with a longer window (`EMBED_DEDUPE_WINDOW_MS = 2000`) to prevent duplicate pushes from iframe focus/blur behavior.
+
+### Privacy And PII Rules
+
+`tracking.js` applies defensive sanitization:
+
+- Blocks email-like and phone-like free-text values.
+- Redacts `mailto:` and `tel:` links (`link_url: "redacted"`, `target: "contact_link"`).
+- Blocks nested objects/arrays from payload output.
+- Drops undefined/null values.
+
+### URL Sanitization Rules
+
+- Only `http`/`https` URLs are allowed for normal tracked links.
+- Querystrings are stripped from `link_url`.
+- Hash fragments are stripped from `link_url`.
+- External domain extraction is preserved for external links only.
+- Valid commerce URLs with numeric path IDs are preserved.
+
+Notes:
+
+- Query parameter stripping is intentional to avoid analytics noise and accidental parameter leakage.
+- `mailto:` and `tel:` are never sent as raw URLs.
+
+### Local Testing Workflow
+
+1. Run `npm run dev`.
+2. Open the site and DevTools console.
+3. Confirm `window.dataLayer` exists and receives `sigilzero_event` payloads.
+4. Exercise page views, release/artist/social/stream/store links, and embed interactions.
+5. Confirm payloads stay flat and contain no undefined values.
+
+### GTM Preview Testing Workflow
+
+1. Start GTM Preview for `GTM-TLP35C5T`.
+2. Navigate core routes (`/`, `/releases`, release detail, artist detail).
+3. Trigger representative interactions (stream/store/social/embed).
+4. Confirm each event appears as `sigilzero_event`.
+5. Verify mapped variables and publish after validation.
+
+### GA4 DebugView Workflow
+
+1. Keep GTM Preview active.
+2. Open GA4 DebugView.
+3. Trigger key interactions and confirm receipt.
+4. Validate expected parameters (`entity`, `action`, `target`, page context, link metadata).
+5. Confirm no unexpected PII-like parameter values appear.
+
 ## Local Development
 
 Install dependencies:
@@ -175,4 +334,3 @@ Speed and simplicity over feature accumulation.
 
 - This repository’s source code is released under the MIT License.
 - Brand identity, artwork, and site content are excluded and remain proprietary.
-