Implementation toolkit
Blueprint
Plan, document, and implement tracking projects in one place. Create projects, store domains and notes, build server- and client-side events, write step-by-step guides with code, and tick off checklists. Sign in to sync everything across devices.
Plan
Cross Domain
Cross-domain tracking: problem, solution, and production-ready code. Domains from your project drive the snippets.
Configurations
Ready-made configs (ecommerce, SaaS, advanced) and copy-paste snippets using your project’s domains and measurement ID.
Measurement Framework
Objectives, events, and KPIs grid. Pick a framework, export CSV or Markdown for scoping and handoff.
Stakeholder Interviews
Question bank by theme, stakeholder list per project, and interview templates (one-pager, agenda, summary) with copy and export.
AI Assist
Extract requirements from RFPs or docs (Project panel) or generate implementation guides from framework gaps.
Implement
Installation Methods
Step-by-step setup for GTM, direct HTML, or WordPress. Choose how you deploy the cross-domain and GA4 setup.
Server-side
GA4 Measurement Protocol: build events, save them per project, send test events, and get a full snippet. Same events can be copied as client-side gtag.
Implementation Guides
Step-by-step guides with optional code per step (bespoke, server snippet, client gtag, or a single event). Reorder steps, export to Markdown.
Snippet Library
Save and tag reusable code snippets. Use placeholders like {{MEASUREMENT_ID}} and {{DOMAINS_ARRAY}}; they’re replaced with the current project when you copy.
Adobe
Analytics, Launch, Target: config snippets and event code. Add Report Suite ID and Tracking Server in Project; placeholders populate all snippets.
GTM Integration
Import a GTM container export to analyze tags and variables, compare against your framework, or generate a GTM setup from your project to import back.
Implementation Checklist
Pre-implementation → GTM → Config → Testing → Validation → Documentation. Per-project progress with a clear progress bar.
Validate & account
Testing & Validation
Validation checklist and test suite for link decoration, client_id, and GA4 Real-time. Confirm cross-domain and tracking work.
Valued Resources
Curated links for consultants: official GA4/GTM docs, testing tools, events reference, and best-practice sites.
Pricing
Plans and project limits. Subscribe to sync across devices and unlock more projects.
Contact
Get support or leave a message when a support email is configured.
Admin
Plans & pricing, app settings, email, and users. Visible only to admins.
Get started
· Full walkthrough: BLUEPRINT_GUIDE.md
Master Cross-Domain Tracking
Fix broken attribution, maintain session continuity, and accurately track users across multiple domains with our production-ready solution.
The Problem
When users navigate from website.com to portal.website.com, GA4 and Adobe Analytics treat them as:
Two Different Users
Session breaks, inflating user counts and destroying journey analysis
Wrong Attribution
All conversions credited to "portal.website.com / referral" instead of original source
Broken Marketing ROI
Can't track which campaigns actually drive conversions
The Solution
Our universal CrossDomainLinker handles everything automatically:
Automatic Link Decoration
Appends _gl parameter with client_id to all cross-domain links
Form Tracking
Injects hidden fields to maintain continuity through form submissions
SPA Support
Intercepts pushState/replaceState for single-page applications
Payment Processors
Track through Stripe, PayPal, and other external checkout flows
Dynamic Content
MutationObserver watches for new elements added after page load
Cookie Management
Handles SameSite=None, Secure flags, and domain configuration
Quick Start
// 1. Add script to your site
<script src="CrossDomainLinker.js"></script>
// 2. Initialize with your domains
<script>
const linker = new CrossDomainLinker({
domains: {{DOMAINS_ARRAY}}
});
</script>
// That's it! Cross-domain tracking is now active.
Using Adobe?
Adobe Analytics uses Visitor ID Service for cross-domain tracking (not a linker). Add your Report Suite ID and Tracking Server in the Project panel, then open Snippet Library and filter by adobe for the Visitor ID snippet and other Adobe configs.
Installation
Step-by-step instructions to implement cross-domain tracking on your site via Google Tag Manager, direct HTML, or Adobe Launch.
Domain list validator
Paste your domains (one per line). We’ll validate format and show which will be linked and any subdomain notes.
Method 1: Direct Implementation
Add the script directly to your website's HTML. This method works great for sites with full code access.
<!-- Add before closing </head> tag -->
<script src="/path/to/CrossDomainLinker.js"></script>
<script>
window.crossDomainLinker = new CrossDomainLinker({
domains: {{DOMAINS_ARRAY}},
measurementId: '{{MEASUREMENT_ID}}',
debug: false
});
</script>
Method 2: Google Tag Manager
Recommended for most implementations. Easier to manage and doesn't require code changes.
Step 1: Create Variables
// Variable Type: Custom JavaScript
// Variable Name: CrossDomain - Domain List
function() {
return [
{{DOMAINS_ARRAY_LINES}}
];
}
Step 2: Create Custom HTML Tag
<script>
{{CrossDomainLinker Script}}
window.crossDomainLinker = new CrossDomainLinker({
domains: {{DOMAINS_ARRAY}},
measurementId: '{{MEASUREMENT_ID}}',
debug: false,
onDecorate: function(data) {
dataLayer.push({
event: 'cross_domain_decorated',
cd_type: data.type,
cd_target: data.url.hostname
});
},
onError: function(error) {
dataLayer.push({
event: 'cross_domain_error',
error_type: error.type
});
}
});
</script>
Step 3: Configure Trigger
Trigger Type: All Pages
Fires On: Page View - All Pages
Priority: Set to fire before GA4 Config tag
Method 3: WordPress Plugin
For WordPress sites, add via theme's functions.php or a custom plugin.
function enqueue_cross_domain_linker() {
wp_enqueue_script(
'cross-domain-linker',
get_template_directory_uri() . '/js/CrossDomainLinker.js',
array(),
'2.0',
false
);
wp_add_inline_script('cross-domain-linker', "
window.crossDomainLinker = new CrossDomainLinker({
domains: {{DOMAINS_ARRAY}},
measurementId: '{{MEASUREMENT_ID}}'
});
");
}
add_action('wp_enqueue_scripts', 'enqueue_cross_domain_linker');
Method 4: Adobe Launch (Data Collection)
For Adobe Analytics, use Launch to deploy tracking. Add your Report Suite ID and Launch Property ID in the Project panel, then open Snippet Library and filter by adobe for the Launch embed, Visitor ID (cross-domain), and Analytics config snippets.
Configuration Examples
Pre-built configs for CrossDomainLinker (Google). For Adobe, use Snippet Library (filter: adobe) for Analytics, Launch, and Visitor ID snippets.
Basic Setup
Simple two-domain configuration
Configuration Options Reference
| Option | Type | Default | Description |
|---|---|---|---|
| domains | Array | [] | Primary domains to track across |
| includeSubdomains | Boolean | true | Auto-detect and track subdomains |
| externalDomains | Array | [] | External domains like payment processors |
| decorateLinks | Boolean | true | Automatically decorate cross-domain links |
| decorateForms | Boolean | true | Add hidden fields to cross-domain forms |
| measurementId | String | auto-detect | GA4 measurement ID (G-XXXXXXXXXX) |
| debug | Boolean | false | Enable console logging for debugging |
Adobe configs
Adobe Analytics, Launch, and Visitor ID configs use different patterns (AppMeasurement s object, Launch embed, Visitor API). Add Report Suite ID and Tracking Server in Project, then open Snippet Library and filter by adobe for ready-to-copy snippets.
Server-Side GA Tracking
Definitive GA4 Measurement Protocol code for server-side events. Only requires your Measurement ID (and API Secret) to activate. Store your Measurement ID and GTM Container ID in the Project panel. Using Adobe? Server-side is different (Data Collection API, etc.)—see Snippet Library (filter: adobe).
Why server-side?
Send events from your backend (Node, Python, etc.) to GA4 without browser code. Use for: server-rendered pages, webhooks, CRMs, email clicks, or any server-only context. GA4 Measurement Protocol is the official API; this snippet is ready to drop in with just your Measurement ID and API Secret (create one in GA4 Admin → Data Streams → your stream → Measurement Protocol API secrets).
Definitive server-side code
Replace {{MEASUREMENT_ID}} and {{API_SECRET}} (or set them in Project and copy from here). Container ID is for reference only; store it in the Project panel.
Send test event
Build an event and send it to GA4 via the Measurement Protocol. Uses this project's Measurement ID and API Secret. From a browser, validation-only (debug endpoint) works; for real events you may need to send from your backend if GA4 blocks cross-origin requests.
GA4 uses this to identify the user. For testing, leave empty and we'll generate one.
Saved events
Saved events are injected into the server-side code block above. Edit one to change it (then Update), or delete.
Project IDs (safe keeping)
In the Project panel you can store this project’s GA4 Measurement ID (e.g. G-XXXXXXXXXX) and GTM Container ID (e.g. GTM-XXXXXXX). The Measurement ID is injected into the code above when you have a project selected; the Container ID is for reference and handoff only.
Measurement Framework Builder
Define what to measure and how. Select your business type, objectives, and platform (GA4, GTM, or Adobe) to generate a framework that maps objectives to KPIs, events, and parameters.
Framework grid
| Objective | Key metric | Events | Parameters / dimensions | Priority | Status | Data layer / GTM | Actions |
|---|
Implementation Guides
Build step-by-step implementation guides with best practices, do's and don'ts, and export to Markdown for handoffs and documentation. Start from a template or save your own.
Start from a template or create your own
Templates include pre-filled steps and best-practice callouts. You can edit, add steps, and export as Markdown.
Guide content
Steps
Do's
One per line; these appear as a best-practice list in the exported guide.
Don'ts
One per line; avoid these common mistakes.
Best-practice callouts in export
In the exported Markdown, Do's are shown as a green callout and Don'ts as a caution callout, so readers can scan quickly.
- Use SameSite=None; Secure for cookies.
- Set linker tag to fire before GA4 Config.
- Don't use DOM Ready if you need first-paint decoration.
- Don't forget referral exclusions in GA4.
Implementation Tools
Snippet library, GTM integration, and testing tools to support your implementation workflow.
Select a snippet
Click a snippet on the left to view its code here. Copy uses the current project's values for placeholders.
Adding your snippets
Save and tag reusable code snippets (GTM, GA4, custom HTML). Filter by use case. Snippets can use placeholders like {{MEASUREMENT_ID}} and {{DOMAINS_ARRAY}} that are replaced with the current project when you copy.
Placeholder reference
Use these in your snippets. They are replaced with the current project’s values when you copy.
| Variable | Replaced with |
|---|---|
{{MEASUREMENT_ID}} | GA4 Measurement ID (e.g. G-XXXXXXXXXX) |
{{API_SECRET}} | Measurement Protocol API Secret |
{{CONTAINER_ID}} | GTM Container ID |
{{DOMAINS_ARRAY}} | Domains as JS array, inline (e.g. ['a.com','b.com']) |
{{DOMAINS_ARRAY_LINES}} | Domains as JS array, one per line |
{{EXTERNAL_DOMAINS_ARRAY}} | External domains as JS array |
{{COOKIE_DOMAIN}} | First primary domain (for cookie scope) |
{{PROJECT_NAME}} | Project name |
{{REPORT_SUITE_ID}} | Adobe Report Suite ID |
{{TRACKING_SERVER}} | Adobe Tracking Server |
{{LAUNCH_PROPERTY_ID}} | Adobe Launch Property ID |
{{ADOBE_CLIENT_CODE}} | Adobe Client Code |
GTM Integration
Import a GTM container export to analyze what's live, compare against your framework, or generate a GTM setup from your project to import back into Tag Manager.
Import from GTM
Export your container in GTM (Admin → Export Container), then upload the JSON file here. We’ll parse it and show a summary.
Container summary
Framework comparison
After importing, we compare your framework events with GTM tags. Pick a project above for framework context.
Import a GTM container and select a project to see the comparison.
Export to GTM
Generate a GTM-ready JSON from your current project: variables (Measurement ID, Domain List), GA4 Config tag, and optional CrossDomainLinker. Import into GTM (Admin → Import Container → Merge).
Testing & Validation
Automated testing tools and manual validation steps for GA4/GTM and Adobe. Ensure cross-domain and tracking work correctly.
Automated Test Suite
Copy the code below, open DevTools (F12) on your site where CrossDomainLinker is deployed, paste into the Console, and press Enter. Tests run for link decoration, form decoration, client ID, cookies, and GA4/GTM presence.
Tip: Save as a DevTools Snippet (Sources → Snippets → New snippet) to run with one click instead of pasting into the Console each time.
Run from Blueprint
Add the listener snippet to your site once, then run tests from here. Results appear below.
Results
Saved results
No saved runs yet. Run tests and click Save.
Manual Testing Steps
Verify Link Decoration
Open browser DevTools → Network tab → Click cross-domain link → Check URL includes _gl parameter
Check Client ID Consistency
Open console on domain 1 → Run: gtag('get', 'G-XXX', 'client_id', console.log) → Repeat on domain 2 → IDs should match
GA4 Real-Time Report
Navigate main → subdomain → Check GA4 Real-time shows 1 user (not 2) and session doesn't break
Source/Medium Attribution
After 24-48 hours, check GA4 reports → Conversions on subdomain should show original source, NOT "subdomain / referral"
Adobe testing
For Adobe Analytics and Launch: use Experience Platform Debugger, Adobe Debugger extension, or Omnibar to validate hits. Check Visitor ID is consistent across domains. Real-time reports in Adobe Analytics (or Data Workbench) show session continuity. See Valued Resources for Adobe debugging links.
FAQ: Common issues & fixes
Expand a question to see the fix. Use the search above to find topics like _gl, client_id, or referral.
_gl parameter not appearing on links
Check that domains are correctly listed in config (exact match, no trailing slashes). Verify the script loads before user interactions (e.g. in <head> or early in GTM). Enable debug: true and check the console for decoration logs.
Client ID still different across domains
Set the cookie domain to the parent domain (e.g. website.com not www.website.com). Ensure SameSite=None; Secure is set and both domains use HTTPS. Confirm the linker parameter is being read on the destination page (acceptIncoming: true).
Sessions still breaking when crossing domains
Add referral exclusions in GA4 Admin (Admin → Data streams → your stream → Configure tag settings → Define internal traffic / List unwanted referrals). List your own domains so GA4 doesn’t treat cross-domain as a new session. Ensure the destination domain accepts the _gl parameter (acceptIncoming: true).
Forms not decorated (no _gl in form submit)
Set decorateForms: true in config. Check that the form’s action URL is cross-domain. Ensure the script runs before form submission (e.g. not loaded async after the form). If forms are added dynamically, enable observeDOM: true.
GTM tag not firing or firing too late
Use the “All Pages” trigger and set the tag’s firing priority higher than your GA4 Config tag so the linker runs first. Avoid “DOM Ready” if you need decoration on first paint. In Tag sequencing, fire the CrossDomain tag before GA4.
Subdomains not linking (e.g. www vs non-www)
Include both in your domain list (website.com and www.website.com) or set includeSubdomains: true if your linker supports it. Set cookieDomain to the root (e.g. website.com) so the same client_id is shared across subdomains.
Attribution still shows “referral” after 24–48 hours
Confirm the linker parameter is present in the URL when users land on the second domain (check Network tab or address bar). Verify GA4 is reading the _gl parameter (gtag config with allow_google_signals and linker). Allow 24–48 hours for reporting; check Real-time first to validate same client_id.
Implementation Checklist
Complete guide to ensure nothing is missed during implementation. Signed-in users can customize the checklist.
Stakeholder Interviews
Plan and run discovery interviews: a question bank by theme, a stakeholder list per project, and ready-to-use templates (pre-meeting one-pager, agenda, summary) with copy and export. Signed-in users can customize the question bank and templates.
Question bank
Curated questions by theme. Use “Why we ask” to explain intent; copy a question or export the full bank.
Check “Include in brief” on questions you want in your interview document. Pick a project to save selections.
Stakeholder list
Per project: role, name, focus, and whether they’ve been interviewed. Pick a project above to edit.
Interview templates
Pre-meeting one-pager, agenda, and summary. Copy or export each block.
Pre-meeting one-pager
Agenda
Summary
Valued Resources
Curated links for implementation consultants: official docs, testing tools, and best-practice references for GA4, GTM, Adobe, and cross-domain tracking.
Bookmark these
GA4 DebugView and the Measurement Protocol reference are must-haves for any implementation.
Account & Profile
Manage your profile information and account settings.
Backup & restore
Export all projects, guides, and frameworks to a JSON file. Restore from a previous backup to replace current data (e.g. on another machine or after a reset).
Invoices & billing
View and download invoices, update payment method, or cancel your subscription in the Stripe customer portal.
Subscription status
Pause your subscription to save money during slow periods. You can resume anytime.
Project credits
You have 0 project credit(s). Credits never expire and can be used anytime.
Delete account
Permanently delete your account and all associated data. This cannot be undone.
User guide
A short guide to get started and do common tasks.
Pricing
Sync across devices, unlock more projects, and get more AI assists. Simple plans, instant access via Stripe. Cancel anytime.
Loading plans…
Admin
Manage users, roles, and plans. To disable a user or send a password reset, use Supabase Dashboard → Authentication → Users.
Users
All users with access to Blueprint. Change role to promote or demote.
| Display name | Role | Stripe Customer ID | Created | Actions |
|---|
To disable a user or send a password reset link, open Supabase Dashboard → Authentication → Users.
Plans & Pricing
Edit plan names, project limits, and prices. Changes apply to new signups and upgrades.
| Plan | Name | Project limit | AI limit | Price | Price label | Stripe Price ID | Actions |
|---|
Project limit: Leave empty for unlimited.
AI limit: Extractions + guide generations per month. Use 0 for unlimited.
Price label: Shown in the UI (e.g. $9/mo). For credits plan, use format like "$5 per project".
Email users
Send transactional email via Brevo. Configure the sender in Settings. Admin only.
Settings
Configure app-wide options. Run supabase/migrations/006_app_settings.sql in Supabase → SQL Editor if the table is missing.
Used by the Contact form. Leave empty to hide the Contact link.
When free users don’t log in, hide the free row in the plans table.
When checked, the Top metrics panel appears in the right sidebar on every admin tab. When unchecked, it only shows on the Analytics insights tab.
From address for admin emails (Brevo). Must be a verified sender in Brevo.
From name shown in admin emails.
Shown at the top of the app for everyone. Leave empty to hide.
Small icon shown before the message.
App-wide look. Nunito Sans, rounded corners, single accent. Only admins see this control.
Stakeholder Interviews
Edit the default question bank and templates. Signed-in users can override with their own.
Question bank — Add, edit, remove
Edit theme names and question text in the fields. Each theme block has Add question and Remove theme; each row has Remove. Use Add theme (above or below) to add a new theme.
Interview templates
Pre-meeting one-pager, agenda, and summary. Markdown is supported.
Guide templates
Add or edit templates shown in Implementation Guides → From template. Built-in templates (GTM, Adobe, etc.) are used until you add your own. Users can also save their own templates.
Steps
Implementation Checklist — Add, edit, remove
Edit the default checklist. Signed-in users can override with their own. Add section (above or below) to add a section; inside each section use Add item and Remove section; each item row has Remove. Edit section titles and item id/label in the fields.
Checklist sections
Each section has a title; each item has an id (e.g. pre1, gtm1 — used for progress) and label (the text users see). Change them in the fields below.
Valued Resources
Edit the resource sections and links shown on the Valued Resources page. All users see the saved content. Each section has icon, title, description; each link has URL, label, and optional meta.
Resource sections — Add, edit, remove
Edit section icon (emoji), title, and description. Each section has links: URL, label, meta. Use Add section and Add link. Load defaults to start from the built-in list.
DataLayer & event tracking
Control app-wide dataLayer pushes for GTM, GA4, or Adobe Launch. When enabled, the app pushes events for buttons, forms, links, section views, and file actions. Use the same prefix in your tag manager to build triggers.
When on, events are pushed to window.dataLayer. Ensure GTM, gtag, or Adobe Launch is loaded to consume them.
Prepended to every event name (e.g. blueprint_button_click). Use only letters, numbers, underscore. Leave empty for no prefix.
For sending hits to GA4. Used by client-side gtag and server-side proxy. Leave empty to use dataLayer only (consume via your own GTM).
Client: loads gtag and sends from browser. Server: forwards via Edge Function (set GA4_API_SECRET in Supabase Edge Function secrets).
Event schema (for GTM)
Every push includes: event, event_category, event_action, event_label. Buttons/links also: element_id, element_type, section. Forms: form_id, form_name. Links: link_url, outbound. Section views: section, tab (for cross-domain tabs). Tab switches: section, tab. Copy actions: copy_type (snippet/guide_step_code/interview_question/code_block/code), snippet_id, code_block_id. Downloads: download_type, file_name. Promo CTA: promo_action, promo_type. Contact: contact_source (nav/footer). GTM Integration: gtm_action (import/export/clear), gtm_tag_count. Overview cards: overview_section.
Full tracking docs – event catalog, measurement framework, GTM implementation guide.
Consent management
Configure consent mode and platform. Supports CookieYes (free), OneTrust, CookieBot, and custom implementations. Modular architecture allows switching platforms without code changes.
When enabled, consent checks will be enforced based on the selected mode and platform.
Track without consent: Analytics runs immediately, no consent required.
Track only with consent: Analytics only runs after user grants consent.
Do not track without consent: Analytics blocked until consent is granted.
Select your consent management platform. The system will automatically detect consent status from the selected platform.
Your CookieYes script ID from the banner code. Example: 1303fd6a1448f9865d59655ca3326fcd. Found in: <script src="https://cdn-cookieyes.com/client_data/YOUR_ID/script.js">
How it works
Modular architecture: The consent manager uses a plug-and-play design. Switch platforms by changing the dropdown—no code changes needed.
Cookie blocking: For free CookieYes (and other platforms without automatic blocking), the system blocks tracking cookies until consent is granted. GA4 consent mode is also updated automatically.
Custom platform: Define window.BLUEPRINT_CUSTOM_CONSENT as a function that returns true when consent is granted.
Analytics insights
Ask natural language questions about your GA4 tracking data. Get CEO-level answers on trends, events, engagement, and more. Requires GA4_PROPERTY_ID and GA4_SERVICE_ACCOUNT_JSON in Edge Function secrets. Setup guide
Suggested questions
Past queries
No past queries yet. Ask a question to add it here.
Get Started Carousel
Manage the steps shown in the Get Started carousel on the overview page. Add, remove, reorder, and edit slides. Each slide has a title, content (supports HTML), and optional tip text.
Promo & Tips
Edit the upgrade ad and contextual tips shown in the right sidebar. JSON format. Use "Load defaults" to seed, edit, then Save. Leave empty to use built-in defaults.
Keys: default (upgrade card), cross-domain, serverside, framework, guides, gtm-integration, testing, checklist, interviews, resources, pricing. Use null to hide a section tip.
Keys: overview, framework, guides. Each has title and items (array of strings, HTML allowed).
User guide content
Edit the customer-facing User guide shown in the User guide section. Use Markdown (headers, lists, links, code). Leave empty to use the default content.