> ## 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.

# Referrer

> Using referrer information in Esper policies.

## 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.

<Info>
  **MDN Web Docs**

  Read more on [Referer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer).
</Info>

## 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

<Info>
  **Privacy Note**

  Modern browsers increasingly limit referrer information for privacy. The `Referrer-Policy` header controls how much information is shared.
</Info>

## Using Referrer in Policies

### Basic Examples

**Block hotlinking:**

```yaml theme={null}
Field Type: Request Path
Operator: ends with
Value: .jpg
AND
Field Type: Referrer
Operator: not contains
Value: yourdomain.com
Action: Block
```

**Track marketing campaigns:**

```yaml theme={null}
Field Type: Referrer
Operator: contains
Value: utm_campaign=summer
Action: Tag as marketing
```

### Advanced Patterns

**Detect referrer spam:**

```yaml theme={null}
Field Type: Referrer
Operator: contains any
Values:
  - viagra
  - casino
  - make-money
  - free-iphone
Action: Block
```

**CSRF Protection:**

```yaml theme={null}
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 Type   | Referrer Pattern          | What It Means          |
| ------------- | ------------------------- | ---------------------- |
| Search Engine | google.com/search         | Organic search traffic |
| Social Media  | facebook.com, twitter.com | Social sharing         |
| Email         | mail.google.com           | Email link clicks      |
| Internal      | yourdomain.com            | Navigation 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

```yaml theme={null}
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

```yaml theme={null}
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:

| Policy        | What's Sent               | Use Case         |
| ------------- | ------------------------- | ---------------- |
| no-referrer   | Nothing                   | Maximum privacy  |
| origin        | Domain only               | Balanced         |
| strict-origin | Domain (HTTPS→HTTPS only) | Security-focused |
| same-origin   | Full URL (same site only) | Internal only    |
| unsafe-url    | Everything                | Full tracking    |

## Working with Marketing

### UTM Parameter Tracking

```yaml theme={null}
# Capture marketing sources
Field Type: Referrer
Operator: contains
Value: utm_source=
Extract campaign data for analytics
```

### Affiliate Link Validation

```yaml theme={null}
# 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:**

```yaml theme={null}
# Don't require referrer
Field Type: Referrer
Operator: is empty
Action: Allow but monitor
```

### Problem: Referrer Spoofing

**Attack:**

```bash theme={null}
curl -H "Referer: https://trusted-site.com" https://target.com
```

**Defense:**

```yaml theme={null}
# 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

```yaml theme={null}
# 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

```yaml theme={null}
# 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

```yaml theme={null}
# 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

```yaml theme={null}
# 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
```

## Related Fields

* [Request Path](./request-path) - Where user is going
* [Client IP](./client-ip) - Where request comes from
* [Headers](./headers) - Referrer is a header
* [User Agent](./user-agent) - Browser sending referrer