Offline use and the lease
How an app runs the model without a connection in SDK 4.0, how the lease is renewed, and what happens when Quran Lab cannot be reached.
In SDK 4.0 the model opens only with a lease: a permission that Quran Lab signs for one install, one build of the model and one release of the Core. While the lease is valid, the model opens with no connection at all. The SDK renews the lease in the background whenever the device is online, so a learner who goes online now and then never sees it.
How long a lease lasts
Learners can use the model offline for days at a time. The exact time is set by Quran Lab and may change; your app needs no code for it, and every install gets it, attested or not. Each install's lease ends at a time of its own, so the leases of many learners never end at the same hour.
What attestation gives
| The install | Its class |
|---|---|
| A phone app on a production key whose install Quran Lab could attest: App Attest on Apple; on Android the phone's hardware key check, or Google Play Integrity on a phone without one | Hardware-verified: it may use the device's accelerator, such as the Neural Engine on an iPhone |
| Every other install: one that could not be attested, a development key, a web page, a Windows or Linux app, a Node app | Standard: it runs on the CPU, never locked out |
diagnose() names the class: attested or standard.
Renewing it
- The SDK asks for a new lease in the background at the first app start or model open once a renewal is due, about once a day while the device is online: from about 20 hours after a hardware-verified install's lease was given, and from about 12 hours after any other. So a block, a revoked key or a new model reaches an online learner within about a day.
- A renewal that fails is tried again after 1, 5 and 30 minutes, then every 2 hours, and at most every 6 hours after that.
- A valid lease never waits for a renewal: the model opens at once.
On the web the lease is kept across page loads, in the storage of Quran Lab's frame for your site, with the install's keys as WebCrypto keys the browser never lets out. A page loaded again within the lease opens the model with no connection. The model's files stay in the browser's storage, encrypted, so a new page load downloads nothing again. The first lease of a page session also passes an invisible bot check in the frame: a learner never sees it, and a check that gives no clear answer never refuses the learner. A Node app keeps its lease in the SDK's storage folder across runs.
Without a connection
- The first run needs a connection. The model is downloaded, the install makes its keys, and Quran Lab gives it a certificate and its first lease.
- After that the model opens offline while the lease is valid.
- A model already open keeps running until the app closes it, also past the end of its lease.
- Once the lease has ended, the next
client.model()needs Quran Lab. With no answer at all it fails withneeds_connection, unless the grace below applies. The model stays on the device, encrypted: once a new lease comes, nothing is downloaded again.
When your app gets needs_connection, ask the learner to connect to the internet, then call client.model() again.
When Quran Lab cannot be reached
A learner is not stopped because Quran Lab's servers are down. When a lease has ended and Quran Lab cannot be reached (no answer, a server error, or a "too many requests" answer), the model opens under that lease for up to 24 hours more.
- Never after a refusal. When Quran Lab answers that the key, the app or the install is refused, there is no grace, and a refusal that comes during the grace ends it at once: the next open needs a new lease.
- On the web too, for a page left open past its lease and for a page loaded later.
- One grace per lease, counted from the lease's own end. Attempts during the grace never lengthen it, so an install opens the model at most 24 hours past the end of its last lease.
- At most 10 seconds of waiting. Past the end of a lease, opening the model first tries for a new one and waits at most 10 seconds for an answer. A device that is offline does not wait.
- Reported. Each open in the grace is reported to Quran Lab without telling your app, and shows on your app's Problems tab as a problem of the model key.
The device clock
A device clock that is wrong, or that the learner moves, never lengthens a lease and never locks a learner out for long. The Core judges the lease by its own clock, which it sets from Quran Lab's time in each lease.
A refused key or app
When Quran Lab refuses the key or the app, the SDK stops running the model and removes it from the device, whatever lease it holds. A model already open keeps running until the app closes it. Once the key is accepted again, the model is downloaded again.
On Windows and Linux, tf_client_diagnose_json says whether the install holds a valid lease and until when.