Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.esperr.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What is a Referrer?

The referrer (yes, it’s misspelled in the HTTP spec!) tells you which webpage or source sent the user to your current page. It’s like a trail of breadcrumbs showing where traffic comes from.
MDN Web DocsRead more on Referer.

​
Understanding Referrer Values

​
Full URL Referrer

https://example.com/blog/article?utm_source=social
Shows complete source URL including path and parameters.

​
Domain-Only Referrer

https://example.com/
Shows just the source domain (privacy-focused).

​
Empty Referrer

Common sources of empty referrers:
  • Direct navigation (typed URL)
  • Bookmarks
  • HTTPS→HTTP (blocked by browsers)
  • Privacy settings/extensions
  • Some mobile apps

​
How Referrers Work

  1. User clicks link on Site A
  2. Browser navigates to Site B
  3. Browser sends Referer: https://siteA.com/page
  4. Site B knows traffic came from Site A
Privacy NoteModern browsers increasingly limit referrer information for privacy. The Referrer-Policy header controls how much information is shared.

​
Using Referrer in Policies

​
Basic Examples

Block hotlinking: 
Field Type: Request Path
Operator: ends with
Value: .jpg
AND
Field Type: Referrer
Operator: not contains
Value: yourdomain.com
Action: Block
Track marketing campaigns: 
Field Type: Referrer
Operator: contains
Value: utm_campaign=summer
Action: Tag as marketing

​
Advanced Patterns

Detect referrer spam: 
Field Type: Referrer
Operator: contains any
Values:
  - viagra
  - casino
  - make-money
  - free-iphone
Action: Block
CSRF Protection: 
Field Type: Request Method
Operator: equals
Value: POST
AND
Field Type: Referrer
Operator: not starts with
Value: https://yourdomain.com
Action: Block

​
Common Referrer Patterns

​
Legitimate Sources

Source TypeReferrer PatternWhat It Means
Search Enginegoogle.com/searchOrganic search traffic
Social Mediafacebook.com, twitter.comSocial sharing
Emailmail.google.comEmail link clicks
Internalyourdomain.comNavigation within site
Direct(empty)Typed URL or bookmark

​
Suspicious Patterns

  • Spam sites: Random domains with keywords
  • Spoofed referrers: Impossible sources
  • Referrer injection: XSS attempts in referrer
  • Bot traffic: Consistent fake referrers

​
Security Considerations

​
Open Redirect Prevention

Field Type: Query Parameter
Field Reference: redirect
Operator: is present
AND
Field Type: Referrer
Operator: not starts with
Value: https://yourdomain.com
Action: Block

​
Clickjacking Detection

Field Type: Referrer
Operator: is not empty
AND
Field Type: Header
Field Reference: X-Frame-Options
Operator: is not present
Action: Add header: SAMEORIGIN

​
Best Practices

​
DO:

  • Allow empty referrers - Many legitimate reasons
  • Check referrer for state-changing operations - CSRF protection
  • Monitor referrer patterns - Understand traffic sources
  • Validate for sensitive actions - Extra security layer
  • Consider referrer policies - Balance security and privacy

​
DON’T:

  • Require referrer always - Will block legitimate users
  • Trust referrer completely - Easily spoofed
  • Store sensitive data in referrer URLs
  • Block all external referrers - Breaks incoming links
  • Ignore privacy trends - Referrers becoming less reliable

​
Referrer Policy Impact

Modern Referrer-Policy settings affect what you see:
PolicyWhat’s SentUse Case
no-referrerNothingMaximum privacy
originDomain onlyBalanced
strict-originDomain (HTTPS→HTTPS only)Security-focused
same-originFull URL (same site only)Internal only
unsafe-urlEverythingFull tracking

​
Working with Marketing

​
UTM Parameter Tracking

# Capture marketing sources
Field Type: Referrer
Operator: contains
Value: utm_source=
Extract campaign data for analytics

# Verify affiliate traffic
Field Type: Referrer
Operator: matches regex
Value: https://partner\d+\.affiliates\.com
AND
Field Type: Query Parameter
Field Reference: ref
Operator: is present
Action: Track affiliate

​
Common Issues and Solutions

​
Problem: Missing Referrers

Causes:
  • HTTPS to HTTP
  • Privacy extensions
  • Meta refresh redirects
  • JavaScript navigation
Solution: 
# Don't require referrer
Field Type: Referrer
Operator: is empty
Action: Allow but monitor

​
Problem: Referrer Spoofing

Attack: 
curl -H "Referer: https://trusted-site.com" https://target.com
Defense: 
# Verify with additional signals
Field Type: Referrer
Operator: equals
Value: https://admin.internal
AND
Field Type: Client IP
Operator: not in range
Value: 10.0.0.0/8
Action: Block

​
Analytics and Business Intelligence

​
Traffic Source Analysis

# Categorize traffic sources
If Referrer contains "google.com":
  Tag: search-traffic
If Referrer contains "facebook.com":
  Tag: social-traffic
If Referrer is empty:
  Tag: direct-traffic

​
Conversion Tracking

# Track referrer to conversion
Field Type: Request Path
Operator: equals
Value: /checkout/success
Log referrer for conversion attribution

​
Troubleshooting

“Referrer policy blocking data”
  • Check site’s Referrer-Policy header
  • Test with different browsers
  • Verify HTTPS configuration
  • Review privacy settings
“False positives on referrer checks”
  • Allow empty referrers
  • Consider mobile apps
  • Account for privacy tools
  • Test with real user scenarios

​
Advanced Patterns

​
Cross-Domain Security

# API requires same-origin referrer
Field Type: Request Path
Operator: starts with
Value: /api
AND
Field Type: Referrer
Operator: not matches
Value: ^https://([^/]+\.)?yourdomain\.com
Action: Block

​
Traffic Protection

# Bots often have inconsistent referrers
Field Type: User Agent
Operator: contains
Value: bot
AND
Field Type: Referrer
Operator: equals
Value: https://yourdomain.com
Action: Challenge  # Suspicious self-referrer