# Blueprint – Comprehensive Guide **Blueprint** is an implementation toolkit for consultants and teams planning and delivering tracking projects: cross-domain GA4, measurement frameworks, step-by-step guides, checklists, and server- and client-side event code. This guide describes every major feature and how the pieces fit together. --- ## Table of contents 1. [What Blueprint is and who it’s for](#1-what-blueprint-is-and-who-its-for) 2. [Core concepts: projects and data](#2-core-concepts-projects-and-data) 3. [Navigation and sections](#3-navigation-and-sections) 4. [Project panel](#4-project-panel) 5. [Cross-Domain](#5-cross-domain) 6. [Installation Methods](#6-installation-methods) 7. [Configurations](#7-configurations) 8. [Server-side (GA4 Measurement Protocol)](#8-server-side-ga4-measurement-protocol) 9. [Measurement Framework](#9-measurement-framework) 10. [Implementation Guides](#10-implementation-guides) 11. [GTM Integration](#11-gtm-integration) 12. [Testing & Validation](#12-testing--validation) 13. [Implementation Checklist](#13-implementation-checklist) 14. [Stakeholder Interviews](#14-stakeholder-interviews) 15. [Snippet Library](#15-snippet-library) 16. [Valued Resources](#16-valued-resources) 17. [Export deliverable and Backup & restore](#17-export-deliverable-and-backup--restore) 18. [Events: server-side and client-side](#18-events-server-side-and-client-side) 19. [Pricing, Account, Contact, Admin](#19-pricing-account-contact-admin) 20. [Auth, sync, and limits](#20-auth-sync-and-limits) 21. [Technical setup](#21-technical-setup) --- ## 1. What Blueprint is and who it’s for Blueprint is a **single-page app** that helps you: - **Plan** tracking work (domains, objectives, frameworks, checklists). - **Document** it (implementation guides with steps, code, and best practices). - **Implement** it (copy-paste snippets for cross-domain linking, GA4 config, server-side events, and client-side gtag). It is aimed at: - **Implementation consultants** who run multiple client projects and need one place for domains, notes, code, and handoff docs. - **Teams** that want a shared toolkit for GA4 and cross-domain setups without scattering code in emails or wikis. Data can be used **locally only** (browser storage) or **synced** via Supabase when you sign in. Plan limits (e.g. number of projects) apply when using the synced backend. --- ## 2. Core concepts: projects and data ### Projects A **project** is the main container for one client or engagement. Each project has: - **Name** and **notes** - **Domains** (one per line) – primary domains to track - **External domains** (e.g. payment, portals) – for cross-domain config - **GA4 Measurement ID** (e.g. `G-XXXXXXXXXX`) - **Measurement Protocol API Secret** – for server-side GA4 - **GA4 Property ID** (optional) – numeric ID (e.g. `123456789`) from GA4 Admin → Property settings. Used for **Open DebugView / Realtime** links and **Recent events in GA4** in the Server-side section so you can confirm test events in GA4. - **GTM Container ID** (e.g. `GTM-XXXXXXX`) – for reference/handoff - **Checklist state** – which Implementation Checklist items are done - **Saved server events** – events built in the Server-side section and optionally injected into the server-side snippet Projects are listed in the **Project** dropdown at the top. The selected project drives: - Which domains appear in cross-domain and configuration snippets - Which measurement ID and API secret are used in server-side code - Which saved events are shown and injected - Which checklist state is shown Project selection is **persisted** (e.g. in `localStorage` or per user when signed in), so refreshing the page keeps the same project. ### Other data (not per-project) - **Guides** – Implementation Guides are stored as a separate list (per user when synced). They are not “inside” a project; you pick a guide from its own dropdown. - **Frameworks** – Measurement frameworks are stored separately. A project can **link** to one framework (optional) so the grid shows that framework’s rows. - **Checklist** – Checklist state is stored **per project**; each project has its own checked/unchecked list. When you **sign in**, projects, guides, and frameworks sync to Supabase so you can use the same data across devices and browsers. --- ## 3. Navigation and sections The **sidebar** lists all sections. Click a section to view it; the main content area shows one section at a time. A **search** field filters sections by keywords. Sections: | Section | Purpose | |--------|--------| | **Blueprint Overview** | Intro, what’s in the app, get started | | **Cross Domain** | Cross-domain tracking problem, solution, domains, code, download | | **Installation Methods** | GTM, direct HTML, WordPress setup | | **Configurations** | Basic, ecommerce, SaaS, advanced options and code | | **Server-side** | GA4 Measurement Protocol: snippet, event builder, saved events | | **Measurement Framework** | Objectives, events, KPIs grid; export | | **Implementation Guides** | Step-by-step guides with steps, code, do’s/don’ts; Generate from gaps (AI); export Markdown | | **GTM Integration** | Import GTM container JSON, compare to framework, export GTM setup from project | | **Testing & Validation** | Validation checklist and test suite | | **Implementation Checklist** | Pre-implementation → GTM → Config → Testing → Validation → Documentation | | **Stakeholder Interviews** | Stakeholder list per project, takeaways, question bank, templates | | **Snippet Library** | Reusable snippets with placeholders (GA4, GTM, cross-domain, etc.) | | **Valued Resources** | Curated links (GA4/GTM docs, testing tools); sections set by admins | | **Pricing** | Plans, limits, Subscribe | | **Admin** | Plans & pricing, settings (theme style, app notice, Brevo), email, users (admin only) | | **Contact** | Support / contact form | | **Account** | Sign out, billing portal, backup & restore, delete account | --- ## 4. Project panel At the top of the app, the **Project** bar includes: - **Project dropdown** – Select a project or “— New project —”. - **New project** – Creates a new project and selects it. When a project is selected, you can edit (in the Project panel or in context): - **Name**, **Notes** - **Domains** (one per line) - **External domains** - **Measurement ID**, **API Secret**, **Container ID** - **AI: Extract requirements** – Paste or import text (e.g. from Google Docs Published to web) to extract objectives, KPIs, events, stakeholders. Apply to project to populate. These fields are used by: - Cross-domain and configuration snippets (domains, measurement ID) - Server-side snippet and event builder (measurement ID, API secret) - Saved events (stored on the project; optional “include in snippet” per event) --- ## 5. Cross-Domain This section explains **cross-domain tracking** and gives you copy-paste code. - **Problem** – Why sessions and attribution break when users move across domains. - **Solution** – Link domains with a stable `client_id` and decorated links (`_gl`). - **Domains** – The list is taken from the **current project’s domains** (or a default). Snippets are generated with these domains. - **Code** – You get a production-ready script (CrossDomainLinker-style) and instructions. **Download Full Script** gives you the full implementation file. Use this section to hand off or implement the cross-domain linker; keep domains in the project so the snippets stay correct. ### 5.1 Tag communication & taxonomy (Overview tab) In the Cross-Domain **Overview** tab, a **Tag communication & taxonomy** card explains how measurement tags communicate (cross-domain, within-page, attribution, implementation) and how a consistent event/parameter taxonomy keeps implementations aligned. The panel is **dynamic**: - **Live taxonomy count** – “This taxonomy includes X event types and Y parameters” (tied to the same vocabulary used in the Event builder). - **Collapsible pattern cards** – Four areas (Cross-domain, Within-page, Cross-campaign attribution, Implementation patterns); expand the one you need. The first card that matches your project (e.g. has domains → Cross-domain) can open by default. - **In Blueprint** – Each pattern has links that jump you to the right place (e.g. Project panel, Server-side, Domain list validator, Measurement Framework, Event builder, Implementation guides, Snippet Library). - **CTA row** – Buttons to **Open Event builder** and **Open Measurement Framework** for a quick next step. - **Relevant to you** – If you have a project selected, the app may show hints such as “Your project has N domain(s).”, “Server-side / Event builder is set up.”, or “You’re using a prefix; taxonomy applies to unprefixed event names.” - **View by** – Toggle between **Communication layer** (the four patterns above) and **Tool** (GA4, GTM, Adobe, Server-side) so you can see the same concepts grouped by platform with direct links into the app. --- ## 6. Installation Methods Installation describes **how** to deploy the cross-domain and GA4 setup: - **GTM** – Use a Custom HTML tag, domain list variable, trigger, and GA4 config. - **Direct HTML** – Paste script and config into the site. - **WordPress** – Where to add code (e.g. theme or plugin). The content is step-by-step; code blocks often use the current project’s **Measurement ID** and **domains** where relevant. --- ## 7. Configurations Configurations provide **ready-made options** (Basic, Ecommerce, SaaS, etc.) and the corresponding code. You pick a configuration; the app shows the snippet with the **current project’s domains** and **Measurement ID** injected. Use this to tailor the cross-domain/GA4 setup (e.g. ecommerce, form tracking) and copy the result. --- ## 8. Server-side (GA4 Measurement Protocol) The Server-side section is where you work with **GA4 Measurement Protocol (MP)**: server-side events that send data to GA4 from your backend (or a proxy) instead of only from the browser. ### 8.1 Full server-side snippet A **code block** shows a complete server-side script that: - Uses the project’s **Measurement ID** and **API Secret** - Defines a `sendToGA4(clientId, events)` helper that POSTs to GA4’s `mp/collect` (or debug endpoint) - Can include **saved events** (see below) so the snippet contains real event definitions, not only a placeholder You can **copy** or **download** this block (e.g. `ga4-server.js`) and use it in your backend. The snippet is updated when you change the project, measurement ID, API secret, or saved events. ### 8.2 Event builder (“Send test event”) The **event builder** lets you construct a single event and either send it or copy it. - **Event name** – e.g. `page_view`, `purchase`, custom name. - **Parameters** – Key/value pairs (e.g. `page_location`, `page_title`). You can add and remove rows. - **Client ID** (optional) – For “Send test event”; leave blank to use a test value. - **Validate only** – If checked, the request goes to the **debug** endpoint so you can verify in GA4 DebugView without sending live data. Actions: - **Send test event** – Builds the event payload and POSTs to GA4 `mp/collect` (or `debug/mp/collect`). Result is shown on the page (success or error). - **Copy event code** – Copies the **server-side** call: `sendToGA4(clientId, [{ name: '...', params: { ... } }]);` - **Copy as gtag (client-side)** – Copies the **same** event as a **client-side** call: `gtag('event', '...', { ... });` so you can use it in the browser where gtag is loaded (see [§17](#17-events-server-side-and-client-side)). **After you send a test event**, the app can show: - **Validation detail** – When using “Validate only”, a short summary confirms the payload is valid or lists any validation messages from GA4. - **Open in GA4** – If the project has a **GA4 Property ID** set, links appear to open **DebugView** and **Realtime** in GA4 for that property. - **Recent events in GA4** – A panel lets you **Fetch recent events** (realtime, last ~30 minutes) from GA4. If your project has GA4 Property ID and the same service account as GA4 Audit is configured, you see event names and counts. When the event you just sent appears in the list, the app confirms **“Your test event [name] is in GA4”** and highlights that row. After a successful send, the list can auto-refresh after a few seconds. So: one event definition (name + params), two outputs (server MP vs client gtag), plus in-app confirmation that the event reached GA4 when GA4 Property ID is set. ### 8.3 Saved events You can **save** the event you built (or edit a saved one) so it lives on the **current project**. - **Save as…** – Prompts for a name (e.g. “Homepage page_view”), then adds the event to the project’s saved list. - **Saved events list** – Each item shows: - Name and event type - **In snippet** – Checkbox: if checked, this event is **included** in the full server-side code block (in the `events` array and `sendToGA4(clientId, events)` call). If unchecked, the event stays in the list but is not injected. - **Edit** – Loads that event into the builder; you can change name/params and click **Update**. - **Delete** – Removes it from the project. The **server-side code block** at the top of the section is built from: - The base MP script (measurement ID, API secret, `sendToGA4` helper) - Plus all saved events that have **In snippet** checked, as a single `events` array and one `sendToGA4(clientId, events)` call So you maintain a list of events per project and choose which ones are actually included in the downloadable snippet. ### 8.4 Project IDs (safe keeping) The Server-side section also reminds you that **Measurement ID**, **API Secret**, and optionally **GA4 Property ID** and **Container ID** are stored in the Project panel. Measurement ID and API Secret are injected into the snippet and event builder. **GA4 Property ID** (numeric) is used for “Open DebugView / Realtime” links and “Recent events in GA4” so you can confirm test events. The Container ID is for reference/handoff only. --- ## 9. Measurement Framework The Measurement Framework section helps you align **objectives, events, and parameters** in a grid. - You choose **business type** (e.g. multi-brand, ecommerce) and **objectives/channels** (e.g. acquisition, retention). - The app shows a **grid** of objectives, key metrics, events, and parameters (and optionally priority, etc.). - You can **copy** the grid as text, **export CSV**, or **export Markdown** (implementation brief). Frameworks are stored separately; a **project** can optionally link to one framework so the grid reflects that framework. The grid is useful for scoping and handoff (“these are the events we’ll implement”). --- ## 10. Implementation Guides Implementation Guides are **step-by-step documents** you create and edit: title, steps, do’s/don’ts, and optional **code** per step. They are ideal for client handoffs, runbooks, or internal playbooks. ### 10.1 Creating and editing guides - **Guide dropdown** – Select an existing guide or “— New guide —”. - **New guide** – Creates a new guide and clears the form. - **Title** – Guide name. - **Steps** – Each step has: - **Step number** (auto) - **Title** - **Body** (textarea) - **Image** (optional) – Upload or paste URL - **Code** (optional) – See [§10.2](#102-code-per-step) - **Move up / Move down** – Reorder steps. - **Remove** – Delete the step. - **Add step** – Appends a new blank step. - **Do’s / Don’ts** – Bullet lists (one item per line). Guides are saved when you **save** (or switch guide / create new, depending on app behavior). When signed in, they sync to Supabase. ### 10.2 Code per step For any step you can attach **code** so the guide contains both instructions and copy-paste snippets. - **Add code** (or **Edit code**) – Opens a panel for that step. - **Code for this step** – Dropdown: - **None** – No code. - **Bespoke (custom)** – Free-form text/code in a textarea (e.g. GTM snippet, custom JS). - **Server-side snippet** – The **full** server-side code block for the **current project** (measurement ID, API secret, and all “in snippet” saved events). Updates when the project or saved events change. - **Client-side (gtag)** – A block of **gtag** calls for all **in-snippet** saved events of the current project (see [§17](#17-events-server-side-and-client-side)). Good for “paste this in your page/tag” steps. - **Event: [name]** – A single saved event: server-side `sendToGA4(...)` call for that event. Dropdown lists the project’s saved events. So the same events you build and save in the Server-side section can be **injected into a guide step** as server-side code, client-side gtag, or a single event. - **Copy** – Copies the resolved code (bespoke text or generated snippet) to the clipboard. - **Hide code** – Collapses the panel; the step still stores the choice (bespoke/snippet/gtag/event). When you **export the guide to Markdown**, steps that have code get a fenced code block (```) containing the resolved code (bespoke or generated). ### 10.3 Reordering steps Each step has **↑** (Move up) and **↓** (Move down). Use them to reorder; step numbers update automatically. Order is saved with the guide. ### 10.4 Templates and export - **Templates** – You can start from a template (e.g. “GTM implementation”, “Handoff checklist”) that pre-fills steps and do’s/don’ts. - **Export to Markdown** – Downloads the guide as a `.md` file (title, steps with body and code blocks, do’s, don’ts). Useful for version control, sharing, or converting to PDF/Word. ### 10.5 AI Assist AI Assist uses OpenAI to speed up requirements gathering and guide generation. Requires Supabase, the `ai-assist` Edge Function, and `OPENAI_API_KEY` in Supabase Edge Function secrets. **Requirements extraction** (Project panel → "AI: Extract requirements"): Paste or import text (e.g. from Google Docs Published to web, GitHub raw, Pastebin, Notion). AI extracts objectives, KPIs, events (GA4-style), stakeholders, timeline, project notes, and **structured measurement framework rows** (objective, key metric, events, params, priority per row). **Apply to project** populates the project and framework grid; when the framework already has rows, new framework rows are merged in (duplicates skipped). Falls back to adding events as a single row if framework rows are not returned. **Gap-to-guide** (Implementation Guides → "Generate from gaps"): Uses your Measurement Framework, GTM import, and project context. Computes **missing events** (framework events not found in GTM) and generates a bespoke implementation guide focused on filling those gaps. **Cost control:** Input/output limits apply (e.g. 25k chars for extract, 30 framework rows, 4k tokens for extract, 4k for guide). --- ## 11. GTM Integration The **GTM Integration** section connects your Blueprint project with Google Tag Manager so you can analyze an existing container or generate one from your project. - **Import from GTM** – Upload a GTM container export (JSON file from GTM → Admin → Export). The app parses the file and shows a **summary** (counts of tags, triggers, variables, and tag types) and a **list of tags** so you can see what’s in the container. - **Framework comparison** – Compares the **events** defined in your current project’s **Measurement Framework** with the events found in the imported GTM container. You see which framework events are already implemented in GTM (covered) and which are missing. The comparison updates when you change the selected project or framework. - **Export to GTM** – Generates a **GTM-compatible JSON** file you can import into Google Tag Manager. The export includes variables for **Measurement ID** and **Domain List** (filled from the current project’s measurement ID and domains), and a **GA4 Configuration** tag set to fire on GTM’s built-in “All Pages” trigger. Use this to bootstrap a new container or hand off a minimal GA4 + cross-domain–ready setup. Use **GTM Integration** to audit a client’s live container against your plan, or to export a clean GTM setup from Blueprint into GTM. --- ## 12. Testing & Validation This section provides a **validation checklist** and **test suite** for cross-domain and GA4: - How to verify link decoration (`_gl`), client_id consistency, and GA4 Real-time. - Console and manual test steps (e.g. run a snippet in the console, check Network tab). It’s the “did we implement it correctly?” companion to the Implementation Checklist. --- ## 13. Implementation Checklist The Implementation Checklist is a **progress list** for a single implementation: Pre-implementation → GTM Setup → Configuration → Testing → Validation → Documentation. - **Per project** – Each project has its own checklist state (checked/unchecked). Select the project to see and tick its checklist. - **Progress bar** – Shows the percentage of items checked. - **No code on checklist** – Code attachment (bespoke, snippet, gtag, event) lives in **Implementation Guides** (per step), not on checklist items. The checklist stays a lightweight “done / not done” list. So: use the **checklist** to track progress; use **guides** for the actual steps and code. --- ## 14. Stakeholder Interviews The Stakeholder Interviews section helps you **run and document** stakeholder interviews per project. - **Stakeholder list** – Add stakeholders with name, role, and **Takeaways** (notes from the interview). The table shows a truncated preview; **Edit** opens a modal to edit takeaways. - **Copy takeaways to project notes** – Compiles all stakeholder takeaways into a formatted block and **appends** it to the current project’s Notes field. - **Question bank** and **templates** (pre-meeting one-pager, agenda, summary) are edited in **Admin → Stakeholder Interviews** and shared for all users. Markdown is supported in templates. --- ## 15. Snippet Library The Snippet Library holds **reusable code snippets** (GA4, GTM, cross-domain, server-side, consent, etc.) with **tags** for filtering. - **Placeholders** – Snippets can use placeholders such as `{{MEASUREMENT_ID}}`, `{{DOMAINS_ARRAY}}`, `{{API_SECRET}}`. When you **Copy**, the app replaces these with the **current project’s** values. - **Built-in snippets** – A set of default snippets (e.g. GA4 config, GTM, cross-domain, server-side) are viewable and copyable but not editable or deletable. - **Your snippets** – Add, edit, delete, and tag your own snippets. The preview panel shows the resolved code; **Copy** uses the current project for placeholders. --- ## 16. Valued Resources Valued Resources is a **curated list of links** (official GA4/GTM docs, testing tools, events reference, best-practice sites) grouped into sections. - Sections and links are edited in **Admin → Resources** and shared for all users. Each section has an icon (emoji), title, description, and links (URL, label, optional meta). --- ## 17. Export deliverable and Backup & restore ### Export deliverable From the **Project** panel, **Export deliverable** opens a modal where you choose sections to include: cover, table of contents, implementation guide, framework grid, checklist, and project notes. You can **Download HTML** (open in Word or print to PDF) or **Print / Save as PDF** directly. Useful for client handoffs. ### Backup & restore In **Account**, the **Backup & restore** card provides: - **Export backup** – Downloads a JSON file (`blueprint-backup-YYYY-MM-DD.json`) containing all projects, guides, and frameworks (from localStorage when not synced, or from the server when signed in). - **Restore from file** – Upload a backup JSON file to **replace** all current projects, guides, and frameworks after confirmation, then refreshes the UI. --- ## 18. Events: server-side and client-side The **same event definition** (event name + parameters) can be used in two ways: 1. **Server-side (Measurement Protocol)** – Your backend (or proxy) sends a POST to GA4 `mp/collect` with `client_id` and `events`. The app generates `sendToGA4(clientId, events)` and injects saved events into the full snippet. 2. **Client-side (gtag)** – In the browser, with gtag loaded (e.g. via GA4 config tag), you fire `gtag('event', eventName, params)`. The app can output the same event as a gtag call. So the events you build in the **event builder** and **save** are reusable: - **Copy event code** – Server-side: `sendToGA4(clientId, [{ name: '...', params: { ... } }]);` - **Copy as gtag (client-side)** – Client-side: `gtag('event', '...', { ... });` In **Implementation Guides**, when you add code to a step: - **Server-side snippet** – Full MP script including all “in snippet” saved events. - **Client-side (gtag)** – Block of `gtag('event', ...)` lines for all “in snippet” saved events (with a short comment and measurement ID). - **Event: [name]** – One server-side `sendToGA4(...)` call for that saved event. So: one set of events, consistent naming and params, and the app gives you both server and client code. --- ## 19. Pricing, Account, Contact, Admin - **Pricing** – Lists plans and limits (e.g. project count). **Subscribe** sends you to Stripe Checkout; after payment, the backend updates your plan (via webhook). - **Account** – Sign out; **View invoices & billing** (Stripe customer portal); **Backup & restore** (export/restore all data); **Delete account** (removes user and data). - **Contact** – Support or contact form (when a support email is configured). - **Admin** (admin users only) – **Plans & Pricing** (link Stripe Price IDs, edit limits); **Settings** (support email, hide free plan, Brevo sender, **app-wide notice**, **Theme style** (Default or Airbnb: Nunito Sans, subtler corners; only admins see this)); **Email** (send to users by role/plan); **Users** (view/manage); **Stakeholder Interviews** (question bank, templates); **Checklist** (sections and items); **Resources** (Valued Resources sections and links). App-wide notice is configured in Admin → Settings and shown in a banner when set. --- ## 20. Auth, sync, and limits - **Sign in** – Email/password or Google (Supabase Auth). When signed in, projects, guides, and frameworks sync to Supabase. - **Sync** – Create/edit/delete projects, guides, and frameworks; they are stored in the database and available on other devices/browsers where you sign in. - **Limits** – Plan limits (e.g. number of projects) are enforced when using the synced backend. Pricing section and Admin → Plans define these. --- ## 21. Technical setup For **running locally**, **deploying (e.g. Vercel)**, **Supabase** (migrations, auth, RLS), **Stripe** (Checkout, webhook, billing portal), and **admin email (Brevo)**, see the main **README.md** in the repo. It covers: - `npx serve .` and opening `http://localhost:3000` - Vercel env vars and build - Supabase migrations (order, auth URLs, setting an admin) - Stripe products, prices, webhook, Edge Functions, linking Price IDs in Admin - Edge Function secrets and troubleshooting (e.g. 401 on Subscribe) --- *This guide describes Blueprint as of the latest implementation: projects, cross-domain, installation, configurations, server-side event builder and saved events, measurement framework, implementation guides (with per-step code and reordering), GTM Integration (import container, framework comparison, export to GTM), implementation checklist, stakeholder interviews, snippet library, valued resources, export deliverable, backup & restore, admin theme style, and dual output of events (server-side MP and client-side gtag). For a shorter quick-start and common tasks, see [USER_GUIDE.md](USER_GUIDE.md).*