Privacy and compliance readiness

OwlEye gives teams privacy controls. It does not hand out a magical compliance sticker.

This page documents the current technical behavior and an operator checklist. It is not legal advice, and deploying OwlEye does not by itself satisfy the GDPR, India’s DPDP Act and Rules, or another privacy law. Your organization still chooses its purposes, lawful basis, notices, contracts, transfer mechanism, retention schedule, and request-handling process.

Who is responsible for what?

The customer operating a measured app is the controller/data fiduciary for visitor analytics.
OwlEye usually acts as that customer’s processor/data processor for those analytics facts.
OwlEye is normally a controller/data fiduciary for the account, security, support, and billing data it collects for operating the hosted service.

Real roles depend on the actual arrangement, not a product label. Record the assessment and execute the required processing terms before production use.

Technical baseline

OwlEye currently provides these controls:

The public SDK writes no cookies, local storage, or session storage and sends requests without browser credentials.
Do Not Track and Global Privacy Control suppress SDK tracking by default. When either request signal reaches the ingestion API, it acknowledges the request with zero accepted events, even if the browser-side check was explicitly disabled.
autoStart: false lets an integrator wait for a consent or lawful-basis decision before starting automatic page analytics.
Query strings and URL fragments are excluded by default. Campaign capture is a separate, bounded opt-in for utm_source, utm_medium, and utm_campaign.
The API discards the raw client address after in-memory GeoIP lookup and prefix reduction. It stores location fields and a keyed, site-scoped cohort identifier—not the source IP.
Cohort identifiers are pseudonymous, not anonymous. They can still single out activity within their useful window and must be treated as personal data where applicable.
Analytics retention is server-managed from the confirmed plan and stamped on every new fact. Ordinary analytics reads exclude facts after their active window; durable workers reconcile notices, grace periods, purge work, and completion evidence.
App deletion submits a site-scoped analytics deletion before archiving its SQLite control plane.
Owner, admin, and read-only permissions are checked server-side for the named app.
Console sessions use rotating, HttpOnly credentials and unsafe console requests require the configured console origin.
Account holders can download a bounded account/control-plane export. Guarded account deletion removes the live canonical user/authentication record after owned apps and organizations are transferred or deleted; separate logs, recipients, audit evidence, and backups need their own reviewed retention and deletion process.

Cookie-free is a data-minimization choice, not a universal exemption from notice or consent. Configure tracking based on the rules that apply to your product and audience.

When tracking must wait:

import { useAnalytics } from "@owleye/analytics";

const analytics = useAnalytics("your-site-id", {
  autoStart: false,
  server: "https://api.owleye.dev",
});

// Run only after your consent or lawful-basis decision.
analytics.start();

// Run when processing must stop for this page.
analytics.stop();

Your consent manager remains responsible for presenting choices, recording proof where required, and handling withdrawal across every technology—not only OwlEye.

Retention and deletion

Owners configure retention in Settings → Privacy baseline. A shorter selection affects existing and future facts; a longer selection affects future facts only and cannot revive deleted data. ClickHouse performs TTL and explicit site deletion asynchronously, so operators should monitor mutation health and backups.

An event request that already read the previous app state can finish after a mutation snapshot. A deployment promising a hard-delete deadline must also fence new writes, reconcile in-flight events, verify mutation completion, and keep that evidence; mutation acceptance alone is not completion.

Backups need their own expiry and deletion procedure. A row disappearing from the primary database does not automatically remove an independent backup, log sink, warehouse copy, or support export.

Rights requests

The console exposes two different export boundaries:

Account export: GET /v1/account/export returns the signed-in person’s profile, memberships, session metadata, and account audit records.
App event export: an app owner can export a bounded set of analytics facts from Developer settings without raw addresses, arbitrary query strings, or payload blobs.

DELETE /v1/account deletes the live canonical account after ownership is resolved. App owners can separately request app analytics deletion; ClickHouse completes that mutation asynchronously, and the SQLite app record is archived rather than physically removed by that operation.

OwlEye intentionally does not keep a direct visitor identity. That reduces risk but does not erase the controller’s duty to assess access, correction, deletion, objection, portability, grievance, and appeal requests. Document how your team verifies a requester without collecting extra identity just for analytics. Do not claim that a pseudonymous cohort is anonymous or impossible to relate to other information.

Before production

Complete these organizational controls outside the codebase:

Map account and analytics processing in a ROPA/data inventory; name each purpose, category, recipient, location, lawful basis, and retention period.
Publish a clear privacy notice and working privacy/grievance contact. Keep consent requests separate and understandable where consent is used.
Sign processor terms and DPAs, list subprocessors, and document international-transfer grounds and supplementary measures.
Complete a DPIA or equivalent risk assessment when monitoring, scale, location, sensitive data, or audience makes it necessary.
Test request intake, identity verification, export, correction, deletion, objection/opt-out, grievance, appeal, and nominee workflows against applicable deadlines.
Maintain encryption, access review, backups, restore tests, monitoring, vulnerability handling, and an incident plan that can meet the shortest applicable notification deadline.
Do not collect passwords, payment details, free-form messages, precise location, children’s data, or sensitive/special-category data in event names or custom properties without a separately reviewed need and control set.
For cloud operation, publish the actual legal entity, regions, subprocessors, security contact, privacy contact, deletion schedule, and service terms before accepting production data.

Regulatory coverage

The shared baseline—purpose limitation, minimization, transparency, security, retention, rights, contracts, and transfer controls—supports work under EU/UK GDPR, India’s DPDP framework, CCPA/CPRA, PIPEDA, PIPL, LGPD, and APPI. Each regime still has distinct definitions, exemptions, timelines, children’s rules, local-representative requirements, and regulator processes.

The repository includes operational templates in docs/compliance/, plus a fuller control and gap matrix in COMPLIANCE.md. Have qualified counsel and your security/privacy owners adapt them to the real organization and deployment.