Skip to content
liwan

Data Collection

liwan is self-hosted web analytics. Events are processed by your liwan server and stored in your deployment. Collection behavior can be adjusted globally and for each entity.

Collection Controls

Section titled “Collection Controls”

You can configure:

  • Visitor grouping: choose accurate, network-based, or random-per-request grouping.
  • Geolocation: store country and city, country only, or no location.
  • UTM parameters: enable or disable campaign attribution fields.
  • Session metrics: enable or disable bounce rate, time on site, entry page, and exit page.
  • Retention: keep all history or remove events after a configured period.
  • Drop rules: discard matching internal, test, local, or other unwanted traffic before storage.

Where Data Is Processed

Section titled “Where Data Is Processed”

The browser sends tracking events to your liwan instance. The server uses the request IP during processing for visitor grouping, rate limiting, and optional geolocation, then discards it. Raw IP addresses are not stored in the events database.

What the Tracker Sends

Section titled “What the Tracker Sends”

The browser tracker can send:

  • Page URL: the current URL with fragments and non-attribution query parameters removed. The server stores the domain and path separately from enabled attribution fields.
  • Referrer: the referring site, if the browser provides it.
  • Attribution parameters: campaign values from the page URL.
  • Screen width bucket: a coarse bucket such as SM, MD, or XL.
  • Orientation: portrait or landscape.
  • Event name: pageview by default. Custom tracking code can send other event names.
  • Page exit: a best-effort exit: true request when a tracked page becomes hidden.

The exit request uses the same page context and updates the matching pageview instead of creating another pageview. Add data-exit="false" to the script element or pass exit: false to trackPageviews to disable it.

The default tracker ignores localhost, loopback addresses, and file:// pages.

What the Server Derives

Section titled “What the Server Derives”

The server can derive:

  • Visitor grouping ID from the client IP, user agent, entity ID, and rotating salt, depending on the selected grouping mode.
  • Browser and platform families from the user agent, without storing full version strings.
  • Device type from the user agent parser.
  • Country and city from MaxMind or trusted proxy headers. MaxMind values take precedence when available.
  • Session timing from intervals between pageviews and an optional terminal-page exit timestamp.

liwan also filters obvious bot traffic and spam or local referrers before storage.

Visitor Grouping

Section titled “Visitor Grouping”
Mode Behavior
Accurate Hashes the exact IP address, user agent, rotating salt, and entity ID. Raw inputs are not stored.
Random per request Generates an unrelated visitor grouping ID for each event.
Network standard Hashes a /24 IPv4 or /56 IPv6 network prefix, rotating salt, and entity ID.
Network balanced Hashes a /28 IPv4 or /64 IPv6 network prefix.
Network accurate Hashes the full IP address without the user agent.

The grouping salt rotates once per day at the configured hour, so visitor groups do not persist across rotation periods.

Geolocation

Section titled “Geolocation”

Geolocation can store country and city, country only, or no location. Data can come from a MaxMind database or trusted proxy headers.

UTM Parameters

Section titled “UTM Parameters”

When UTM tracking is enabled, liwan stores utm_source, utm_medium, utm_campaign, utm_content, and utm_term separately.

The aliases source, medium, campaign, content, and term map to their corresponding UTM fields. ref, referrer, and referer map to utm_source.

Session Metrics

Section titled “Session Metrics”

Session metrics provide bounce rate, average time on site, entry page, and exit page. Average duration can use the next pageview or the final page’s best-effort exit signal, with durations limited to 30 minutes.

Exit signals are ignored when session metrics are disabled, visitor grouping is random per request, or no usable client IP is resolved.

Retention and Pruning

Section titled “Retention and Pruning”

Retention controls how long historical events are kept. Set a period based on how much history you need.

The pruning tool can also apply current collection settings to historical data:

  • Clear UTM fields when UTM tracking is disabled.
  • Clear geolocation fields when geolocation is disabled or reduced.
  • Clear session intervals and exit timestamps when session metrics are disabled.
  • Delete events older than the selected retention period.

Run a dry run first to preview how many events will be affected.

What liwan Does Not Store

Section titled “What liwan Does Not Store”

liwan does not store raw IP addresses, visitor-tracking cookies, cross-site visitor identifiers, full referrer paths, or normal page URL query strings and fragments. Enabled UTM values are stored separately.

To reduce collection, disable unneeded fields, use shorter retention, and add drop rules.