Omniscio

Share view tracking (privacy contract for the view counter)

When you protect a share (password / view cap / notify-on-view) or even just publish one and leave it open, Omniscio needs to know whether — and how often — strangers on the internet are actually opening your link. That bookkeeping is now a view counter: the Cloud Function increments viewCount and stamps lastViewedAt on the share's own document, the desktop mirrors those two fields about once a minute while your shares are active, and a new view fires an OS notification when notify-on-view is on. No per-view audit row is kept. When nothing has happened for a few minutes the desktop slows to checking once every 5 minutes, so the first new view after a quiet spell can take up to about 5 minutes to appear.

On this page

What it is

When you protect a share (password / view cap / notify-on-view) or even just publish one and leave it open, Omniscio needs to know whether — and how often — strangers on the internet are actually opening your link. That bookkeeping is the view-tracking pipeline: a count and a last-viewed timestamp on the share's Firestore document, mirrored back to the desktop about once a minute while your shares are active (slowing to once every 5 minutes after a quiet spell), plus an OS notification when the count advances and the share has notify-on-view turned on. There is no per-view event log any more — the old one was retired because nothing read it.

This page is the privacy contract for that pipeline. It answers: what is captured per view, where does it live, who can read it, how long does it stay, and what happens when you revoke or delete a share. If you only want to know how to turn the feature on, see shares-view.md § The detail pane (the toggles) and share-artifacts.md § Per-share protection (the publish-time model).

What gets captured per view

When a viewer opens https://shares.omniscio.com/s/<token> and the share gate decides to serve (i.e. not revoked, not expired, password unlocked or absent, view cap not yet hit), the Cloud Function increments the view counter inside a Firestore transaction and stamps lastViewedAt. That is the whole of the per-view record: a count and a timestamp on the share's own document. No per-view event document is written. The old shares/<token>/events audit log is retired — nothing writes to it any more, and the rows written before the change purge by their Firestore TTL.

For a share with a view cap, a served view also leaves one small server-side record so the cap counts viewers rather than reloads:

what where what it holds
viewer dedupe doc shares/<token>/viewers/<viewerKey> viewedAt and expireAt (about 180 days). viewerKey is a salted hash of the viewer's network prefix — /24 for IPv4, /64 for IPv6 — never the raw address, and the User-Agent is deliberately not part of the key. One network counts once, so a reload does not consume another view.
counted-view grant inside the share site's __session cookie A signed grant scoped to that one share, so a reload is served without re-counting the view.

An uncapped share writes no per-viewer record at all — only the counter.

On a capped share, every read uses a view (2026-11-06). A script, a link-preview bot (Slack, email), a browser prefetch and a click from another site all count — once per network, as above — so a view limit cannot be read past by any request that claims not to count. A capped link opens directly, with no extra "one step to open this link" page. The app's own background checks of a capped share get an empty reply instead, so Omniscio itself never uses up your views. On an uncapped share, machines and prefetches still do not count.

Things that are NOT captured for a shared page: raw IP, browser fingerprint, screen resolution, referrer URL, time spent on the share page, click-through events, URL hash, or any data the viewer typed into a form on the share page (forms inside the share's HTML are sandboxed and can't reach the CF). The one per-viewer fact that is retained for a page, and only for a capped share, is the salted network-prefix hash described above. The share site sets one __session cookie for its own host — it carries the password-unlock grant, the counted-view grant and workspace grants, each signed and scoped to one share — and it is never used for analytics or advertising, and never sent anywhere else.

A shared screen recording works differently. It plays on the recorder's own viewer page, which sends a watch beacon as the video plays. One viewing session per play records how far the viewer got, the seconds actually watched, the video's length, a coarse country, and salted pseudonymous hashes of the viewer's IP and User-Agent — userAgentHash and ipHash are salted SHA-256 hashes, never the raw values. The sessions live in a watch subcollection under the share, are readable only by the share's owner, expire after 180 days, and are what the Review Window's Viewer analytics panel summarises (counts only until a share has 5 views). See Screen Recorder (part 4) § Viewer analytics.

Those two parent-document fields (viewCount and lastViewedAt) are what the Omniscio poller actually reads on the 60s tick. There is no per-view event subcollection to walk.

Where to find it

Where the data lives

There are two stores, kept in sync one-way:

  1. Firestore (authoritative writer) — the Cloud Function increments viewCount and stamps lastViewedAt on the share's mirror doc inside one transaction. A view-capped share also gets its per-viewer dedupe docs under shares/<token>/viewers. No Omniscio instance can write the count; only the Cloud Function can.
  2. SQLite — the local share_links row mirrors view_count and last_viewed_at from the poller. The sibling share_view_events table still exists in the schema for older installs but nothing writes new rows into it: the per-view feed it mirrored was retired (see "How Omniscio pulls the data back").

There is no log file, no analytics provider, no email digest, and no per-view audit row. The pipeline lives entirely inside Firebase (your project) and your local Omniscio's SQLite.

How it behaves

Hash salting

The viewer key is a salted SHA-256 hash computed at the Cloud Function with a per-deploy secret plus a per-share context label. The desktop stores nothing of it — the key exists only on the server side and in the viewer dedupe document's id.

The salt is fail-closed: with the salt or the address empty the scope is null, never a bare/unsalted value, and a null key means the request is not deduped at all (it counts as before, rather than freezing the counter). An unsalted SHA-256 of an IPv4 address is rainbow-table-reversible, so this matters. Each viewer dedupe doc also carries a server-stamped expireAt, so a counted viewer ages out after about 180 days instead of pinning that network out of the count for ever.

Because the key is scoped per share and per deploy, the same network is recognisable across reloads of that one share, but the value does not join against another share, another subsystem, or another install. The raw IP address is never persisted.

Tripwire: any surface that AGGREGATES view records and presents them as "anonymized" MUST first apply a minimum-cohort (k) suppression — the screen-recording watch-analytics panel does exactly this (k=5) for the sibling share_watch_sessions store.

How Omniscio pulls the data back

The view poller runs on a 60-second tick. Per tick:

  1. Short-circuit on missing creds. isMirrorAvailable() returns false if no Firebase service-account key is wired up. The poller keeps running so the user can add credentials without restarting Omniscio, but the body of the tick is skipped — no Firestore round-trip, no work.
  2. List local active shares. listActiveShareTokens() selects every share row that is not revoked / not expired / not pending.
  3. Read mirror state. fetchChangedShares() asks the relay which shares changed since a persisted cursor, rather than reading every share doc: the cursor is on lastActivityAt, a Firestore server timestamp stamped by every path that changes what the poller reads. An idle tick costs about one read, and a busy one costs exactly the shares that actually moved. Tokens not present in Firestore are silently skipped (share predates the mirror, or publish-time sync failed — either way the local count stays unchanged). A transient read failure (machine asleep → dead network, flaky wifi) is logged locally and retried on the next tick, not escalated to Sentry — only a permanent/config error (e.g. PERMISSION_DENIED) is. The poller's own per-share reconcile-failure inbox alert is the user-facing escalation for a share that stays broken.
  4. Diff each share's count. For every remote row where remote.viewCount > local.viewCount, call reconcileShare():
    • Call setShareViewCountFromMirror(shareId, remoteViewCount, remoteLastViewedAt) to update the parent share_links row's view_count / last_viewed_at columns. The mirror is the writer, Omniscio is the reader. Omniscio's local count is never pushed back to Firestore.
    • There is no per-view event feed to pull. The relay exposes no events-read operation, VIEW_EVENTS_MIRROR_SUPPORTED is false, and fetchRecentViewEvents() returns [], so the poller skips its event-fetch block entirely. The local share_view_events table stays empty on a current install; older installs may hold legacy rows, which are removed when the share is deleted.
    • If the share has notify_on_view = 1, fire notificationService.showOnce() with dedupe key share-view-<shareId>-<remoteViewCount> and the message "<label>" was just viewed (<count> total). The count in the key still suppresses a repeat of the SAME count — but the popup itself is coalesced per share: takeViewNotifySlot allows at most one per share per rolling hour (VIEW_NOTIFY_MIN_INTERVAL_MS / lastViewNotifiedAtMs), with the running total travelling in the body. A burst — a link opened in a group chat, or a link reloaded — therefore reads as ONE notification rather than one per view. A restart re-arms it, which is the safe direction (at worst one extra popup, never a suppressed real one).
    • Emit IPC.SHARE_UPDATED push so any open Shares view re-renders the badge.

Crash-safety: the SQLite count write commits before the notification fires. If Omniscio crashes between the count write and showOnce(), the next tick re-reads the count, sees no delta (already-mirrored count), and doesn't double-notify. The cost is at most one missed notification, never a duplicate. (showOnce's own 24h dedupe map provides additional belt-and-suspenders coverage if the process restarts mid-tick.)

How notify-on-view actually fires

The OS-level notification is the only outbound signal in the whole pipeline — every other action is reading data the publisher already has access to. The notification:

  • Fires from the desktop app's process (main-process notificationService), not from the CF and not from a push-notification service. If Omniscio isn't running, the notification is deferred until the next time Omniscio starts (and Firestore has the count delta waiting).
  • Is per-share, per-count, and capped to one popup per share per rolling hour — dedupeKey: share-view-<id>-<count>, but takeViewNotifySlot refuses to fire again inside the window, so view 1 and view 2 a minute apart produce ONE notification carrying the running total rather than two. Without that cap the count-in-key dedupe suppressed only a repeat of the same count, which meant anyone holding the share URL could reload the page and flood the owner's desktop — each driven view also costing a relay invocation and a Firestore write.
  • Has a 24h dedupe window baked into notificationService.showOnce(), so a single share+count combination can't fire more than once a day even if the poller restarts mid-batch (which would otherwise re-run the reconciliation).
  • Surfaces with the share's user-supplied label if one exists; falls back to "A shared item was just viewed (<count> total)" if no label.
  • Is NOT batched by Focus Mode. View notifications are informational and not in Focus Mode's eligible-items set — they always fire immediately if notify_on_view is on, regardless of focus state.

If you want to stop receiving view notifications for one share, open it in the Shares view and untick "Notify me when someone views this share" in the share's detail pane — the change syncs to the Firestore mirror on save, but the poller's check is against the local share_links.notify_on_view column, so the toggle takes effect on the next poll (usually within a minute, and at most about 5 minutes after a quiet spell) regardless of whether the mirror sync has landed yet.

What happens on revoke and delete

Operation What stays What goes
Revoke (detail pane → Revoke) Mirror doc (with active: false), including viewCount / lastViewedAt; any viewer dedupe docs; legacy SQLite event rows; the storage blob Future views — the gate refuses with 410 "this share has been revoked"
Delete (detail pane → Delete) Nothing Mirror doc + every Firestore subcollection under it (viewers, legacy events, comments and so on — recursiveDelete); legacy SQLite event rows (deleteShareViewEventsForShare); the storage blob; the share_links row
Expiration (expiresAt in past) The local row in your Shares list (Archived & expired) Within about 15 minutes the app unpublishes it — a full teardown of the stored page or video, the cloud record and its comments and subcollections, so the link answers 404 "Share Not Found". The "this share has expired" page is only what a visitor sees in the window before that sweep (longer if Omniscio is not running)

A screen recording works differently on revoke. Stop sharing tears the share down — the uploaded video and the share record are removed from the cloud, so the link stops resolving instead of answering a 410 page. The kept-blob and 410 behaviour in the table above applies to file and page shares.

Delete is irreversible — the share row, the Firestore document and everything under it (including any per-viewer dedupe docs), and the storage blob are all hard-removed.

What an outside AI sees vs. what you see

If you publish a share, anyone with the URL can view the share content. They cannot see:

  • The view counter (it's not rendered into the share page — only the publisher's Shares view shows it)
  • The list of past viewers (no per-view row exists to serve, and nothing about the viewer is shown to anyone)
  • Whether other people have viewed it
  • Whether you have notify-on-view turned on
  • Whether you've set a view cap (until they hit it — then they get a 410 "view limit reached" page)

The publisher (you) sees the view count and last-viewed time in the per-share row in shares-view.md. A future per-share detail panel (not yet shipped) would have visualised an event timeline; there are no per-view event rows left to draw it from.

Disabling view tracking entirely

The view-counter increment is always on — even for shares with no password, no view cap, and notify_on_view = false. The reason: a future version of the Shares view will show "viewed 12 times" badges for every share, and breaking the counter into an opt-in feature would silently disable that for existing shares.

To stop keeping view data, a file or page share has to be deleted (revoke keeps the count and any per-viewer record); stopping a screen recording's share removes its viewing sessions along with the link. To stop firing notifications, untick notify-on-view per-share. There is no global "kill view tracking" toggle today — the design rationale is that the counter holds no raw IP or User-Agent, and the only per-viewer value is a salted, per-share network-prefix hash that expires after about 180 days, so the storage and privacy cost is bounded regardless of how many shares you publish. Note that hash is pseudonymous rather than anonymous — a GDPR-regulated deployment should weigh that, though for an uncapped share nothing per-viewer is stored at all. If that calculus needs to change, the lever to add is a disableViewTracking AppSetting that the publish path checks before writing the Firestore mirror doc — but it doesn't exist yet.

  • share-artifacts.md — the publish-time view of the same pipeline (how to set a view cap / password / notify-on-view at create time)
  • artifact-sharing.md — the sibling feature for session/message/selection shares, same view-tracking pipeline
  • shares-view.md — the sidebar UI that surfaces the counter and the detail pane's per-share protection toggles
  • share-cli.md — CLI publishes go through the same view-tracking pipeline; the CLI body schema does not accept protection fields, so CLI-published shares start unprotected and use the in-app detail pane to add gates

Last verified 2026-11-05