What changes from 3.x
What an app, a developer and a learner notice when an app moves from SDK 3.x to 4.0, in every SDK and platform by platform.
The calls of 3.x stay: TajweedClient, client.model(), model.listen() or model.session(), and chunk.decoded. Your key, your app's page, its model version and its response time stay as they are. This page lists what an app, a developer or a learner may notice.
When to move
- SDK 3.x stops receiving the V4 model on 15 January 2027, 00:00 UTC. Move your app to SDK 4.0 before then.
- New model versions are for SDK 4.0 only. From V4.1 on, a new model version ships only encrypted, for SDK 4.0: an app on 3.x never gets it.
In every SDK
| 3.x | 4.0 | |
|---|---|---|
| The model on the device | Plain files that the SDK verified | Encrypted for this install. Only the Core opens it, in its own memory. The calibration and the sample clips stay plain: they are data your app may read. |
| Without a connection | Ran once downloaded | Runs while the install's lease is valid: learners can use the model offline for days at a time (the exact time is set by Quran Lab and may change), and up to 24 hours more while Quran Lab cannot be reached. Offline use and the lease |
The first client.model() |
Downloaded and opened the model | Also makes the install's keys and gets a certificate and a lease from Quran Lab, so it needs a connection and takes longer the first time only. |
| Anonymous analytics | An analytics option in the app's code |
Always on, with no option: daily counts and durations only, never audio, text, names or device identifiers. Only Quran Lab can pause them, for every app at once. |
| Error codes | The catalogue of 3.x | The same codes, each with one meaning: needs_connection only when Quran Lab gave no answer at all, download_failed when a server answered with a failure. Errors in 4.0 |
| Error reports | Some failures, as issues (the newest 3.x patches report every one) | Every failure a learner hits is reported, with no identifier, and shown on your app's Problems tab. The Problems page |
| Recited ayahs | Reported by the app with session.reportRecited |
The SDK places each take in the Quran and counts the ayahs itself. session.reportRecited stays, for a take it could not place, and can carry your app's own judgement of the range. A take is never counted twice. |
| Asking to share | After "Not now", the sheet again at least 7 sessions later | Later and less often. The first ask never comes in the 24 hours after the install or the update, never before the learner's third completed session, and only at the end of a good session. A re-ask is a small card that blocks nothing: after 14 days and 7 sessions, then after 30 days and 10. Three asks at most, as before, and a yes is never asked again. |
Remove the analytics option wherever your code sets it. In Kotlin, Swift, TypeScript and C, code that sets it does not build against 4.0. On the web, plain JavaScript that still passes it is refused: create() fails with invalid_argument, whose message names the option, says it was removed because the anonymous analytics are always on, and points to the SDK's migration guide. The fix is to delete it.
4.0 also removed the audience option of 3.x: every app shows the same sharing sheet, under the same rules, and there is no other version of the sheet. Remove audience wherever your code sets it. Code that sets it does not build against 4.0, and on the web a page that still passes it is refused with invalid_argument, as for analytics.
client.sharing.ask() keeps your app's moment, under the same rules: it shows nothing when no ask is due. An app that asked at its first launch no longer can.
What stays as it was
- Sharing is the learner's choice. The SDK asks every learner itself, and each learner chooses: "Not now", the settings switch and "Delete what I shared" are theirs at any time. There is no option for it in your code or in the portal. Recording sharing
- The SDK hears and reports what it heard. Your app builds its own feedback on the output. Build your own feedback
- The notice is optional. Quran Lab recommends a line such as "Automatic tajweed feedback can be wrong. It does not replace a qualified teacher." where your app shows feedback. It is never required, and it is not a condition of the licence.
- 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, as in 3.x. In 4.0 a stop that answers a lease request is signed by Quran Lab, and the Core checks the signature before anything is removed.
Web
- One script from Quran Lab. A page includes the hosted loader, which opens a small hidden frame of Quran Lab's on the page. The engine, the model and its lease live in that frame's Worker, on Quran Lab's origin: your page's scripts, other scripts and extensions limited to your site cannot read them. The npm package of 4.x is a thin wrapper that loads the same loader. The model never comes through the package.
- Engine updates without a release of your site. The loader runs the engine build Quran Lab's signed config names for your site, after checking its signature and every file's hash.
- Two hosts. The loader and the frame come from
web.quranlab.aiand, as a fallback, fromweb2.quranlab.ai. When the first host's frame has not answered within 4 seconds, the loader opens the same frame on the second. - Content-Security-Policy. If your site sends one, add the lines on the web quick start; they name both hosts.
- The lease is kept across page loads. It stays in the frame's storage for your site, so a page loaded again within it opens the model with no connection, as a cached model did in 3.x; learners can use the model offline for days at a time (the exact time is set by Quran Lab and may change).
- An invisible check. The first lease of a page session passes a bot check inside Quran Lab's frame. A learner never sees a box or ticks anything, and a check that gives no clear answer never refuses the learner.
- Microphone. Capture stays in your page, with your page's one permission prompt.
- Threads. One thread by default. The threads engine runs only in a cross-origin isolated page that asks for it.
- Node. The npm package's Node entry runs the same API in Node 20 or later, with a desktop key and its app id, in a worker thread and with no frame. Its leases are kept in the SDK's storage folder across runs, as long as Quran Lab sets them, with the same 24 hours more while Quran Lab cannot be reached. There is no recitation sharing in Node.
Android
- Change the version. Most apps change nothing else in their code.
- Remove the
analyticsandaudiencearguments ofTajweedClientOptionsif you set them. - Keep
minSdkat 26 or above, the SDK's own. - Leave the Core as it is.
libqlcore.soships in the AAR. Android's own build may strip native libraries, and that is fine; do not change it in any other way. The Core checks its own code, and a changed Core gets no lease. - The first
client.model()makes the install's keys in the Android Keystore and attests them, so it takes longer that first time. - Add your signing certificates on the Android key's page, under "Signing certificates (SHA-256)": the app signing key certificate and the upload key certificate. Until you do, your installs are not hardware-verified for your app: they run on the CPU, and a re-signed copy of your app is not told apart from yours.
- Testing on a cloud device lab. Some labs sign your APK again, so its signing digest differs from yours. Add the lab's signing digest to a development key, never to the production one.
- An unlocked bootloader. A phone with an unlocked bootloader is refused a lease, by design. The error says which check failed.
- The CPU engine on every phone. At 4.0's launch every phone runs the Core's CPU engine; there is no NPU acceleration on Android. NPU support returns when a faster build ships. Add nothing to your app for it.
- Wi-Fi only.
TajweedClientOptions(unmeteredOnly = true)makes the SDK's own background downloads wait for Wi-Fi or Ethernet.client.model()andclient.prefetch()keep their own argument. - A Client made late (Flutter does it) now finds the activity in front, so the sharing sheet can show and
listen()asks for the microphone.
Windows and Linux
- Remove
TfClientOptions.analyticsandTfClientOptions.audienceif you set them. - Ship the Core beside your app. The library needs the Core's binary for its target, published by Quran Lab with each release:
qlcore.dllandlibwinpthread-1.dllon Windows,qlcore.soon Linux. Point CMake at its folder when you build. - Desktop leases. A desktop install is not attested, so its leases are of the standard class, which runs on the CPU; learners can use the model offline for days at a time (the exact time is set by Quran Lab and may change). The install's keys are kept in the TPM on Windows when there is one, else in Windows' own key store for the signed-in account; on Linux in a key file sealed to the machine and the account.
- The CPU engine. Windows and Linux run the Core's CPU engine. There is no GPU build in 4.0.
iOS and macOS
- Change the version. Most apps change nothing else in their code.
- Remove the
analyticsandaudienceparameters ofTajweedClientOptionsif you set them; code that sets them no longer compiles.client.sharing.setOn(_:)takes the learner's switch alone. - Leave the Core as it is.
QuranLabCore.xcframeworkcomes with the package, fetched and checked by SwiftPM. Beyond Xcode's own signing, do not change it: the Core checks its own code, and a changed Core gets no lease. - The model downloads when your app asks for it. Making the Client downloads nothing: the model downloads at the first
client.model()orclient.prefetch(), and once more after the upgrade. In 3.x a launch could download it before your app asked. - Add the App Attest capability. With it, an install on a production key is hardware-verified: it may use the Neural Engine, and its shared recordings upload. Without it the SDK runs on the CPU and is never locked out.
- The Simulator needs a development key. Quran Lab leases the Core's Simulator build to development keys only.
- Privacy manifests now also declare crash data and the boot clock, which the lease reads. Check your App Store privacy answers against them.
The Apple quick start has the install line.
Flutter
The plugin quranlab_tajweedformer 4.0 is on pub.dev, over the Android and Apple SDKs 4.0: flutter pub add quranlab_tajweedformer. What changes for each platform underneath is what is above. Flutter