How attribution works

A visit leaves an opaque receipt in the browser. After an install, the hook finds that receipt on the same computer and reports it. The service resolves it back to the visit.

#1. The visit

When your install page loads, the SDK asks your CLItrail service to record the visit with POST /v1/visits. The request carries the page's origin and path, the referrer, the session's campaign source and the ad identifiers the page can see, such as a GA4 client ID or a gclid. See What is collected for the full list.

The service stores the visit and returns a marker containing a new random receipt: 256 bits, base64url encoded. The server keeps only the receipt's SHA-256 hash.

#2. The marker

The SDK writes the marker to the website's Origin Private File System (OPFS) as opfs-install-attribution.<website>.<url id>.json, then confirms the write with POST /v1/visits/activate. A marker that was never activated never matches.

{
  "format": "opfs-install-attribution",
  "version": 1,
  "project": "p_04de14934e8005ed97dd",
  "url_id": "url_96f86d390b35cfa7",
  "origin": "https://acme.dev",
  "receipt": "5GodFohsqck6lAXWFydmiZTBXvtQnU2WzbpsB8tq-_k",
  "created_at": 1790171920120,
  "expires_at": 1792763920120
}

The marker contains no identifiers, URL or referrer. Those stay on the server. The URL-ID is url_ plus the first 16 hex characters of the SHA-256 of the page's origin and path, so query strings and fragments never create new pages. A revisit to the same page replaces its marker and revokes the previous receipt; the visits it replaced stay in the install's journey while they are still unexpired. Markers expire after 30 days, or earlier if the browser clears site data.

#3. The install

After your installer succeeds, the hook looks for CLItrail marker files inside the storage folders of supported browsers for the current OS user. It reads only small files, validates CLItrail's own flat JSON format for your website, and never evaluates file contents. It then posts the opaque receipts it found, a random installation ID and the event type to POST /v1/events.

#4. Resolution

On the Standard and Enterprise plans, the service looks up each receipt among active, unexpired visits for your website. On Free it looks up nothing: receipts are discarded unread and the install is only counted. Every receipt found, with the earlier visits its revisits replaced, becomes a touch in the install's journey, oldest first. Your attribution policy picks the visit that gets the credit, and the install is recorded with one of these resolutions:

#5. Delivery

For each destination, the service prepares the platform's payload in the same transaction that records the install. Each platform takes its own identifiers from the journey in the direction of your attribution policy: the most recent click under latest visit, the earliest under first visit. Live destinations send it; test-mode destinations only show it. Install starts go to webhooks only. See How delivery works.

#When the terminal cannot see the browser

Receipts only work when the install runs as the same OS user, on the same computer, in a browser whose storage the hook can read. That rules out Safari's protected storage, a Windows browser with a CLI in WSL, remote agents, SSH sessions, containers and installs on another device. Two optional routes cover those cases:

• Handoff command. The page prepares an install command that carries an opaque token. Running it reports the token. Evidence: explicit_handoff.
• Reconstruction. On paid plans, on by default: an install without a receipt can match a recent visit from the same public network when other signals, such as the OS, time zone and language, agree. Always labelled probable.

An install that stays unattributed is labelled Safari or External, from what the hook reported about the machine, so you know which of these would have caught it.

#What a match means

A receipt proves that this computer's browser recorded a visit to your page. It does not prove that the install command was copied from that visit, or that the installation really happened. A handoff token proves that the command came from a prepared page, not who ran it. Shared OS accounts and several browser profiles can produce competing receipts; the attribution policy decides between them. CLItrail publishes no accuracy figure for production traffic.