Source identity
| Field | Recorded value |
|---|---|
| Source type | GitHub source |
| Original record | Janady13/thatstupidcomputer / docs/MEASUREMENT.md |
| Date | Not specified in source |
| Repository | Janady13/thatstupidcomputer |
| Revision | 57555cde46910102dd25d6c1c1fb2c359e9655bd |
| Branch | main |
| Path or archive member | docs/MEASUREMENT.md |
| Original SHA-256 | 4fb81ffc0605562052ed21c66c4c4a2432fef51200def6b8f1f0eb3e7df6aa02 |
| Git blob SHA | cf28e11a9a3f96b2a7d8e0b6fbb8aa70e187575e |
| Reading-copy SHA-256 | 4fb81ffc0605562052ed21c66c4c4a2432fef51200def6b8f1f0eb3e7df6aa02 |
Recovered source transcript
Download complete source text ↓90 lines · 19.7 KB
# M01 — Measurement, consent and reporting contract
Implementation date: 2026-09-13. Accountable scope: R16 with R20/R12 and G25/G26/G34 of the supplied SEO/AIO library. Relevant complete source modules reviewed: documents 022, 026, 030, 041, 042, 044, 045, 054–057 and the three graph sections. The source library is private reference material; it is not published as site content.
## Delivery state
Implemented: one GA4 adapter, validated public measurement ID and canonical-origin configuration, persistent consent controls, a closed event dictionary, safe attribution, and optional consent-gated Core Web Vitals. The deployed identifier is `G-RNRQK2CRDY`, belonging to the existing That Stupid Computer property `533588991` and rebuild stream `15768871672`. Missing or invalid configuration leaves analytics inactive without breaking the site or inquiry journey.
Local test evidence: `node --test tests/measurement/*.test.mjs` passes 24 tests covering every actual canonical route, safe absolute page URLs, origin validation/reconfiguration, consent, privacy boundaries, route and accepted-receipt deduplication, the computer funnel, withdrawal, cross-tab state, storage failures and load failures. These tests inspect the real adapter's commands in a fake browser environment; they do not independently prove Google received events, establish field performance, or establish legally sufficient consent. Live provider and browser evidence belongs in `docs/MEASUREMENT-SEARCH-VERIFICATION.md`.
The authorized Google APIs have now been inspected: the real stream receives events, enhanced automatic measurement is disabled, Signals is disabled, and Search Console reports ownership plus an error-free eleven-page sitemap. The first account read also exposed empty hostname reporting and missing custom definitions. The canonical-origin repair and provider setup are tracked in the integration report; do not infer deployment or Bing ownership from source changes alone. Preserve unavailable observations as unavailable, not zero. Clarity and other session recorders are **NOT_APPLICABLE**: no requirement justified recording the interface or inquiry fields. Adding one requires a separately reviewed purpose and separate consent controls.
## Application interface
Import `analytics` and `ConsentControls` from `apps/web/src/measurement/index.ts`. App configuration uses `analytics.configure({ ga4MeasurementId: config.ga4MeasurementId, canonicalOrigin: config.canonicalOrigin })`. Root bootstrap maps the public `/api/config` response's `analytics.measurementId` to that App prop; the canonical origin comes from the existing approved public site projection. A repeated identical configuration is idempotent. Client configuration contains a public measurement ID and public canonical origin, never a Measurement Protocol secret or service account key.
Configuration accepts only an ID matching `G-` plus 5–20 uppercase letters/digits and an explicit HTTPS root origin with no credentials, nonstandard port, path, query or fragment. One trailing slash is normalized. Syntax does not establish account authorization. `analyticsDebug: true` is an optional explicit development setting; it never activates tracking without valid configuration and consent, and is not derived from a visitor's query string. Invalid or missing ID/origin returns `false`, reports `unconfigured`, and never creates a tag; invalidating an active configuration stops collection.
The component provides a first-choice banner only when measurement is configured and a persistent **Privacy preferences** control. Allow and decline have equal visual weight. Escape from the preferences controls closes them and restores focus without navigating the page behind them. Dismissing the initial banner leaves analytics off; preferences can be reopened. Inquiry processing consent is separate from optional analytics consent. JavaScript-free submission does not emit browser analytics.
Only these application methods emit events:
| Method | Event | Evidence represented |
| --- | --- | --- |
| `pageView(path)` | `page_view` | A consented view of a finite public route |
| `sceneInteraction(scene, action)` | `scene_interaction` | One explicit studio interaction |
| `computerInteraction(stage, intent)` | `computer_interaction` | One explicit, finite character-conversation action |
| `demoStart(source)` | `demo_start` | Explicit interest in opening the inquiry path |
| `demoSubmitError(error)` | `demo_submit_error` | A validation, transport or server failure |
| `generateLead('smtp_accepted', requestId)` | `generate_lead` | The server reported SMTP acceptance; repeated receipts are suppressed |
There is no public arbitrary `track(name, fields)` escape hatch. Runtime schema validation requires exactly the documented fields and finite values; it rejects additional keys, arbitrary strings, inherited records, accessors and nonfinite metric numbers. TypeScript definitions provide the same finite interface to the application.
## Event and metric dictionary
All application events are event counts, scoped to consented browser activity in the selected reporting period. GA4 report timezone must be recorded from the actual property. No production timezone, lookback window, first-user identity, or qualification decision has been fabricated.
| Event | Allowed business parameters | Unit and meaning | Missing data / deduplication |
| --- | --- | --- | --- |
| `page_view` | `page_path`, `referral_source`, `referral_evidence` | Count of manual route views; unknown routes become `/404/` | Repeated same-route effects emit once; an actual return after another route emits a new view. Preconsent views are not replayed. |
| `scene_interaction` | `scene_id`: `desktop-office` or `mobile-workshop`; `interaction`: `services`, `work`, `process`, `about`, `demo`, `character`, `motion_pause`, `motion_play` | Count of explicit scene actions | No pointer coordinates, DOM text, selectors, or arbitrary object IDs |
| `computer_interaction` | `interaction_stage`: `open`, `intent_selected`, `attitude_requested`, `gesture_requested`, `mood_selected`, `back`, `demo_clicked`, `dismissed`; `project_intent`: `design`, `rescue`, `search`, `care`, `unsure`, `not_selected` | Count of explicit character-conversation actions | No dialogue text, URLs, fields, moods or arbitrary actions are collected. |
| `demo_start` | `entry_point`: `hero`, `navigation`, `footer`, `contact`, `computer` | Count of inquiry-path entry actions | This is neither a submission nor a lead. Repeated deliberate entries may create repeated events. |
| `demo_submit_error` | `error_type`: `validation`, `network`, `rate_limited`, `unavailable`, `server` | Count of failed attempts | No field name, error detail, user input, response body or stack trace |
| `generate_lead` | `acceptance`: `smtp_accepted` | Count of server-confirmed SMTP-accepted inquiry responses observed by consented browsers | Never on click, submit initiation, thank-you page, timeout, honeypot rejection or nonaccepted response. No CRM qualification or mailbox receipt implied. |
| `web_vital` | `metric_name`: `CLS`, `INP`, `LCP`; `metric_value`; `metric_rating`: `good`, `needs-improvement`, `poor`; finite `page_path` | CLS is a unitless score, rounded to four decimals. INP/LCP are integer milliseconds. | Missing/unsupported/blocked observations stay missing; never replace them with zero or a lab score. |
Each event contains an absolute `page_location` built only from the approved canonical origin and the finite route whitelist, plus a fixed title, empty `page_referrer`, and configured destination ID. Unknown paths become the fixed `/404/` bucket. The visitor's real hostname, raw URL, query, fragment, arbitrary title and referral URL are never copied. This restores GA4 hostname/page reporting without publishing visitor input. Google's configuration contract defines `page_location` as a full URL; the earlier relative-value implementation produced an empty hostname in the live Data API baseline. [Google page configuration](https://developers.google.com/analytics/devguides/collection/ga4/reference/config#page_location)
The property reporting contract registers twelve event-scoped dimensions: `page_path`, `referral_source`, `referral_evidence`, `scene_id`, `interaction`, `entry_point`, `error_type`, `acceptance`, `interaction_stage`, `project_intent`, `metric_name`, and `metric_rating`. The `metric_value` custom metric uses STANDARD units: filter `metric_name` before interpreting it, because CLS is unitless and INP/LCP are milliseconds. Do not sum different vitals or call a mixed average meaningful. `generate_lead` is the sole new key-event registration, once per event; its meaning remains SMTP acceptance, not qualification or revenue. Existing historical key-event definitions are preserved, not emitted or relabeled by this site.
The success caller must require an HTTP success response plus `ok === true`, `status === 'accepted'`, and a string `requestId`. That request ID remains operational data; it is never sent to analytics or saved in browser storage. A memory-only cache suppresses already-emitted receipt IDs across SPA navigation and consent withdrawal/regrant for 30 minutes, with a maximum of 100 entries and oldest-entry eviction. No IDs are added while consent is denied. A full page reload clears this memory; it is bounded duplicate protection, not a cross-browser identity system. The form blocks concurrent submits and switches to its accepted state after confirmation. Backend idempotency remains the authority for SMTP duplicate suppression. No server analytics event or CRM import duplicates this browser event. A response lost before reaching the browser can leave an accepted inquiry without a measured lead event.
For an inquiry funnel, declare the numerator and denominator before reporting: e.g. consented `generate_lead` event count divided by consented `demo_start` event count in the same timezone and window is an **event ratio**, not unique visitor conversion rate. Repeated starts, returning visits, failures, consent gaps and response loss affect it. A qualified-inquiry count requires a separate real business review, with reviewed, rejected and unresolved outcomes. Revenue requires actual authorized revenue records. Nothing in this implementation creates those business outcomes.
## Consent and data flow
The implementation uses **basic mode**: no Google script, data layer, analytics event queue, metric import, network request or analytics cookie is created before a valid opt-in. On opt-in it queues denied defaults, grants only `analytics_storage`, applies safe configuration, loads one Google tag, and sends the current route. Advertising storage, ad user data and ad personalization remain denied. Google documents that basic mode blocks tags entirely until permission is granted. [Google consent mode overview](https://developers.google.com/tag-platform/security/concepts/consent-mode)
Consent is stored locally under `tsc.analytics-consent.v1` as version, choice and timestamp for up to 180 days. It contains no identity or activity history. Corrupt, future-dated, expired or unreadable values default to unset. If storage is unavailable, the current in-memory choice works and the visitor may be asked again next visit. A storage event withdrawing consent stops other open tabs; a grant in another tab does not initiate collection here. Expiration is checked before event dispatch and when page visibility changes.
Withdrawal sets `window['ga-disable-<ID>'] = true` **before** the denied consent update, drops queued commands, removes a pending script, and deletes accessible `_ga`, `_ga_*`, `_gid` and `_gat*` cookies across current host/parent domain and accessible path variants. The essential choice record remains so a decline can be remembered. A previously executed tag cannot be unloaded from JavaScript; its documented disable flag prevents further collection and cookie writes. Already transmitted data and an already in-flight request cannot be recalled by withdrawing consent. Any historical data deletion request needs the separate account process. [Google privacy controls](https://developers.google.com/tag-platform/security/guides/privacy)
New analytics cookies are host-scoped, rooted at `/`, limited to 180 days without extending expiry on activity, and have Secure/SameSite settings. No User-ID, cross-domain linker, Ads integration, Google Signals, URL passthrough, user-provided data, or session recorder is added.
Web Vitals imports the standard `web-vitals` build only after opt-in; withdrawal before the queued import begins cancels it. Callbacks pick only scalar name/value/rating; performance entries, IDs, selectors, targets, URLs and attribution objects are excluded. Each observer is registered once per document. An uninterrupted valid configuration refresh preserves that observer set and uses the current approved destination. Revocation or invalid configuration permanently invalidates those callbacks for that document, including after regrant; reload to start fresh metrics. Metrics cover the document’s navigation, whose browser performance timeline can begin before the consent click. SPA route changes do not establish new navigation-level Core Web Vitals; metric context stays with its initial document route, even when consent is granted after client-side navigation. Consented real-user samples must be reported with sample count, observation window and device cohort, separately from laboratory tests. [GoogleChrome web-vitals](https://github.com/GoogleChrome/web-vitals)
## Attribution and discovery evidence
Raw UTM data and referrer strings are inspected transiently only after consent, reduced to finite categories, and neither persisted nor emitted. Exact allowed source values are `chatgpt.com`, `perplexity.ai`, `claude.ai`, `copilot.microsoft.com`, and `gemini.google.com`. Referrer hosts additionally recognize `chat.openai.com`, `google.com` and `bing.com` (optional `www.` prefix); other hosts reduce to `other_referral`. Missing or invalid evidence is `unattributed`/`unavailable`. Regional search hosts may remain unclassified. A lookalike such as `chatgpt.com.attacker.example` never becomes a ChatGPT referral.
The `referral_evidence` field distinguishes `allowed_utm` from `referrer_host` and `unavailable`. Visitor-supplied UTMs are observed labels, not independently verified exposure. A referral cannot establish the exact answer, prompt, citation, or original customer journey. All campaign fields are explicitly overwritten: only finite source/medium values survive; campaign name, ID, term and content become `not_collected`.
Current Google documentation defines AI Assistant using medium `ai-assistant` and includes Google AI Overviews/AI Mode within Organic Search. This adapter maps recognized assistant evidence to that documented medium, search evidence to `organic`, other referrers to `referral`, and absent evidence to `unknown`. Empty real referrers and deliberate campaign minimization mean these are the site’s limited classifications; check actual GA reports before promising complete acquisition reporting. Keep event, session and first-user dimensions distinct. [GA4 default channel definitions, checked 2026-09-13](https://support.google.com/analytics/answer/9756891?hl=en)
Search Console/Bing verification tags do not install a report or establish indexing. An authorized operator must verify the actual property, report availability, dimensions, filters, period, timezone, completeness and extraction method. Preserve real exports privately. Citation counts, search impressions/clicks, analytics referrals, accepted inquiries, qualified leads and revenue stay separate. Do not derive missing click counts from citations or infer prompts from grounding phrases. Current account/sitemap/index-inspection observations are recorded in the integration report; they do not measure qualified leads, revenue or AI citations.
## Launch account steps and browser verification
1. Reuse property `533588991`, rebuild stream `15768871672`, and public ID `G-RNRQK2CRDY`; do not create another property or stream to repeat this setup. The observed reporting timezone is `America/Los_Angeles`; event retention is two months, user retention fourteen months, and activity resets user retention. These existing choices were preserved, not newly approved. Keep labeled test observations separate from customer activity; review and test any property filter before activating it.
2. **Keep Enhanced Measurement disabled for this stream.** The live Admin API readback shows its master switch disabled; in particular, automatic history pageviews and form interactions must stay off. `send_page_view: false` does not disable history events from Enhanced Measurement. Signals is disabled, email redaction enabled, and the current stream has no event-create/edit rules. Other Google tag UI settings and connected-tag behavior require their own observation; do not infer those from the master switch or the local build. Do not add a second GTM/GA4 installation. [GA4 manual pageviews](https://developers.google.com/analytics/devguides/collection/ga4/views)
3. The twelve dimensions, `metric_value` metric and once-per-event `generate_lead` definition above have been created and read back. Reuse them. The key event means SMTP acceptance, never qualification or delivered email. Historical key-event definitions were preserved. Reporting availability may lag configuration; retain the actual account observation time and review retention/deletion arrangements with the owner.
4. On an authorized test property, enable explicit debug mode or approved Tag Assistant. Open a clean browser. Before consenting and after declining, the Network panel must show **zero** requests to Google Tag Manager/Analytics and no GA cookies. Navigate, interact and submit a synthetic rejected form; no analytics should appear.
5. Allow analytics. Inspect the dedicated `window.tscAnalyticsDataLayer`, one tag request and actual GA collection requests. Confirm one manual pageview for initial/current route and each genuine route change, no automatic form events, no duplicated history pageviews, and no name/email/phone/message, raw URL/query/hash, UTM free text, error details or DOM data. Test a synthetic sensitive query string and a 404 path. Code tests prove command minimization; only live transport inspection verifies third-party wire behavior.
6. Trace one permitted synthetic inquiry against server SMTP acceptance. A validation error, rate limit, unavailable transport, network timeout and failed SMTP response must not emit `generate_lead`; one accepted browser response must emit it once. Reconcile operational acceptance separately from actual mailbox receipt. Never send real customer details merely to test analytics. [GA4 event setup and verification](https://developers.google.com/analytics/devguides/collection/ga4/events)
7. In DebugView, confirm the event names, parameters, consent state and count for that test device. Inspect ad consent remains denied and verify property filters. If events are absent, record unavailable collection and investigate blockers/configuration; do not report zero customer activity.
8. Withdraw consent while active and while the tag is still loading. Confirm GA cookies disappear, the disable flag is true, later route/form/vital activity emits no new requests, and the site remains usable. Repeat after reload, with denied local storage, across two tabs, and on mobile. Inspect an actual request after a route change as well as the initial request; third-party automatic behavior can only be accepted after this test.
The live network, DebugView and external-account steps describe verification requirements, not blanket claims of completion. Read `docs/MEASUREMENT-SEARCH-VERIFICATION.md` for what was actually observed, including any unavailable gate. A newly added measurement ID must not be activated merely because it passes syntax validation; this release preserves the existing authorized ID and repairs its page context.