← back to Consulting Designerwallcoverings Com
docs/gtag-theme-install.md
59 lines
# gtag → Shopify theme insertion instructions
**Snippet file:** [`snippets/gtag.html`](../snippets/gtag.html)
**Target:** the LIVE Designer Wallcoverings Shopify theme (`designer-laboratory-sandbox.myshopify.com`).
**Status:** GATED. Editing the live theme is customer-facing and production. Do **not** perform these steps autonomously — they are drafted in `~/.claude/yolo-queue/pending-approval/attribution-gtag-install.md` for Steve's approval. This file is the exact runbook that memo references.
> ⚠️ **Prerequisite:** the real `G-XXXX` measurement ID must exist first (from the gated GA4-property step). Installing the placeholder `G-XXXX` collects nothing. Do GA4 property → get ID → replace placeholder → then install.
---
## Option A — Shopify's native GA4 integration (preferred, lowest risk)
Shopify has a first-party GA4 connection that wires purchase + checkout events server-side without editing `theme.liquid`:
1. Shopify Admin → **Online Store → Preferences → Google Analytics** (or **Settings → Customer events**).
2. Paste the **`G-XXXX`** measurement ID into the Google Analytics 4 field / connect the Google & YouTube channel's GA property.
3. This auto-sends `page_view`, `view_item`, `add_to_cart`, `begin_checkout`, and `purchase` with the standard ecommerce schema.
4. Add any **DW custom events** (`request_sample`, `trade_account_signup`, `email_signup`) as a **Custom pixel** under Settings → Customer events, or via theme event handlers.
**Why preferred:** survives theme updates, no Liquid edit, purchase event carries the order's discount code in `coupon` automatically. Use this unless a custom `<head>` tag is specifically required.
---
## Option B — manual gtag in `theme.liquid` (when a raw tag is required)
1. **Back up first.** Shopify Admin → Online Store → Themes → ⋯ → **Duplicate** the live theme (so there's a one-click rollback). Do not edit the only copy.
2. Themes → ⋯ → **Edit code** → open `layout/theme.liquid`.
3. Paste the entire contents of `snippets/gtag.html` **inside `<head>`**, immediately after the `<meta charset>` / `<meta name="viewport">` lines and **before** any other `<script>`.
- Alternatively, add the file as a snippet named `gtag` and include it with `{% render 'gtag' %}` at the top of `<head>`.
4. **Replace both `G-XXXX` occurrences** with the real measurement ID.
5. **Save.** Shopify recompiles the theme immediately (this is live the moment you save).
6. Confirm `cookie_domain` matches the storefront apex (`designerwallcoverings.com`).
---
## Verification (either option)
1. **GA4 DebugView:** GA4 Admin → DebugView. Load `www.designerwallcoverings.com` with the GA Debugger extension (or `?_gl=` debug) → confirm `page_view` arrives in real time.
2. **Realtime report:** GA4 → Reports → Realtime → confirm your session with the correct property.
3. **Tag presence:** `curl -s https://www.designerwallcoverings.com/ | grep -o 'G-[A-Z0-9]\{8,\}'` → returns the real ID, not `G-XXXX`.
- Or run the analytics skill's verifier: `bash ~/.claude/skills/analytics/scripts/verify_rollout.sh`.
4. **UTM round-trip:** open a stamped link (`?utm_source=instagram&utm_medium=social-bio&utm_campaign=test`) → GA4 Realtime → confirm source/medium = instagram / social-bio.
5. **Coupon round-trip (after codes exist):** place a test order with `DW-IG-10` → confirm the `coupon` field appears on the `purchase` event and the redemption shows in Shopify Admin → Discounts.
---
## Rollback
- **Option A:** clear the measurement ID field / disconnect the GA property. Instant.
- **Option B:** Themes → publish the duplicated backup theme, OR remove the pasted block from `theme.liquid` and Save.
---
## Notes
- The placeholder `snippets/gtag.html` is intentionally inert (`G-XXXX`) so it can live in the repo without collecting data or risking a wrong-property leak.
- Enhanced measurement (scroll, outbound click, site search, video, file download) is toggled **in the GA4 web data stream settings**, not in this snippet.
- Never commit the real measurement ID as the only copy in a public place; it's low-sensitivity but keep the repo's committed snippet on the placeholder and substitute at install time.