AttributionRules.md

EasyAttrib Attribution Rules

Overview

EasyAttrib is a JavaScript attribution tracking system that determines the source and medium of website traffic. It processes various attribution signals in a specific order to provide accurate traffic source attribution.

Attribution Evaluation Order

The system evaluates attribution signals in the following order:

1. Campaign Parameters (Always Processed First)

Campaign parameters are processed first and are independent of other attribution logic:

Supported Campaign Parameters:

• utm_campaign (Google Analytics)
• mtm_campaign (Matomo)
• matomo_campaign (Matomo alternative)
• pk_campaign (Piwik)
• piwik_campaign (Piwik alternative)
• cid (Adobe Analytics)

Priority: First parameter found wins (left-to-right order)

2. Attribution Plugins (In Plugin Order)

Plugins are evaluated in the order they are provided to the SessionTracker constructor. The default order is:

1. UTM Attribution Plugin
2. Google Ads Attribution Plugin
3. Facebook Attribution Plugin
4. Referrer Attribution Plugin

Attribution Priority Rules

UTM Parameters Priority

• UTM parameters have the highest priority over click ID plugins
• When both UTM parameters and click IDs are present, UTM source/medium takes precedence
• Click IDs are still preserved for tracking purposes even when UTM overrides

Click ID Plugin Priority

• Click ID plugins (Google Ads, Facebook) can only override existing attribution if:
  • No UTM source attribution is present
  • The existing source is not from the same click ID plugin
  • Attribution preservation is disabled

Session Attribution Preservation

• By default, existing session attribution is preserved
• New attribution only overrides existing attribution when:
  • No existing attribution exists
  • Attribution preservation is disabled (shouldPreserveAttribution: false)
  • UTM parameters are being set for the first time
  • Click ID plugins meet the override criteria

Plugin-Specific Rules

UTM Attribution Plugin

Supported Parameters:

• Source parameters: utm_source, mtm_source, matomo_source, pk_source, piwik_source
• Medium parameters: utm_medium, mtm_medium, matomo_medium, pk_medium, piwik_medium

Behavior:

• Returns attribution only if at least one parameter is found
• First parameter found in each category wins
• Can override click ID attribution when both are present

Google Ads Attribution Plugin

Supported Parameters:

• gclid (Google Ads click ID)

Default Attribution:

• Source: google_ads
• Medium: cpc
• Click ID: Value of gclid parameter

Behavior:

• Only activates when gclid parameter is present
• Cannot override UTM source attribution
• Can override other attribution sources when no UTM is present

Facebook Attribution Plugin

Supported Parameters:

• fbclid (Facebook click ID)

Default Attribution:

• Source: meta
• Medium: social
• Click ID: Value of fbclid parameter

Behavior:

• Only activates when fbclid parameter is present
• Cannot override UTM source attribution
• Can override other attribution sources when no UTM is present

Referrer Attribution Plugin

Behavior:

• Only activates when a valid referrer is present
• Ignores same-domain referrers (internal traffic)
• Maps known domains to specific source/medium combinations
• Unknown domains are classified as referral traffic

Referrer Domain Mappings

Search Engines (organic_search)

Domain	Source	Medium
google.	google	organic_search
bing.	bing	organic_search
duckduckgo.com	duckduckgo	organic_search
ycombinator.com	ycombinator	organic_search
yahoo.com	yahoo	organic_search
ecosia.org	ecosia	organic_search
startpage.com	startpage	organic_search
yandex.com	yandex	organic_search
brave.com	brave	organic_search
baidu.com	baidu	organic_search
sogou.com	sogou	organic_search
eniro.se	eniro	organic_search
presearch.org	presearch	organic_search

Social Media (social)

Domain	Source	Medium
facebook.com	facebook	social
twitter.com	twitter	social
linkedin.com	linkedin	social
instagram.com	instagram	social
pinterest.com	pinterest	social
reddit.com	reddit	social
quora.com	quora	social
tiktok.com	tiktok	social
youtube.com	youtube	social
medium.com	medium	social
github.com	github	social
stackoverflow.com	stackoverflow	social
dev.to	dev.to	social
x.com	x	social

AI/Chat Bots (ai-service)

Domain	Source	Medium
chatgpt.com	chatgpt	ai-service
openai.com	openai	ai-service
claude.ai	anthropic	ai-service
anthropic.com	anthropic	ai-service
perplexity.ai	perplexity	ai-service

Unknown Domains

• Source: Domain name (e.g., example.com)
• Medium: referral

Fallback Attribution

Direct Traffic

When no attribution is found by any plugin:

• Source: direct
• Medium: direct
• Channel: direct/direct

Channel Assignment

The system automatically assigns a channel based on source and medium:

• Format: {source}/{medium}
• Examples:
  • google/organic_search
  • facebook/social
  • google_ads/cpc
  • meta/social
  • direct/direct

Session Management

Session Creation

• New sessions are created when no existing session is found
• Sessions include landing page URL, referrer, timestamp, and attribution data
• Multi-tab support with automatic session cleanup when all tabs close

Session Persistence

• Sessions are stored in localStorage by default
• Attribution data is preserved across page views within the same session
• Sessions persist until all browser tabs are closed

Debug Mode

Debug Cookie

• Set cookie x-attrib-test=enabled to enable debug logging
• Debug mode shows detailed attribution processing steps
• Can be overridden by constructor debug option

Debug Output

When debug mode is enabled, the system logs:

• Plugin evaluation steps
• Attribution decisions
• Session state changes
• Override logic decisions

Configuration Options

SessionTracker Constructor Options

• plugins: Array of attribution plugins (default: UTM, Google Ads, Facebook, Referrer)
• debug: Boolean to enable debug mode
• shouldPreserveAttribution: Boolean to control attribution preservation (default: true)
• storage: Storage interface (default: localStorage)
• sessionKey: Session storage key (default: 'easyattrib_sessions')
• tabsKey: Active tabs storage key (default: 'easyattrib_active_tabs')

Examples

UTM Override Click ID

URL: example.com?utm_source=newsletter&gclid=abc123
Result: source=newsletter, medium=undefined, clickId=abc123, channel=newsletter/undefined

Click ID Without UTM

URL: example.com?gclid=abc123
Result: source=google_ads, medium=cpc, clickId=abc123, channel=google_ads/cpc

Referrer Attribution

Referrer: https://www.google.com/search?q=example
Result: source=google, medium=organic_search, clickId=null, channel=google/organic_search

Direct Traffic

URL: example.com (no parameters, no referrer)
Result: source=direct, medium=direct, clickId=null, channel=direct/direct