Clavem

How to check for updates in a desktop app: version comparison, cadence and entitlement

An update check is a small request with four decisions in it: how to compare versions, how often to ask, how to tie the answer to a license, and what to do when the check fails. Comparing version strings with a plain numeric sort is the usual bug, because it ranks 4.0.0-beta.2 above 4.0.0.

Two jobs hiding in one feature

“Check for updates” is two jobs. The first is discovery: is a newer version out? The second is installation: download it, verify it and replace the running app. Frameworks give you the second job. The first is mostly your decision, and it is the place licensing meets updates, because a paid product usually gives new versions only to people who are entitled to them.

Choose the mechanism

Mechanism What it does What you provide
Sparkle (macOS) Checks an appcast, an RSS feed with extra fields, then downloads and installs An appcast and an EdDSA key. Sparkle’s generate_appcast tool builds the feed from a folder of archives
Electron autoUpdater Squirrel-based updates on macOS and Windows. On macOS the app must be signed A feed URL in the format Squirrel expects, set with setFeedURL
Tauri updater Checks endpoints, verifies a signature and installs Endpoints that answer 204 when there is no update, or 200 with JSON, and a signature on every bundle
Your own check Asks a releases endpoint and opens a download link A comparison, a prompt and an installer the user runs

Sparkle’s documentation recommends signing update archives with EdDSA (Ed25519) and keeping the signing keys off the machine that hosts the files, so that a compromised web server cannot push a bad update. Tauri says its signature check cannot be disabled. Electron’s documentation says an update on macOS requires a signed application. These are good reasons to use the framework’s installer for installation, and to ask your own endpoint only for entitlement and version information when licensing is involved.

Clavem’s releases endpoint is a discovery and download service. It returns its own JSON, not a Sparkle appcast, a Squirrel feed or a Tauri response, so with those frameworks use a small adapter you control, or use it as an entitlement check before you hand over a link.

Ask the endpoint

curl "https://clavem.io/v1/releases/75/latest?platform=macos" \
  -H "X-License-Key: YOUR-LICENSE-KEY"

The response, as documented:

{
  "version": "3.2.1",
  "notes": "Fixes a crash when importing large files.",
  "published_at": "2026-11-19T08:30:00.000Z",
  "files": [
    { "id": 12, "filename": "Inkwell-3.2.1.dmg", "size": 50540748, "platform": "macos", "url": "https://clavem.io/d/12?exp=1795050000&sig=..." }
  ]
}

Behaviors worth knowing, each checked against the live service or its documentation:

  • No release yet. The demo product has none published, and the endpoint answers HTTP 404 with {"error":{"code":"not_found","message":"This product has no published release yet."}}. Treat 404 as “no update”, not as an error.
  • No key. Without a license key, the response carries version and published_at but no notes or files. The app can say a version exists without handing it out.
  • Browser and extension calls. A preflight request from another origin returned HTTP 204, allowing the header X-License-Key and the methods GET and OPTIONS.
  • Separate rate limit. The endpoint allows 120 requests per 60 seconds per IP address, counted apart from the License API, so update checks do not use up your validation budget.
  • Download links expire. The url is signed and works for one hour. Request a fresh one when the user clicks, not when the app starts.

Latest means most recently published

“Latest” is the release published most recently, not the highest version number. If you publish 3.3.0 and then a backport 3.2.4, the backport becomes the latest. A customer on 3.2.3 is offered 3.2.4 and never hears of 3.3.0, and a customer on 3.3.0 sees no update at all. If you ship from several branches, publish in version order, or keep branches in separate products. To pull a bad build, unpublish it, and the previously published release becomes the latest again.

Compare versions correctly

The docs’ sample uses localeCompare with numeric sorting. It handles 3.10.0 against 3.9.0, but it has a bug with pre-releases. I ran both approaches on the same pairs:

Left Right Numeric string sort says Semantic versioning says
3.10.0 3.9.0 newer newer
4.0.0-beta.2 4.0.0 newer (wrong) older
4.0.0-beta.10 4.0.0-beta.2 newer newer
4.0.0-rc.1 4.0.0-beta.9 newer newer
2026.11 2026.9 newer not a semantic version

The second row is the dangerous one. A customer on the beta would never be offered the final release, and a customer on the final release could be offered the beta. Compare the three core numbers first, then pre-release identifiers, with a release outranking its own pre-releases. Return nothing, not a guess, for strings you cannot parse. The function I used:

function parse(v) {
  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim());
  return m ? { core: [+m[1], +m[2], +m[3]], pre: m[4] ? m[4].split('.') : [] } : null;
}
export function compare(a, b) {
  const x = parse(a), y = parse(b);
  if (!x || !y) return null;
  for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i];
  if (!x.pre.length || !y.pre.length) return y.pre.length - x.pre.length;
  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
    const p = x.pre[i], q = y.pre[i];
    if (p === undefined) return -1;
    if (q === undefined) return 1;
    const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
    if (pn && qn) { if (+p !== +q) return +p - +q; }
    else if (pn !== qn) return pn ? -1 : 1;
    else if (p !== q) return p < q ? -1 : 1;
  }
  return 0;
}

Clavem accepts versions of up to 64 characters made of letters, digits, dots, dashes, plus signs and underscores, so a calendar version such as 2026.11 is possible. If you use one, write a comparison for your own format. Do not mix formats across releases.

Cadence and failure behavior

Decision Recommendation
When to check At launch if the last check is over a day old, then about daily
Blocking Never. Run it in the background and let the app start
Timeout A few seconds. An update check is not worth a frozen window
Failure Stay silent, try again at the next interval
Jitter Add a random offset so a million launches do not align on the hour
Frequency cap Remember the version you last told the user about

The jitter and the cap are cheap and prevent most annoyance. The cap belongs in the update prompts article.

Entitlement: who gets the file

With a valid license key, the response includes files and notes. With no key, or a key that is not valid for the product, it reports the version and the date only. So the app can tell the difference between “up to date” and “an update exists, and this license cannot download it”.

Some products promise “updates for one year” with a license that never expires. Clavem’s expiry model is a single date, so the simplest way to do this is in the app: read the created_at of the license from a validate response and the published_at of the release, and offer the download only if the release was published within your window. I ran this rule with dates, and it correctly allowed a June 2027 release and refused a December 2027 one for a license created in November 2026. The rule lives in your app, so state it in your terms.

Doing this with Clavem

Clavem stores your release files, gives each a signed download link and serves the endpoint described above, with no bandwidth fee. See the releases documentation for the upload limits and the full response. The installation step stays with your framework: Sparkle, Squirrel or the Tauri updater.

Questions

How often should a desktop app check for updates?

At launch if the last check was more than a day ago, and then about once a day while the app stays open. Do not block startup on the answer, set a short timeout of a few seconds, and stay quiet when the check fails.

Why does my app think a beta is newer than the final release?

A numeric string sort treats 4.0.0-beta.2 as greater than 4.0.0. Under semantic versioning a pre-release is older than its release. Parse the version and compare the core numbers first, then the pre-release parts.

Should the license key go in the update URL?

No. Send it in a request header so it stays out of server logs, referrer headers and shared screenshots. Clavem's releases endpoint reads the X-License-Key header.

Sources

  1. Sparkle documentation, appcasts and EdDSA signatures (as of November 2026)
  2. Electron autoUpdater API (as of November 2026)
  3. Tauri v2 updater plugin (as of November 2026)