Campaign Detector

v1.0.0 · Detects and normalizes campaign parameters from 60+ advertising platforms. Resolves unexpanded macros, identifies traffic sources via click IDs, UTM parameters, referrer domains, and user-agent patterns for mobile apps.

Public API — `window.TrafficCampaign`

// Initialize
const tc = new window.TrafficCampaign();

// Get full digital data
const data = tc.getDigitalData();
// Returns: { campaign, traffic, device, context, raw }

// Send to GA4 via Measurement Protocol
tc.sendToGA({
  measurement_id: "G-XXXXXXX",
  api_secret: "your-secret"
});

Supported Platforms

The detector uses a 4-level priority system to identify the traffic source:

Priority 1 — Click IDs (highest confidence)

Parameter	Platform
`gclid` / `gbraid` / `wbraid`	Google Ads
`fbclid`	Facebook Ads (or Instagram if `utm_source` matches)
`msclkid`	Microsoft Ads
`ttclid`	TikTok Ads
`li_fat_id`	LinkedIn Ads
`pclid`	Pinterest Ads
`rdt_cid`	Reddit Ads
`ScCid`	Snapchat Ads

Priority 2 — UTM Source + Macro Coherence

Matches utm_source to platform aliases and validates with detected macros and their format (double-brace for Facebook/LinkedIn, single-brace for Google, double-underscore for TikTok).

Priority 3 — Unique Macros

Identifies platforms by unique macro names that only belong to one platform (e.g., __AID__ = TikTok, ACCOUNT_ID = LinkedIn).

Priority 4 — Pattern Matching

Falls back to regex pattern matching against platform-specific patterns in parameter values.

Macro Format Detection

Format	Pattern	Platforms
Double-brace	`{{campaign.id}}`	Facebook, Instagram, LinkedIn, Snapchat, Reddit
Single-brace	`{campaignid}`	Google, Microsoft, Pinterest, Amazon
Double-underscore	`__CAMPAIGN_ID__`	TikTok

Traffic Classification

Beyond campaign detection, the engine classifies all traffic into channels:

Channel	Detection Method	Examples
Paid Search	Click IDs from search engines	Google Ads, Bing Ads, Yahoo, Baidu, Yandex
Paid Social	Platform click IDs	Facebook, TikTok, Twitter, LinkedIn, Snapchat, Pinterest, Reddit
Display / Native	Platform-specific params	Criteo, Taboola, Outbrain, DoubleClick, AdRoll, TheTradeDesk
Email	ESP tracking params	HubSpot, Mailchimp, Klaviyo, Marketo, MailerLite
Affiliate	Network params	CJ, Impact, Awin, ShareASale, ClickBank, Partnerize, Rakuten
Organic Search	Search engine referrer domains	Google, Bing, DuckDuckGo, Brave, Ecosia, Kagi (14 engines)
Social Organic	Social platform referrer domains	Facebook, Instagram, Twitter/X, LinkedIn, TikTok, Reddit, Threads, Bluesky (16 platforms)
AI Referral	AI platform referrer domains	ChatGPT, Claude, Gemini, Perplexity, Copilot, Phind, Poe (13 platforms)
Video	Video platform referrers	YouTube, Vimeo, Twitch, Dailymotion
Shopping	E-commerce referrers	Amazon, eBay, Etsy, Shopify
App Store	Store referrers	Google Play, Apple App Store, Microsoft Store

Mobile App Detection

Identifies traffic from 30+ native mobile apps by parsing the User-Agent string for known package names (Android) and UA identifiers (iOS):

Android: com.facebook.katana, com.instagram.android, com.twitter.android,
         com.linkedin.android, com.zhiliaoapp.musically (TikTok),
         com.openai.chatgpt, com.anthropic.claude, ai.perplexity.app

iOS:     FBAV (Facebook), Instagram, Twitter, [LinkedInApp],
         Snapchat, TikTok, ChatGPT, Claude, Perplexity

Digital Data Schema

tc.getDigitalData() returns:
{
  campaign: {
    source: "google",
    medium: "cpc",
    name: "summer-sale",
    content: "banner-v2",
    term: "shoes",
    // Platform-specific
    adPlatform: "Google Ads",
    clickId: "gclid-abc123",
    macroInfo: { hasMacros: false, ... }
  },
  traffic: {
    channel: "Paid Search",
    referrer: "https://google.com/search?q=...",
    isInternal: false,
    landingPage: "/products/shoes"
  },
  device: {
    type: "desktop" | "mobile" | "tablet",
    os: "macOS",
    browser: "Chrome",
    isMobileApp: false,
    appName: null
  },
  context: {
    timestamp: "2024-03-10T12:00:00Z",
    timezone: "Europe/Madrid",
    language: "es-ES",
    viewport: "1920x1080"
  },
  raw: {
    // All original URL parameters
  }
}

GA4 Measurement Protocol

// Send digital data directly to GA4
tc.sendToGA({
  measurement_id: "G-XXXXXXX",
  api_secret: "your-mp-api-secret"
});

// This sends a 'campaign_detected' event with all
// campaign parameters as event params, enabling
// attribution stitching between Impressio and GA4.