# SFR Analytics — Settings Guide

A complete reference for every option on the **Analytics > Settings** page.

---

## Table of Contents

1. [General Settings](#general-settings)
   - [Data Retention](#data-retention-days)
   - [Exclude User Roles](#exclude-user-roles)
   - [Session Timeout](#session-timeout)
   - [Anonymize IP Addresses](#anonymize-ip-addresses)
   - [Respect Do Not Track](#respect-do-not-track)
2. [Ignore IP Addresses](#ignore-ip-addresses)
   - [Your IP Status](#your-ip-status)
   - [Adding a Single IP](#adding-a-single-ip)
   - [Adding an IP Range (CIDR)](#adding-an-ip-range-cidr)
   - [Common CIDR Examples](#common-cidr-examples)
   - [Managing the Ignore List](#managing-the-ignore-list)
3. [Ignore Countries](#ignore-countries)
   - [How Country Detection Works](#how-country-detection-works)
   - [Adding a Country](#adding-a-country)
   - [Common Country Codes](#common-country-codes)
   - [Managing Ignored Countries](#managing-ignored-countries)
4. [Data Management](#data-management)
   - [Retention Cleanup](#retention-cleanup)
   - [Reset All Data](#reset-all-data)
5. [GDPR Compliance](#gdpr-compliance)

---

## General Settings

These are the core configuration options. After changing any of these, click **Save Settings**.

### Data Retention (Days)

| Setting | Default | Range |
|---------|---------|-------|
| `sfran_retention_days` | 365 | 30–3650 |

How long analytics data is kept before automatic deletion. A daily cron job removes records older than this value.

**Recommendations:**
- **365 days** (1 year) is suitable for most sites — gives year-over-year comparison.
- **90 days** if storage is a concern or you only need recent trends.
- **3650 days** (10 years) if you want to keep everything long-term.

> **Note:** Reducing this value does not immediately delete old data. Click **Clean Up Old Data Now** in the Data Management section to apply the new retention period immediately.

---

### Exclude User Roles

| Setting | Default |
|---------|---------|
| `sfran_exclude_roles` | Administrator |

Logged-in users with any of the checked roles will not be tracked. Their pageviews are silently skipped.

**Recommendations:**
- Always keep **Administrator** checked — you don't want your own dashboard visits inflating the numbers.
- Consider also checking **Editor** if editors spend a lot of time on the front-end previewing content.
- Leave **Subscriber** unchecked unless subscribers are internal team members.

---

### Session Timeout

| Setting | Default | Range |
|---------|---------|-------|
| `sfran_session_timeout` | 1800 (30 min) | 300–7200 |

The number of seconds of inactivity before a visitor's session expires and a new session begins. This affects how "sessions" are counted in your dashboard.

**How it works:** When a visitor loads a page, SFR Analytics checks their session cookie. If more time than this has elapsed since their last pageview, a new session is started.

**Recommendations:**
- **1800 seconds (30 minutes)** — the industry standard, used by Google Analytics. Best for most sites.
- **900 seconds (15 minutes)** — if your content is short-form and visitors make quick decisions.
- **3600 seconds (60 minutes)** — if visitors tend to read long articles or leave tabs open.

> **Tip:** Lowering the timeout increases the session count (more sessions per visitor). Raising it decreases the count. If you're comparing with another analytics tool, match their session timeout for consistent numbers.

---

### Anonymize IP Addresses

| Setting | Default |
|---------|---------|
| `sfran_anonymize_ip` | Off |

When enabled, the last octet of IPv4 addresses is removed before any processing (e.g. `98.96.173.59` becomes `98.96.173.0`). This improves visitor privacy but reduces the precision of IP-based features like the IP ignore list.

**Recommendations:**
- **Enable** if you want stronger GDPR/privacy compliance.
- **Keep off** if you need precise IP exclusion (e.g. ignoring your exact office IP).

> **Important:** SFR Analytics does not store raw IP addresses in the database — only hashed visitor identifiers. This setting affects the hash input, not stored data.

---

### Respect Do Not Track

| Setting | Default |
|---------|---------|
| `sfran_respect_dnt` | On |

When enabled, visitors whose browser sends the `DNT: 1` (Do Not Track) header will not be tracked at all.

**Note:** Major browsers have largely deprecated the DNT header, and most analytics services ignore it. However, a small percentage of privacy-conscious users still set it.

**Recommendations:**
- **Keep on** for maximum privacy respect.
- **Turn off** if you find it's excluding a meaningful portion of your audience and you want complete data.

---

## Ignore IP Addresses

This section lets you exclude specific IP addresses or entire IP ranges from analytics tracking. Ignored visitors can still access the site normally — their activity simply won't appear in the analytics data.

### Your IP Status

At the top of this section, you'll see a coloured banner showing your current IP address and whether it's currently being ignored:

- **Red banner** — "Your IP address is not ignored" with an **Ignore This IP** button
- **Blue banner** — "Your IP address is ignored" with a **Stop Ignoring** button

This is the quickest way to exclude yourself — one click and your current IP is added to the ignore list.

> **Tip:** If you access the site from multiple locations (office, home, mobile), you'll need to add each IP separately or use a CIDR range that covers them.

---

### Adding a Single IP

Enter a standard IPv4 or IPv6 address in the text field and click **Add**.

**Examples:**
- `98.96.173.59` — a single IPv4 address
- `2001:db8::1` — a single IPv6 address

---

### Adding an IP Range (CIDR)

CIDR (Classless Inter-Domain Routing) notation lets you ignore an entire block of IP addresses with a single entry. The format is `IP/prefix_length`, where the prefix length determines how many addresses are covered.

**How CIDR works:**

The prefix length specifies how many bits of the IP address are fixed. The remaining bits can be anything — those are the addresses in the range.

For IPv4 (32-bit addresses):
- `/32` = exactly 1 address (same as a single IP)
- `/24` = 256 addresses (last number varies: 0–255)
- `/16` = 65,536 addresses (last two numbers vary)
- `/8` = 16,777,216 addresses (last three numbers vary)

### Common CIDR Examples

| CIDR | Range | Addresses | Use Case |
|------|-------|-----------|----------|
| `192.168.1.0/24` | 192.168.1.0 – 192.168.1.255 | 256 | A typical local/office network |
| `10.0.0.0/8` | 10.0.0.0 – 10.255.255.255 | 16.7M | All private 10.x.x.x addresses |
| `172.16.0.0/12` | 172.16.0.0 – 172.31.255.255 | 1M | Private 172.16–31.x.x range |
| `203.0.113.0/28` | 203.0.113.0 – 203.0.113.15 | 16 | A small office IP block |
| `98.96.0.0/16` | 98.96.0.0 – 98.96.255.255 | 65,536 | An ISP's address block |

**Quick reference — "How do I block...?"**

| I want to ignore... | Enter this |
|---------------------|-----------|
| Just my IP | `98.96.173.59` |
| My IP and nearby (same /24) | `98.96.173.0/24` |
| My ISP's range | Ask your ISP for their CIDR block, e.g. `98.96.0.0/16` |
| All private/internal IPs | `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16` |
| A specific small block | Count addresses needed and use the closest prefix (see table above) |

> **How to find your CIDR range:** If you know your IP is `98.96.173.59` and you want to ignore everything in `98.96.173.*`, use `98.96.173.0/24`. For your entire ISP block, look up your IP at [bgp.he.net](https://bgp.he.net/) or run `whois 98.96.173.59` to find the allocated block.

---

### Managing the Ignore List

The **Ignored IPs** table shows all current entries with:
- **IP / Range** — the exact IP or CIDR range
- **Type** — "Single IP" or "CIDR Range"
- **Actions** — a red **Remove** button (with confirmation prompt)

Entries that match your current IP are labelled **(you)**.

---

## Ignore Countries

Block all traffic from entire countries. Visitors from ignored countries can still access the site, but their pageviews won't appear in analytics.

### How Country Detection Works

SFR Analytics determines visitor country from HTTP headers provided by your CDN or proxy:

| Header | Provider |
|--------|----------|
| `HTTP_CF_IPCOUNTRY` | CloudFlare |
| `HTTP_CLOUDFRONT_VIEWER_COUNTRY` | AWS CloudFront |
| `HTTP_X_COUNTRY_CODE` | Various proxies |

There is also a WordPress filter hook (`sfran_get_country_code`) for custom GeoIP implementations (e.g. MaxMind GeoLite2).

> **Important:** If your site is **not** behind a CDN that provides country headers, country detection will not be available and this filter will have no effect. Most production WordPress sites using CloudFlare will have this automatically.

---

### Adding a Country

Enter a **2-letter ISO 3166-1 alpha-2 country code** in the text field and click **Add**.

The code must be exactly 2 uppercase letters. The plugin will automatically convert lowercase input to uppercase.

### Common Country Codes

| Code | Country | | Code | Country |
|------|---------|---|------|---------|
| US | United States | | DE | Germany |
| GB | United Kingdom | | FR | France |
| CA | Canada | | IT | Italy |
| AU | Australia | | ES | Spain |
| NZ | New Zealand | | NL | Netherlands |
| IE | Ireland | | SE | Sweden |
| IN | India | | JP | Japan |
| CN | China | | KR | South Korea |
| RU | Russia | | BR | Brazil |
| UA | Ukraine | | ZA | South Africa |

For a full list, see: [ISO 3166-1 alpha-2 on Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

**Common use cases:**
- **Ignore your own country** during development/testing if you're the primary visitor.
- **Ignore high-bot-traffic countries** if you notice large volumes of unverified traffic from specific regions.
- **Focus on target markets** by ignoring countries outside your audience.

---

### Managing Ignored Countries

The **Ignored Countries** table shows:
- **Code** — the 2-letter country code
- **Country** — the full country name (auto-resolved from a built-in list of 150+ countries)
- **Actions** — a red **Remove** button with confirmation prompt

---

## Data Management

### Retention Cleanup

Click **Clean Up Old Data Now** to immediately delete records older than your configured retention period. This runs the same cleanup that the daily cron job performs.

Useful when:
- You've just reduced the retention period and want it applied immediately.
- You want to free up database space right now rather than waiting for the next cron run.

### Reset All Data

Click **Reset All Analytics Data** to permanently delete ALL analytics data and start fresh. This:

- **Empties** the main analytics table (`wp_sfran_analytics`)
- **Empties** the buffer table (`wp_sfran_analytics_buffer`)
- **Empties** the metadata table (`wp_sfran_analytics_meta`)
- **Clears** all transient query caches

This does **NOT** delete:
- Your settings (retention, roles, IPs, countries, etc.)
- The database tables themselves (they remain, just empty)

> **Warning:** This action cannot be undone. A confirmation prompt will appear before proceeding. Use this when you want a clean slate, e.g. when comparing with another analytics plugin or after major site changes.

---

## GDPR Compliance

SFR Analytics is designed with privacy in mind:

- **No PII stored** — IP addresses are hashed, not stored in plain text.
- **Local storage only** — all data stays on your server. Nothing is sent to third parties.
- **IP anonymization** — optional removal of the last IP octet before hashing.
- **Do Not Track** — respects the browser DNT header (when enabled).
- **Data retention** — automatic cleanup of old data on a configurable schedule.
- **Data reset** — ability to delete all data at any time.

A ready-to-use **Privacy Policy Text** is provided on the settings page. Copy it into your site's privacy policy to inform visitors about the data collection.

---

## Settings Reference Table

A quick-reference summary of all configurable options:

| Option | Type | Default | Location |
|--------|------|---------|----------|
| Data Retention | Number (days) | 365 | General Settings |
| Exclude Roles | Checkboxes | Administrator | General Settings |
| Session Timeout | Number (seconds) | 1800 | General Settings |
| Anonymize IPs | Checkbox | Off | General Settings |
| Respect DNT | Checkbox | On | General Settings |
| Ignore IPs | List (IP/CIDR) | Empty | Ignore IP Addresses |
| Ignore Countries | List (2-letter codes) | Empty | Ignore Countries |

---

## Database Options Reference

For developers — all WordPress options used by the settings:

| Option Name | Type | Default | Description |
|-------------|------|---------|-------------|
| `sfran_retention_days` | int | 365 | Data retention in days |
| `sfran_exclude_roles` | array | `['administrator']` | Roles excluded from tracking |
| `sfran_exclude_ips` | array | `[]` | IPs and CIDR ranges to ignore |
| `sfran_exclude_countries` | array | `[]` | 2-letter country codes to ignore |
| `sfran_session_timeout` | int | 1800 | Session timeout in seconds |
| `sfran_anonymize_ip` | bool | false | Anonymize IPs before hashing |
| `sfran_respect_dnt` | bool | true | Honour Do Not Track header |

---

*Last updated: February 2026*