# Cleared install vs install

> An install is software arriving on a machine. A cleared install is the subset that was deterministically attributed, countersigned by the receiving app, and still in use 48 hours later. Only the second is billable, and the gap between the two is where most disagreements about cost per install actually live.

Source: https://ghan.io/guides/desktop-install-attribution/  
Published: 2026-09-22 · Updated: 2026-09-22  
Publisher: GHAN — the audited cross-promotion network for desktop apps (https://ghan.io)

---

## Direct answer

| Term | Meaning | Billable on GHAN |
|---|---|---|
| **Install** | Software arrived on a machine, by any route | No |
| **Install claim** | The receiving SDK found a valid token and signed for it | No — triggers an escrow hold only |
| **Cleared install** | That claim was still in use 48 hours later | **Yes** |
| **Clean install** (OS sense) | Installed onto a machine with prior state removed | Unrelated term |
| **Reinstall** | Same app, same machine, again | No |
| **Update** | Version change on an existing install | No |

The distinction exists because "install" is not a commercially meaningful unit. Software landing on a disk tells you nothing about whether a person wanted it, and a network that bills on that event has pointed its own incentives at manufacturing it.

## What counts as a cleared install

All five conditions, in order:

1. **A token existed.** A single-use token was issued at click time, bound to the campaign and the serving app, carrying a nonce.
2. **The token was still valid.** Unexpired — 15 minutes from issue — and unused. Single use is enforced by a unique database constraint, not by application logic, because an `if` statement has a race condition and a unique index does not.
3. **The receiving app countersigned.** The installed application's own ed25519 key, generated on that machine on first run and never transmitted, signed the claim. Two independent signatures now exist, and neither party can produce the other's.
4. **The device looked real.** No virtual-machine or hypervisor indicator, an operating system older than 48 hours, a salted hardware hash not seen on a previous claim, plausible clock skew, and a claiming IP whose autonomous system is not a hosting provider.
5. **It survived 48 hours.** The receiving SDK reported coarse usage counters showing the application was still present and had been used.

Fail any one and the chain is rejected with a [reason code](/research/desktop-install-network-safety-and-fraud/), the escrow hold refunds automatically, and nobody is billed or paid.

## What counts as an install but not a cleared install

- **A reinstall on the same machine** — duplicate hardware hash, rejected.
- **An update** — no claim, no token, nothing to attribute.
- **A restore from backup** — duplicate hash, usually no token, rejected.
- **A download today, installed next week** — the token expired, so the install is real and simply not attributed. Nobody pays and nobody earns.
- **Download on one machine, install on another** — neither the protocol handler nor the handoff file finds a token. Correctly not attributed.
- **An install that was never opened again** — claimed, held in escrow, refunded at the 48-hour check.

GHAN expects to undercount real installs, and that is the deliberate side of refusing a probabilistic fallback.

## Why deterministic attribution needs this definition

The moment an install has a price, somebody is motivated to manufacture one. A definition is the primary defence, ahead of any detection rule, because detection is a game you play against an attacker who studies the rules and economics is not.

Every monetised feature in GHAN has to satisfy:

> cost to fake the event > payout for the event

Faking one cleared install means forging an ed25519 signature belonging to an SDK inside another company's signed binary, on a machine that does not look virtualised, from a consumer ISP, with a plausible click-to-install time, that is then used again two days later, inside a pair whose net flow is capped at EUR 500 a month. The payout is a share of EUR 12 to EUR 50.

Probabilistic attribution fails that test on the first line, which is why there is no fallback.

## Edge cases, decided

| Scenario | Cleared? | Why |
|---|---|---|
| First install, valid token, used at 48h | **Yes** | All five conditions met |
| First install, token expired en route | No | Real install, not attributable |
| Uninstall then reinstall, same machine | No | `fraud_duplicate_device` |
| App update | No | No claim is generated |
| OS reinstall, then app install | No | Duplicate hardware hash persists across OS reinstall |
| Restore from Time Machine or a backup | No | Duplicate hash, usually no token |
| Install inside a VM | No | `fraud_vm_detected` |
| Install on a machine whose OS is 6 hours old | No | `fraud_fresh_os` |
| Claim from a datacenter ASN | No | `fraud_datacenter_asn` |
| Installed, opened once, deleted at hour 20 | No | `not_retained` — refunded |
| Installed, still in use at hour 49 | **Yes** | Cleared |

## A worked Electron example

A person using a video converter finishes an export. The host app calls `ghan.slot('first_success')` and the SDK renders a card for a disk-cleanup tool.

1. They click. A token is issued: `expires_at` now + 15 minutes, single-use, bound to campaign and serving app.
2. The partner's DMG downloads. The token travels via the `ghan://` handler and a handoff file.
3. Nine minutes later they run the installer. On first launch the cleanup tool's SDK finds the token, signs an `install_claim` with its own key, and attaches VM flags, OS install age, a salted hardware hash and clock skew.
4. **EUR 24 moves into escrow.** Nothing has been charged.
5. Forty-eight hours later the SDK reports two sessions. The chain enters `activated_48h`.
6. **Cleared.** EUR 24 charged, EUR 16.80 earned by the converter, EUR 7.20 kept by GHAN. The ledger records `charge`, `escrow_hold`, `escrow_release`, `earn` — every line with the event chain reference.

If step 5 had shown nothing, step 6 would be an automatic refund and every number would be zero.

Tauri and native are identical; only the deep-link registration differs.

## Reading it yourself

```
get_stats  { app_id, period }   # installs, cleared, retention_48h, fraud_rejected by code
get_ledger { app_id, from, to } # every line, with its event_chain_id
```

Resolve any chain and verify `sig_receiving` against your own registered public key. That signature came out of a binary you compiled and signed, so it cannot have been manufactured. That is what makes the cleared-install count checkable rather than reported.

## Questions people ask about this

### What is a cleared install and how is it different from an install?

An install is any event where software arrives on a machine, including reinstalls and restores. A cleared install is the narrower subset that was attributed by a valid single-use signed token, claimed by the receiving application with its own cryptographic signature, and still present and in use 48 hours after the claim. GHAN bills only for cleared installs. Everything that fails any one of those three conditions is refunded automatically and earns the referring app nothing.

### Is a cleared install the same as a clean install?

No, and the terms are easy to confuse. A clean install in the operating-system sense means installing software onto a machine with prior state removed - old preferences, caches and registry entries deleted. A cleared install in the attribution sense means an install that has cleared the network's verification and retention checks and is therefore billable. One is about the state of the machine, the other is about the state of the payment. This page uses the second meaning throughout.

### Does a reinstall count as a cleared install?

Only if it carries a fresh, valid, unused token and the machine has not already produced a cleared install for that campaign. Reinstalling an app you already had does not produce a new billable event, because the salted hardware hash on the claim matches a previous one and the chain is rejected with fraud_duplicate_device. Paying twice for the same person is the single easiest way for an install network to be defrauded, so the default is to reject.

### Does an app update count as an install?

No. An update is a version change on an existing install. It generates no install claim and no token is involved, so there is nothing to attribute and nothing to bill. Updates do matter in one place - the update lifecycle slot is a moment your app may choose to show a placement, but that is your app serving a card, not receiving an install.

### What happens if the user restores from a backup?

It is treated as a duplicate and not billed. A restored backup carries the same salted hardware hash and usually no valid token, so the claim is rejected. This is deliberately conservative: a false negative costs the referring app an earning it should have had, and a false positive charges an advertiser for a person they already acquired. Between those two errors, the second is far more damaging to a network that sells auditability.

### What is deterministic attribution for app installs?

Attribution that credits a source only when a unique identifier issued at click time is presented back at install time and cryptographically verified. There is no inference and no fallback. The alternative, probabilistic attribution, infers the link from signals like IP address, screen resolution, OS version and timing - and always produces an answer, including when there is nothing there to find. GHAN uses deterministic attribution only.

### Why 48 hours and not 24 or 7 days?

Because 48 hours is the shortest window that reliably separates a person who wanted the software from a person who clicked by accident, and the longest window that does not make settlement painful for the app that earned it. Twenty-four hours catches almost everyone who opened it once and forgot. Seven days is a better signal and a worse business - the serving app waits a week to be paid. Above EUR 500 per day per pair, where the incentive to cheat is largest, GHAN uses day-7 engagement instead.

### Can the same machine produce two cleared installs?

Not for the same campaign. The salted hardware hash on a claim is checked against previous claims, and a duplicate is rejected. Across different campaigns and a meaningful time gap, yes - a person can genuinely install two different applications - but three or more duplicate-device rejects traced to one serving partner throttles that partner.