Refer App Documentation

How it works

A plain-English explanation of what happens when a visitor arrives at your site.

The beacon

When a visitor loads any page on your site, the beacon script fires and sends information about the visit to your installation. It uses the browser's navigator.sendBeacon API (with a fetch fallback for older browsers) so it fires even if the visitor leaves the page immediately.

Field	What it is	Example
`referrer`	The URL of the page they came from	`https://google.com/search?q=...`
`landing_url`	The full URL of the page they arrived on	`https://yoursite.com/pricing?utm_source=email`
`page_path`	The path, without the domain	`/pricing`
`page_title`	The page's `<title>` tag content	`Pricing — Your Site`
`viewport_category`	Device category from screen width	`mobile`, `tablet`, or `desktop`

Nothing else is sent. No IP address, no device fingerprint, no persistent identifier that could be used to track a person across sites or sessions.

The session cookie

A first-party cookie called rac_session is set in the visitor's browser. It contains a random token — nothing that identifies the person — and it's used to group page views from the same visit into a single session.

The cookie expires after the session window you configure in Settings (default: 30 minutes). Once it expires, the visitor's next page view starts a new session.

The engagement signal

A session is marked as engaged the moment a second beacon hit arrives from the same session token — meaning the visitor clicked through to at least one more page after landing. Sessions with only one page view are marked as not engaged.

This gives you a simple, privacy-safe signal to distinguish visitors who explored your site from those who arrived and left immediately — without any time-based measurement or additional tracking.

The classifier

Once the referrer and landing URL arrive at the server, the classifier reads them and assigns a channel. It works through a priority order:

AI Referrer — the referrer domain matches your AI Taxonomy (e.g. chat.openai.com, claude.ai, perplexity.ai, deepseek.com, grok.com)
Paid Search — UTM medium is cpc, ppc, or paid, or UTM source is a known ad platform
Paid Social — UTM medium is paid_social or similar
Email — UTM medium is email, or the referrer is a known email service provider
Organic Social — the referrer is a known social platform with no paid UTM signal
Organic Search — the referrer is a known search engine with no paid UTM signal
Internal — the referrer is the same domain as the tracked site
Referral — the referrer is any other website
Direct — no referrer at all (typed URL, bookmark, or referrer stripped by browser or privacy settings)

Priority matters. A session with a Google referrer and utm_medium=cpc is classified as Paid Search, not Organic Search, because the paid signal is checked first. The first rule that matches wins.

UTM parameters

If the landing URL contains UTM parameters, they're extracted and stored alongside the session. This is how you attribute traffic from email campaigns, paid ads, or any channel where you control the link:

Parameter	What it tells the classifier
`utm_source`	Where the traffic came from (e.g. `newsletter`, `google`)
`utm_medium`	The marketing channel type (e.g. `email`, `cpc`)
`utm_campaign`	Which campaign sent this visitor
`utm_term`	Search keyword (usually from paid search)
`utm_content`	Which specific ad or link variant

Privacy-resilient c_ parameter aliases

Safari's Intelligent Tracking Prevention and Brave's privacy shields actively strip UTM parameters from links in certain contexts — particularly links opened from private browsing, email apps, and messaging platforms. When this happens, the classifier loses its campaign signal and the session may fall back to Direct.

Refer App supports a set of shorter, privacy-resilient parameter aliases as fallbacks. If a standard UTM parameter is absent, the classifier checks for the equivalent alias:

Alias	Falls back from	Example
`c_src`	`utm_source`	`?c_src=newsletter-july`
`c_med`	`utm_medium`	`?c_med=email`
`c_cam`	`utm_campaign`	`?c_cam=summer-launch`

These aliases are platform-agnostic — they work on any website regardless of what it's built with. The values are sanitized on arrival: lowercased, spaces converted to underscores, special characters stripped. They're stored in the same database columns as their UTM equivalents.

Using both in one URL is not necessary. Standard UTM parameters always take precedence. Only add c_ aliases when you specifically need to protect attribution in privacy-browser contexts, or when using branded short links where you want clean URLs without visible UTM strings.

Example: A privacy-resilient email link

Standard link (UTM may be stripped by privacy browsers):

https://yoursite.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=july

Resilient link (c_ aliases survive when UTM is stripped):

https://yoursite.com/pricing?utm_source=newsletter&utm_medium=email&utm_campaign=july&c_src=newsletter&c_med=email&c_cam=july

Or, using short links — the cleanest option:

https://yoursite.com/go/july-email

First-touch attribution

Only the first page view in a session is marked as the attribution point — the one that carries the actual referrer from wherever the visitor came from. Subsequent page views within the same session are recorded as additional touchpoints and appear in the session journey, but they don't change the attribution channel or source.

Storage

Every session is stored in a single SQLite file on your server. Nothing is sent anywhere else unless you configure an Integrations destination to push data to an external tool.

← PreviousInstallation Next →Dashboard