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.
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
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.
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.
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 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).
So: one event definition (name + params), two outputs (server MP vs client gtag).
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 and API Secret (and optionally Container ID) are stored in the Project panel. They are injected into the snippet and event builder; 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.
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). 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:
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.
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:
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)
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.
Blueprint