Documentation

Install once. Watch every tag fire.

A developer-first reference for installing TagDrishti, shaping the config, wiring BigQuery, and meeting GDPR, DPDP, and PCI DSS without detours.

Start free trialjump to quickstart ↓
# head-tag install · not gtm · tls 1.3 · bigquery direct

Quickstart

Live in under five minutes. Three steps, no infrastructure to provision, no SDK to vendor into your app.

  1. Create your account at the sign-in page. The DPA is executed on signup and your first API key is waiting in Settings.
  2. Paste the snippet directly in your site’s HTML <head>, before </head>. Not through GTM. The monitor has to load independently of your tag manager, otherwise a broken GTM container also breaks the thing watching it.
  3. Deploy your site. First tag fires land in the dashboard inside 30 seconds.

Script installation.

Paste the snippet below directly in your site’s HTML <head>, ideally right before </head>. Swap the tenant ID and API key with the values from Dashboard → Settings → API & Script.

!
Install in your site’s backend, not in GTM. Loading the monitor through GTM means a broken GTM container also breaks the monitor watching it. A direct <head> install is a few lines of template work for your dev, and it keeps TagDrishti alive even when your tag manager is down.
<!-- TagDrishti Monitor. Paste in your site's HTML <head> -->
<script>
window.GTM_MONITOR_CONFIG = {
  tenantId:    "td-your-tenant-id",
  apiKey:      "td_live_xxxxxxxxxxxx",
  apiEndpoint: "YOUR_API_URL"
};
</script>
<script src="YOUR_API_URL/tagdrishti.js?workspace=YOUR_WORKSPACE_ID" async></script>

Deploy the site. The tag loads async, sits outside your critical render path, and starts beaconing within 30 seconds of the first pageview.

✓
No cookies. No consent banner. The tracker operates on pseudonymised session hashes under Legitimate Interest, so it sits outside your CMP. You do not need to gate it for GDPR-compliant monitoring.
!
Running a strict CSP? Whitelist the TagDrishti API origin in script-src, connect-src, and img-src. Skip this and the browser drops every beacon silently, nothing reaches the dashboard. Example directives:
script-src https://your-tagdrishti-api.example.com;
connect-src https://your-tagdrishti-api.example.com;
img-src https://your-tagdrishti-api.example.com;
Swap the hostname for the API endpoint in your snippet.

Your first event.

Deploy the site, then load any page on it. Data should appear within 30 seconds. Here is how to confirm it end to end:

  1. Load your site in Chrome with an incognito window.
  2. Open DevTools, switch to the Network tab, and filter for gtm-event.
  3. Look for a POST to /api/gtm-event returning status 200. That is the beacon reaching us.
  4. In Dashboard → Overview, your domain should surface under Domain Health within one refresh.

Script config options.

Every option is driven from window.GTM_MONITOR_CONFIG, set before the script tag loads.

window.GTM_MONITOR_CONFIG = {
  tenantId:      "td-your-id",         // Required
  workspaceId:   "ws-your-ws-id",      // Optional. Defaults to 'default'
  apiKey:        "td_live_xxxxx",      // Required
  apiEndpoint:   "YOUR_API_URL", // Required. From Settings page
  sampleRate:    1.0,                 // 0.0-1.0. % of events to collect (default: 1.0)
  childrenMode:  false,               // DPDP 2023 children protection (default: false)
  environment:   "production"         // 'production' | 'staging' | 'development'
};

Workspaces & domains.

One workspace, one monitored domain. Every workspace ships with its own API key and its own BigQuery dataset, so agency and multi-brand setups stay cleanly partitioned. Domain A cannot query Domain B, full stop.

To add one: Dashboard → Domains → Add Domain. Drop in the hostname and GTM container ID and you get back a workspace-scoped install snippet.

API keys.

Keys follow the td_live_xxxxxxxxxxxx format. A few things worth knowing:

  • Each key is scoped to exactly one workspace. Blast radius stays small.
  • We hash keys with bcrypt at rest. A lost key cannot be recovered, only rotated.
  • Rotate any time from Dashboard → Settings → API & Script. No downtime on the in-flight key.
!
Do not commit keys to Git. If one leaks (PR diff, public gist, shared screenshot), rotate it from Settings inside the hour and invalidate the old one.

Overview tab.

A rolling 24-hour snapshot across every domain: total fires, failure rate, average latency, any open alerts, and a dual-line chart plotting fires against failures in real time.

Domain Health rolls up to a success-rate sparkline per site. Click a row to drop straight into Tag Health, already filtered.

Tag health.

A row per tag, across every domain you monitor, for the time window you pick. Columns read left to right:

  • Tag Name: exactly as it is named in your GTM container.
  • Type: the underlying tag type (html, ua, ga4, adwords, and so on).
  • Status: success, warning, or failure. This is what triggers alerts.
  • Fires: total fire count inside the window.
  • Fail Rate: percentage of fires that ended in a failure.
  • Avg ms: P75 execution time, not the mean. P75 tracks real-world experience.
  • Severity: critical, high, medium, or low, auto-derived from the tag type (a GA4 tag breaking is not a pixel tag breaking).

Flip the status filter to failures only for a focused triage view. CSV export is one click away for client-ready audits.

Security & Magecart detection.

The Security tab watches for script-level tampering on every page we monitor. Four signals fire here:

  • Unknown domain: a script loaded from an origin you never approved. This is the classic Magecart fingerprint.
  • SRI missing: a third-party script loaded without a Subresource Integrity hash. Required under PCI DSS 6.4.3.
  • CSP violation: a script the browser blocked against your Content-Security-Policy.
  • Flood guard: an unusual spike in event volume from a single origin, your signal for injection or a runaway library.

Running PCI scope? Add every legitimate script origin to the allowlist at Dashboard → Settings → Data & Privacy → Approved Script Domains. Anything outside that list triggers a critical alert the moment it loads.

The Consent tab surfaces what Google Consent Mode v2 is actually doing in production, not what your CMP thinks it is doing:

  • Grant rates for analytics_storage, ad_storage, functionality_storage, and personalization_storage.
  • GPC (Global Privacy Control) signal rate, broken out so you can see the shift in opt-outs over time.
  • Tags blocked by consent, so you can explain the gap between GA4 fires and Meta fires.
  • EU session percentage, geo-detected at the edge.

Core Web Vitals.

P75 measurements for LCP, CLS, INP, FCP, and TTFB, bucketed per domain and attributed per tag. Thresholds track Google’s Good / Needs Improvement / Poor bands exactly. The 7-day LCP trend chart makes regressions obvious the moment a vendor ships a heavier script.

Alerts

Alerts fire the moment an anomaly crosses the threshold you set at Dashboard → Settings → Notifications. The three most common:

  • Tag failure rate threshold: alerts when a tag’s fail rate crosses X percent. Default is 10 percent, which is aggressive enough to catch real breakage without paging on flake.
  • Security event: fires instantly on any unknown domain, missing SRI, or CSP violation. Treat every one as page-worthy.
  • Web Vitals degradation: fires when LCP or INP slides from Good into Needs Improvement.

Email delivery is on every plan. Slack webhooks land in under two seconds on Agency and Enterprise.

Statistical anomaly detection

On Agency and Enterprise, every active workspace also runs an automatic statistical-anomaly check every five minutes. The current hour’s metric (fail rate, tag count, latency, lost revenue) is compared against a 14-day rolling baseline using a z-score; the warning threshold is z > 2.5, critical at z > 3.5. EWMA smooths the running mean so a single noisy hour doesn’t fire, CUSUM catches sustained drift the z-score would absorb, and seasonal decomposition handles weekly traffic cycles. The whole loop runs every 5 minutes per active workspace, so an anomaly that starts at 14:30 surfaces by 14:35 at the latest.

You can’t turn statistical anomalies off, but you can dial sensitivity: Dashboard → Settings → Notifications → Anomaly sensitivity. Default is balanced (z 2.5 / 3.5); strict drops to z 2.0 / 3.0 (more alerts, more false positives); relaxed goes to z 3.0 / 4.0 (fewer alerts, more chance of missing a real drift).

Read-only GTM access.

If you are an agency auditing a client container, the clean pattern is simple. The client grants your Google account read-only access. You never edit anything. They retain full control. TagDrishti pulls tags, triggers, variables, and consent config through the Google Tag Manager API under those credentials.

i
Read is the correct default for an audit. “View & edit” grants publish rights you do not need for a Tag Health Audit. The Read role is enough to enumerate tags, triggers, and variables without the blast radius of edit.

For agency: what to send your client

Forward the five-step block below to your client contact, typically the marketing lead or whoever owns GTM on their side. Drop in the Google account email you want granted.

  1. Sign in to tagmanager.google.com with an account that owns the container.
  2. Open the container in question. Click Admin in the top nav, then User Management in the Container column. Not the Account column, that is a different scope.
  3. Hit the + button (top right) and choose Add users. Enter the agency’s Google account email.
  4. Under Container Permissions, tick only Read. Leave Edit, Approve, and Publish unchecked.
  5. Click Invitation. The agency gets an email, accepts, and access is live in seconds.
✓
You can revoke access any time from the same Admin → User Management screen. No long-lived secrets sit on our side. Access is bound to the agency’s Google identity, not an API key we hold.

For client: what “Read” lets the agency do (and not do)

  • Can do: list every tag, trigger, and variable; view tag configurations; view version history in read-only mode; export the container JSON for offline analysis.
  • Cannot do: create or edit tags, delete anything, spin up workspaces, publish the container, change consent settings, or modify user permissions.

Scope the access to one container, not the whole account

Grant at the Container level, never the Account level. Container-level access boxes the agency into exactly the site being audited. Account-level access hands them visibility into every container on the account, rarely the intent.

!
Do not grant “View & edit” for an audit. An audit needs visibility, nothing more. If an agency pushes for Edit rights, treat it as a separate, time-bounded request with its own change ticket. Do not bundle it into the audit scope.

Revoking access after the audit

Once the audit PDF is delivered, pull the access:

  1. GTM → Admin → User Management in the Container column.
  2. Find the agency row, open the three-dot menu, click Remove.
  3. Optional but tidy: ask the agency to confirm any exported container JSON has been deleted.

Alternative: read-only via service account (advanced)

If you audit many containers and do not want to bind access to a human Google identity, TagDrishti can authenticate against the GTM API with a Google service account. The client grants the service account email the Read role on the container instead. Useful for scheduled re-audits where you do not want a human-in-the-loop on every accept. Email [email protected] and we will set it up.

BigQuery access.

Every event is streamed into your workspace’s BigQuery dataset in real time, 135 columns per row, row-level isolated per tenant. Regions are EU, US, or APAC, pick at signup. You get direct SQL, no exports to download.

  1. Open Dashboard → BigQuery. Copy the dataset ID and the authorized-view connection details.
  2. Plug into Looker Studio, Tableau, Power BI, or anything BigQuery-compatible using the service-account JSON we provision.
  3. Query the pre-built views: tag_events, security_events, consent_snapshots, web_vitals_rollups, and anomaly_alerts. These cover 90 percent of real work.
  4. Dashboard → BigQuery → Sample Queries ships a library of common reports (tag health, consent compliance, CWV drift, usage-vs-billing).
GET/api/bq/statusCheck BigQuery connection
Returns connection state, rows written in the last 24 hours, and usage against your plan cap.

Slack alerts.

End-to-end in under a minute:

  1. In Slack: your workspace → Apps → Incoming Webhooks → Add New Webhook.
  2. Pick the channel, copy the webhook URL.
  3. Paste it into Dashboard → Settings → Notifications.
  4. Hit Test Slack. A test message should hit your channel within a couple of seconds. If it does not, the webhook URL is wrong or the channel is archived.

API reference.

Every endpoint expects Authorization: Bearer {clerk_jwt}. Base URL is YOUR_API_URL.

GET/api/meGet current tenant
Returns tenant profile and the list of workspaces you can see.
GET/api/dashboard/overviewDashboard overview data
Query params: range (1h/24h/7d/30d), workspace_id.
GET/api/tagsTag health table
Query params: range, workspace_id, status (success/warning/failure).
GET/api/securitySecurity events
Query params: range, type (unknown_domain/sri_missing/csp_violation).
GET/api/vitalsCore Web Vitals P75
Query params: range, workspace_id, device (mobile/desktop/tablet).
POST/api/alert-configSave alert configuration
Body: { workspace_id, alert_email, slack_webhook_url, enabled, threshold }.

Full response shapes, pagination, and BigQuery query patterns live in the API Connection Guide.

GDPR setup.

GDPR-compliant out of the box for EU traffic. EU visitors are detected at the edge through Cloudflare geo-IP and session pseudonymisation is applied automatically. There is nothing to wire up.

For DSAR handling, go to Dashboard → Settings → Data & Privacy → Export Data. Paste the pseudonymous session hash and we generate a GDPR-ready export in seconds.

DPDP 2023 (India).

What you need to know if your users fall under India’s Digital Personal Data Protection Act 2023:

  • IN-geolocated sessions are pseudonymised automatically. No config flag required.
  • For DPDP Section 9 (children), set childrenMode: true in your script config. That single flag blocks every non-essential tag we monitor for the session.
  • Indian-user consent is reported separately in the Consent dashboard, so you can prove compliance without disentangling it from EU data.

PCI DSS setup.

If you need TagDrishti to carry the weight for PCI DSS 6.4.3 and 11.6.1, here is the playbook:

  1. Install the tracker on every page in PCI scope. Checkout, payment forms, and order-confirmation pages at minimum.
  2. Populate the allowlist at Dashboard → Settings → Data & Privacy → Approved Script Domains with every legitimate script origin on those pages.
  3. Anything outside the allowlist trips a critical security alert the instant it loads. This is your early warning for skimmer injection.
  4. Review the Security tab weekly. PCI DSS 11.6.1 expects regular monitoring of payment-page script inventory, not a point-in-time audit.
  5. Export security event logs monthly so your QSA has a clean audit trail.
install in 5 min · first alert today · 14-day trial

Read enough? Wire it up.

One async script tag in your <head>, first beacon in 30 seconds. 14-day free trial, no credit card.

Start free trialBrowse resources
14 days, no credit cardinstall in 5 minuteshuman reply within a day