Skip to main content

DEV analytics isolation candidate

Tracking: ecohash/ecolink#94, #95 and #103. Status: Draft; DEV acceptance pending.

Production and DEV both use the dev branch. Deployment host/context and explicit configuration select the environment. Never infer it from the branch or image tag.

DEV destination: GA4 property 552988512, stream 15729052680, measurement ID G-PH01X8R08K. DEV GTM: GTM-MRQP5H9C. Production public GTM remains GTM-NVT22VHK. The DEV container must be configured for all three surfaces, manual page_view, consent gating, hostname restrictions and cookie_prefix=ecohash_dev / cookie_domain=dev.ecohash.com before coordinated acceptance. Do not publish a partial GTM draft.

DEV consent/attribution names end in _dev and use .dev.ecohash.com. GA cookies use the ecohash_dev prefix. Never reuse or delete parent-domain production cookies from DEV. No API secret belongs in a frontend bundle or this document.

Build configuration​

Marketing: NEXT_PUBLIC_ANALYTICS_ENV=development, NEXT_PUBLIC_GTM_ID=GTM-MRQP5H9C, NEXT_PUBLIC_API_URL=https://api.dev.ecohash.com. Pass these as Docker build arguments; runtime variables cannot replace inlined values.

Docs: ANALYTICS_ENV=development, GTM_ID=GTM-MRQP5H9C as Docker build arguments.

Console: runtime GTM_ID=GTM-MRQP5H9C and GA4_MEASUREMENT_ID=G-PH01X8R08K. Worker remains GA4_MP_ENABLED=false until separate ingestion acceptance, with credentials referenced from ecolink-ga4-dev-secret.

Acceptance and rollout​

Record SHA, image digest and existing DEV rollback digest before deployment. Apply only on ecolink-control-plane-dev, namespace ecolink. Check denied/granted/withdrawn consent, existing production cookies, SPA duplicate page views, cross-surface attribution, malformed consent and incorrect destination settings. Validate captured request destinations and actual DEV ingestion separately. Local tests/build success are not DEV acceptance. Recheck pending queue before enabling backend sending.

Keep the MR Draft until all DEV checks pass. Owner approval is required for merge; no production deployment or auto-merge.

Reference: https://developers.google.com/analytics/devguides/collection/ga4/reference/config (cookie_domain and cookie_prefix).

Review follow-up — 2026-09-07 (v2 candidate)​

  • The build fails closed unless (environment, GTM container[, API URL]) is a reviewed tuple in ANALYTICS_BUILDS; the marketing site validates the tuple in next.config.ts so every build path (CI, deploy script, direct docker build) is covered. qa keeps cookie isolation but is intentionally not a trackable build.
  • Consent grants are accepted only in the supported v1:analytics=granted:<epoch> form, in the inline bootstrap and in the runtime reader.
  • analytics-environment.ts is shared verbatim between ecolink-web (lib/) and ecolink-docs (src/); tests/fixtures/analytics-contract.json and CONTRACT_VERSION pin the behaviour in both repositories and must change together.