Activating a license

When the state is MISSING_KEY, or the app is locked for a reason the customer fixes with another key, show an activation screen. When the customer submits their key, pass it to setLicenseKey:

import { LicenseError } from "@licenseman/electron";
 
try {
  await license.setLicenseKey(input);
  // The state is now ACTIVE: unlock the app.
} catch (error) {
  if (error instanceof LicenseError) showError(error.code);
  else throw error;
}

What setLicenseKey does

On any failure, including the network, it throws a LicenseError, and changes nothing: the stored key, the stored token and the current state stay as they were. A customer whose app is ACTIVE and who types a wrong key keeps their working license.

The errors

Branch on error.code, never on error.message, which may change.

The first four are the locking codes: error.isLocking is true for them. They say something about the customer’s license, and the customer needs to do something: another key, a renewal, another version, a free machine. The others say nothing about the license: the customer can try the same key again later.

See handling validation errors for each server error in detail.

invalid_response

The server answered, but its token didn’t pass verification. In practice, it means one of:

• The computer’s clock is wrong. More than 2 hours behind, the token isn’t valid yet; ahead by more than its lifetime, it’s already expired. Ask the customer to set their date and time automatically.
• The public key doesn’t match, like the key of another organization pasted in your code. Every activation fails: you’ll notice it while testing.
• The product id doesn’t match the product the token is for.

error.status holds the HTTP status, 200.

The LicenseError

Replacing a key

setLicenseKey works in every state, not only MISSING_KEY. Use it when the customer:

• enters a new key after their license was refused, in INVALID_KEY, EXPIRED or MACHINE_LIMIT_REACHED,
• upgrades to another license, like from a Personal to a Pro license,
• buys a license after a trial license.

On success, the new key and its token replace the old ones. The computer stays an active machine of the old license on LicenseManager’s side, and keeps one of its places until you or the customer deactivate it.

The SDK has no method to remove the stored key or deactivate the machine. To sign the customer out, see a new computer.

Edge cases

The customer submits twice. Two calls with the same key while the first one runs share one request: both resolve, or both throw, with the same result.

A key entered while the startup validation still runs. The startup validation’s result is ignored once it comes back: only the new key counts. Simpler: wait for ready() before showing the activation screen.

A key in lower case. It’s sent as typed, so 7kq2m-… answers not_found when the key is 7KQ2M-…. Generated keys only use upper case letters and digits: if all your keys are generated, upper-case what the customer typed before passing it.

A key with spaces in the middle, like one copied across two lines. Only the spaces around it are removed: clean it up before passing it if your keys never contain spaces.

A custom fingerprint function that throws, or a missing version outside Electron. setLicenseKey rejects with that error as is, not a LicenseError: don’t assume every error is one.

Activating offline. It’s impossible: the first activation always needs LicenseManager. It throws network_error, after 30 seconds of retries.