meseo-staging/docs/phase-30-site-tag-detection-expansion.md

Phase 30: Site Tag Detection Registry Expansion

Status: Session 2 complete (commit in progress) Effort: 6 hours across 3 sessions (3h + 2h + 1h) Risk: Medium. Touches Site Tag JavaScript running on every client site.

Full spec content lives in Claude conversation dated May 22-25, 2026. This file is a structured summary derived from that conversation.

---

Problem Statement

The meSEO Site Tag detected approximately 20 plugins across two categories (booking widgets and chat widgets). A modern WordPress or CMS site typically has 15-30 trackable integrations. Coverage was roughly 25% of what is actually present on a typical brand site.

Confirmed via production data on May 22, 2026:

• modernheartandvascular.com (cardiology): 4 plugins detected out of ~15-25 present
• lifeimagingfla.com (imaging): 1 plugin detected out of ~8-15 present

After Phase 30 Session 1: cardiology brand shows 11 detected plugins.

---

Goal

1. Site Tag detects 50-80 known plugins, widgets, pixels, and integrations
2. Each detection fires a plugin_detected event with consistent metadata including category, tag_v, and confidence
3. Integrations tab on Site Tag Analytics shows comprehensive per-brand inventories
4. Adding new detection patterns is a small registry edit

---

Architecture

Detection happens entirely in public/t.js (served from Next.js static directory). The unminified source lives at public/t.source.js (gitignored).

Edit workflow:

cp public/t.source.js public/t.js   # copy source to served file
# edit public/t.js
npm run build:site-tag               # minifies in place, backs up to t.source.js

Three registries in public/t.source.js:

Registry	Location	Category	Count	Event shape
BOOKING_PLUGINS	~line 5832	booking, forms, crm	15 entries	{plugin, plugin_key, category, tag_v, confidence}
CHAT_WIDGETS	~line 6416	chat	15 entries	{plugin, plugin_key: "chat_"+key, category: "chat", tag_v, confidence}
ANALYTICS_PLUGINS	~line 6659	analytics, pixel, seo, page_builder, ecommerce, crm, reviews, cache, security, booking, lead_gen	~47 entries after Session 2	{plugin, plugin_key, category, tag_v, confidence}

Event metadata shape (all registries after Phase 30 Session 1 fix):

sendEvent('plugin_detected', {
  plugin: 'Google Analytics 4',   // display name
  plugin_key: 'ga4',              // machine key
  category: 'analytics',          // category string
  tag_v: '2026.05.31',            // Site Tag version (bump on each deploy)
  confidence: 'high' | 'medium',  // detection confidence
});

---

Existing Registries (do NOT modify these in Phase 30)

BOOKING_PLUGINS keys

amelia, calendly, nexhealth, acuity, jotform, typeform, wpforms, gravityforms, contactform7, hubspot, deardoc, birdeye, podium, weave

CHAT_WIDGETS keys

intercom, drift, tidio, tawkto, livechat, crisp, olark, hubspot_chat, zendesk, fb_messenger, smartsupp, jivochat, purechat, userlike, frontchat

---

ANALYTICS_PLUGINS Entries

Session 1 (20 entries, commit cdb096f)

Analytics and pixels (12): ga4, gtm, ua_legacy, fb_pixel, linkedin_insight, tiktok_pixel, twitter_pixel, pinterest_tag, reddit_pixel, clarity, hotjar, amplitude

SEO (3): wordpress, yoast, rankmath

Page builders (1): elementor

E-commerce (1): woocommerce

CRM (3): hubspot_track, klaviyo, mailchimp

Session 2 (~27 additional entries)

Forms (2): formidable, fluent_forms

Page builders (4): divi, beaver_builder, brizy, bricks

Booking (4): bookly, bookingpress, simplybook, setmore

Reviews (3): trustpilot, google_reviews_widget, nicejob

Cache (2): wp_rocket, litespeed_cache

Security (2): wordfence, sucuri

Healthcare-specific (2): patientpop, doctible

SEO (2): aioseo, seopress

E-commerce (2): shopify, edd

CRM (2): activecampaign, convertkit

Skipped (already covered):

• mailchimp: already in ANALYTICS_PLUGINS
• olark: already in CHAT_WIDGETS (fires as "chat_olark")
• zendesk_chat: already in CHAT_WIDGETS (fires as "chat_zendesk")
• hs_conversations: already in CHAT_WIDGETS (fires as "chat_hubspot_chat")

---

Detection Strategies

Window global

detect: () => typeof window.fbq === 'function'

Script src match (uses cached getScriptSrcs())

detect: () => /googletagmanager\.com\/gtm\.js/.test(getScriptSrcs())

DOM selector

detect: () => !!document.querySelector('.gform_wrapper')

Meta tag

detect: () => {
  const meta = document.querySelector('meta[name="generator"]');
  return !!(meta && /Yoast SEO/.test(meta.getAttribute('content') || ''));
}

Cookie name (uses cached getCookies())

detect: () => /_fbp=/.test(getCookies())

Composite (high confidence)

detect: () => {
  const hasGlobal = typeof window.fbq === 'function';
  const hasCookie = /_fbp=/.test(getCookies());
  if (hasGlobal && hasCookie) return { matched: true, confidence: 'high' };
  if (hasGlobal || hasCookie) return { matched: true, confidence: 'medium' };
  return false;
}

---

Performance Constraints

• Detection total work: target under 5ms on mid-range mobile
• requestIdleCallback for post-DOMContentLoaded run (5000ms fallback)
• Skip detection if document.hidden is true
• getScriptSrcs() iterates document.scripts once per detection pass (cached)
• getCookies() reads document.cookie once per detection pass (cached)
• window.__meseoDetectedKeys Set prevents any plugin_key firing more than once per page load
• Detection runs at most twice: DOMContentLoaded + requestIdleCallback(timeout: 5000)

---

Backend: ENRICHMENT_REGISTRY

Location: src/lib/site-tag/integration-signatures.ts

Provides vendor info, descriptions, and category defaults for backfill. Keyed by plugin_key. Consulted by:

1. backfill-detected-integrations route when resolving category/vendor
2. site-tag-analytics/integrations GET route when merging description into response

---

Phase Sessions

Session	Status	Commit	Description
Session 1	Complete	cdb096f	20 ANALYTICS_PLUGINS rules, BOOKING_PLUGINS category fix, tag_v + confidence fields
Session 2	Complete	(current)	~27 additional rules, backend enrichment, docs
Session 3	Pending	-	UI polish, category icons, vendor logos

---

Acceptance Criteria

• Site Tag detects at least 8 distinct plugins on modernheartandvascular.com (was 4)
• Site Tag detects at least 5 distinct plugins on an active lawn care brand site
• No false positives on a clean test site
• All plugin_detected events include category, tag_v, and confidence
• Detection adds less than 10ms to page load p95
• Integrations tab shows expanded set per brand within 24 hours of deploy

---

Dependencies

• Phase 28A Session 1.5 (backend backfill fix): SHIPPED at commit 058272e
• Phase 28A Session 1.6 (SQL aggregation backfill): SHIPPED at commit 30363ed
• Phase 28A Session 2 (real-time write hook to /api/site-tag/event): PENDING