Documentation & Usage Guide

Why GTMalyzer exists

Modern Google Tag Manager containers are complex codebases that accumulate technical debt over years: broken triggers, orphaned variables, unvetted external scripts, and GDPR consent violations. GTMalyzer replaces manual spreadsheet audits and risky releases with instant AI-powered scans, automated living documentation, version diffing, and deployment approvals.

Key platform pillars

Everything in GTMalyzer is structured around six core capabilities:

• •Automated Multi-Domain Auditing: Deterministic configuration checks paired with Gemini AI evaluation across Cleanliness, Performance, Security, and GDPR Privacy.
• •Container Version Diffing: Item-level and line-by-line character comparisons between any two container exports or live versions.
• •AI Living Documentation: Natural-language summaries of every tag, trigger, and variable, with one-click note syncing back into Google Tag Manager.
• •Deployments & Approval Gates: Safe multi-stage deployment workflows with approval requirements for production containers.
• •Container Monitoring & Alerts: Scheduled container health checks delivering immediate notifications via Slack and custom webhooks.
• •Team Workspaces & Access Control: Centralized multi-client management with granular role permissions (Owner, Admin, Member).

Google OAuth Access

When you connect via Google OAuth, GTMalyzer requests read-only and container editing permissions (https://www.googleapis.com/auth/tagmanager.readonly and https://www.googleapis.com/auth/tagmanager.edit.containers). The edit scope allows GTMalyzer to push AI documentation notes directly to your GTM workspace and create staged draft workspaces for deployments. Your OAuth tokens are encrypted at rest using industry-standard AES-256.

JSON Upload Fallback

If your organization restricts third-party OAuth access or you are auditing a client container before gaining Google account permissions, you can export your container directly from Google Tag Manager (Admin → Export Container) and drop the .json file into our uploader. Both workflows run the exact same deterministic rules and AI-powered multi-domain analysis.

Session Management

GTMalyzer sessions are secured with JWT and NextAuth. If your token expires during an active session, the app silently re-authenticates or presents a non-intrusive re-login modal preserving your current form state and unsaved inputs.

Workspace Roles & Permissions

Each workspace maintains strict role-based access control (RBAC):

• •Owner: Primary billing contact. Can delete the workspace, transfer ownership, manage subscriptions, and invite/remove any user.
• •Admin: Can invite members, configure workspace webhooks, manage Slack integrations, and approve container deployment requests.
• •Member: Can run container audits, view comparison diffs, generate living documentation, and submit deployment proposals.

What consumes a credit?

A single credit covers a complete container audit (Cleanliness, Security, Performance, GDPR compliance), an AI living documentation generation, or a deep version comparison diff. Viewing existing reports, re-opening audit history, and downloading PDFs do not consume any credits.

On-demand Credit Top-ups

If you run out of monthly credits during an intensive client onboarding or audit sprint, you can purchase credit top-up packs directly from the Billing page without upgrading your subscription plan.

Key Checks Performed

Our static engine analyzes every element for hygiene anomalies:

• •Orphaned Variables: Identifies User-Defined Variables that are never referenced by any tag, trigger, or child variable.
• •Unlinked Triggers: Flags triggers that have no firing tags assigned to them.
• •Paused Tags: Highlights legacy tags left paused that contribute to container payload bloat.
• •Duplicate Firing Rules: Catches multiple tags listening to the exact same event on the same page with duplicate payloads.
• •Naming Convention Deviations: Flags tags and triggers violating standard naming formats (e.g. '[Vendor] - [Event] - [Destination]').

What we monitor

Performance checks target the main causes of frontend latency:

• •Container Payload Size: Analyzes overall tag, trigger, and variable count for payload bloat.
• •Custom HTML Complexity: Flags inline JavaScript tags containing resource-intensive loops, heavy DOM queries, or blocking code.
• •Micro-Interaction & Runaway Triggers: Evaluates scroll and visibility triggers that fire excessively without debouncing.
• •Duplicate Firing Tags: Highlights tags executing concurrently on the same trigger event.

Security scan criteria

The security analysis inspects Custom HTML and variables for high-risk patterns:

• •Unverified External Endpoints: Flags network requests to unknown third-party endpoints or unauthorized CDNs.
• •High-Risk DOM Manipulations: Scans Custom HTML tags for unsafe element insertions, outerHTML rewrites, and innerHTML injections vulnerable to Cross-Site Scripting (XSS).
• •Secret & API Key Leakage: Searches variable values and tag parameters for exposed private tokens, authorization bearer headers, or unhashed passwords.
• •Form Field Harvesting: Identifies scripts attempting to read inputs with sensitive password or payment card patterns.

Consent evaluation rules

Our AI engine inspects the sequence and configuration of consent logic:

• •Consent Mode v2 Signals: Verifies default states for ad_storage, analytics_storage, ad_user_data, and ad_personalization.
• •Premature Tag Firing: Flags marketing and tracking tags that fire on generic 'All Pages' or 'DOM Ready' before user consent has been explicitly granted.
• •Manual CMP Bypass: Scans custom scripts for code that modifies cookies (like CookieConsent or OptanonAlertBoxClosed) to trick the consent management platform.
• •Automated Opt-In Violations: Flags default configuration parameters that set opt-in flags to 'granted' without an active user gesture.

Health Score Calculation

The overall Container Health Score (0-100) is deterministically calculated from configuration checks: each failed check deducts 18 points, and each warning deducts 7 points. Informational checks and AI findings do not lower the score, providing clear and predictable benchmarking. Containers with scores above 85 are considered healthy.

Actionable Remediation Plans

Every check and AI issue includes an actionable remediation recommendation and associated configuration evidence. Teams can also manage remediation progress directly on the report by setting issue statuses to Open, In Progress, or Resolved.

Shareable Tokenized Links

Generate a unique read-only link for any audit. Anyone with the link can explore the full interactive audit findings and health scores without requiring a GTMalyzer login or account.

Print & PDF Optimization

Click the 'Download PDF' or 'Print' button on any audit report. GTMalyzer applies a clean, print-optimized stylesheet with page breaks, high-contrast charts, and formatted issue tables ideal for client presentations.

What is tracked

Structural comparisons identify:

• •Added Elements: Newly created tags, triggers, or variables highlighted in green.
• •Modified Elements: Existing elements whose parameters, firing conditions, or consent settings changed, highlighted in amber.
• •Removed Elements: Deleted tags, triggers, or variables highlighted in red.
• •Firing Trigger Alterations: Shows exactly which triggers were attached or detached from existing tags.

Detailed Code Analysis

Whenever a Custom HTML tag or Custom JavaScript variable is modified between versions, GTMalyzer runs a character-level unified diff. Green rows denote inserted lines, red rows denote deleted code, and changed variables within lines are highlighted for rapid code review.

Automated Plain-English Summaries

Rather than decoding cryptic regex variables or nested trigger conditions manually, GTMalyzer translates each component into clear documentation explaining: what the tag does, when it fires, what data it collects, and where it sends the payload.

Target Audience

Perfect for onboarding new analytics engineers, preparing compliance records for legal teams, or handing off client projects with complete documentation.

One-Click GTM Workspace Synchronization

Rather than keeping documentation trapped in an external tool, GTMalyzer connects directly to the Google Tag Manager API. You can push AI summaries straight into the native 'Notes' field of any tag, trigger, or variable in your chosen GTM workspace.

Preserve Container Knowledge

When team members or external consultants open your container inside Google Tag Manager, they see exact explanations of what each tag does and why it was created, eliminating guesswork and preventing accidental deletions.

Staged Deployment Process

All deployment operations create a draft workspace in the target GTM container. Nothing is published directly to live production without explicit user review in the GTM interface, preventing accidental tracking outages.

Standardizing Tracking Standards

Create custom templates for ecommerce events (GA4 Purchase, Add to Cart, View Item), server-side tagging setups, or privacy consent banners and push them to any client container with one click.

How Approvals Work

When an analytics specialist creates a deployment request, team Admins or Owners receive an alert. They can inspect the associated container diff, verify health score impact, and approve or reject the release with feedback notes.

Connecting Slack

Create an Incoming Webhook in your Slack Workspace (api.slack.com/apps), paste the webhook URL into your GTMalyzer workspace settings, and send a test notification to verify delivery.

Custom HTTPS Webhooks

Stream structured JSON payloads for monitor runs, audit completions, and deployment approvals to endpoints like Zapier, Make, n8n, or internal incident response pipelines.

Does GTMalyzer store my website visitors' tracking data?

No. GTMalyzer exclusively analyzes container configuration architecture (JSON schemas consisting of tags, triggers, and variables). We never place tracking scripts on your website and never collect or store your website visitors' personal data or browsing hits.

Do I need Google OAuth verification to audit my container?

No. While Google OAuth offers convenient direct access to live GTM accounts, you can always export your container as a .json file directly from Google Tag Manager and upload it instantly to GTMalyzer with zero Google authorization steps.

Can I share audit reports with clients without giving them an account?

Yes. Every audit report includes a 'Share' button that generates a secure tokenized public URL. Anyone with this link can view the complete interactive audit, health score, and remediation steps without logging in.

What happens when my monthly credits run out?

Existing audit reports, diff comparisons, and living docs remain accessible forever. To run new audits or documentation generations, you can purchase one-off top-up credit packs or upgrade your monthly subscription.

How do I report an issue or request a feature?

Our engineering team responds to all inquiries within one business day. Reach out via the Contact page or email us directly at [email protected].