License heartbeats and offline verification
Both settings belong to Licensing policies but answer different questions: how often to contact the server online, and how long use can continue without reaching it.
Heartbeat interval: how often to validate
Set Heartbeat interval (seconds) to 600, the SDK sends a heartbeat roughly every 10 minutes while running. Each success retrieves the latest rules and refreshes the local license cache.
Enter 600–86400 seconds. Enter 0 disables scheduled heartbeats. Your application can still verify or refresh manually. Scheduling adds 0–10% random delay; the interval never falls below 600 seconds.
For a device-bound license with a valid cache, startup restores access and refreshes online in the background, even with the timer disabled. Online-only and floating licenses wait for server confirmation.
Offline allowance: how long to run without the server
Offline mode has three choices. It does not change the heartbeat interval.
- Allow for a specified duration
- For a 24-hour allowance, the signed cache lasts at most 24 hours from the last successful online check. The app can work through a disconnection or temporary server outage within that time. Afterward, online validation must succeed.
- Offline fallback not allowed
- Startup must reach the server successfully; disk caches cannot bypass a failed request. A short-lived signature obtained while running lasts at most
max(10, 心跳间隔)seconds; the app must keep validating and checking feature permissions. - Allow permanent offline access
- An existing local signature can be used long term, including during network failures. A 30-day license still expires after 30 days; permanent offline use does not make a timed license perpetual.
The API uses offline_mode represents these three choices, respectively limited, none, permanent. With a fixed offline allowance,offline_seconds is 1–31536000 seconds; use 0 for the other two modes.
How do these combinations behave?
| Heartbeat / offline settings | Actual behavior |
|---|---|
| 10 minutes / 24 hours | Validate every 10 minutes online. Offline, continue for at most 24 hours after the last successful check |
| 10 minutes / permanent offline | Still tries a heartbeat every 10 minutes, updates rules on success and uses a valid signature when unreachable. |
| 0 / permanent offline | With a valid cache, startup needs no scheduled requests. Explicit validation or refresh still contacts the server |
| 0 / 24 hours | No scheduled heartbeats, but cache still expires. The app must schedule validation; disabling heartbeats does not extend offline allowance. |
Keep the offline allowance longer than the heartbeat interval. With hourly heartbeats but only 1 minute offline, the signature expires before the next heartbeat; the app must validate separately.
Do policy changes update existing licenses?
Yes. Saving a policy atomically syncs device or seat limits, features, usage limits, license model, maintenance and version bounds to every linked, non-revoked license. You no longer select each one and apply the policy again.
Sync preserves each license’s term type, valid days, first activation, expiry, customer, used units and separate maintenance extension. The policy term type affects only future licenses; it never turns an existing 30-day license into a perpetual one.
If active devices or sessions remain while switching between device-bound and floating licensing, or the new limit is below current use, saving returns ACTIVE_DEVICES_CONFLICT, and neither the policy nor any linked license is partially updated. Release the conflicting devices and save again.
After a successful save, linked old and new licenses use the new rules on their next successful activation, validation or heartbeat. The SDK replaces its cache with the new signature. Retrying the same Idempotency-Key still returns the original request result.
An offline device keeps using its existing signed rules. Reconnecting alone does not update its cache; a request must succeed. Your app can refresh actively when connectivity returns.
To move selected licenses to another policy, select them on the Licenses page and preview the move with Apply policy. When editing their current linked policy, simply save to sync automatically.
Explicit online refresh
These methods always try the server, even with permanent offline use and heartbeats disabled. Success updates the signature. Network failure reports a refresh error but keeps an otherwise valid cache. Explicit revocation or release clears it.
| Language | How to call |
|---|---|
| Go | client.RefreshOnline(ctx) |
| Java | client.refreshOnline() |
| C | ln_refresh_online(client) |
| C++ | client.RefreshOnline() |
| C# | await client.RefreshOnline() |
| Python | client.refresh_online() |
| JavaScript | await client.refreshOnline() |
A successful refresh counts as one activation API request. If a policy change enables previously disabled heartbeats, call your language's StartHeartbeat to start scheduling. Offline devices cannot receive revocation or release updates.