Skip to main content

Aila SDK — Licensing Transition Guide

Upgrading to Aila SDK v3.3 (iOS / iPadOS Swift SDK)

Contents​

  1. What's changing in 3.3
  2. Before you upgrade
  3. Cloud licensing (the default)
  4. Optional: Configuration Key
  5. Verifying your licensing state
  6. What happens without valid licensing
  7. Migration checklist
  8. API quick reference

1. What's changing in 3.3​

Through SDK 3.2, the Aila SDK did not require any special licensing. Most users could use the mainline version from the developer portal, or Aila supplied a custom-compiled version with additional entitlements and contractual obligations built in. Starting with 3.3, licensing is handled by the SDK itself.

Cloud licensing is on by default. On init, the SDK reaches Aila's cloud, retrieves the entitlements registered for your app's bundle ID, and refreshes them as they change. There is no new call to add and no code change to your SDK integration.

The entitlements themselves are carried in a Configuration Key, the licensing string generated for your organization's configuration. With cloud licensing you never have to handle it directly; the SDK fetches and applies it for you. If your app also needs to run without connectivity, you can retrieve the Configuration Key from the portal and add it to your app or MDM payload. That path is optional and covered in Section 4.

This guide covers what to check before you upgrade, how to confirm licensing applied, and a working reference based on the AilaDemo sample app bundled with the SDK.

2. Before you upgrade​

  1. Watch for your portal invitation. Your organization and configuration are created for you ahead of the migration. You will receive an invitation to your organization, which is where you review bundle IDs, entitlements, and expirations.
  2. Check your registered bundle IDs. Licensing is keyed to bundle IDs. If you're an Aila SDK user before September 2026, we have done our best to capture all known bundle IDs for your organization, but unknown testing or developer bundles may not have been added. Any missing bundle ID needs to be added to your configuration in the Developer Portal, or the SDK will have no entitlements to apply for that build.
  3. Update the frameworks. Replace Aila.xcframework and AilaDecoder.xcframework with the 3.3 builds (Embed & Sign).
  4. Decide whether you need offline coverage. Most integrations do not — leave the default alone. If your devices spend time without a network path to Aila's service, plan for the optional Configuration Key in Section 4.

Adding or editing a bundle ID generates a new Configuration Key. With cloud licensing this is handled for you. The SDK picks up the newer key on its next check. If you have also embedded a Configuration Key in your app, that copy becomes outdated and should be refreshed when convenient (see Section 4).

3. Cloud licensing (the default)​

Cloud licensing is controlled by the cloudLicensing property on AilaConfiguration, which defaults to .on in 3.3. A standard integration keeps its existing startup sequence exactly as it is:

Aila_Init()
Aila_SetConfiguration(config)
// No licensing call needed — cloud licensing is already on

What you need in place:

  • Ensure every bundle ID that will utilize this license is registered in the Developer Portal (see Section 2).
  • Network access from the device to Aila's licensing service.

Because entitlements are resolved in the cloud, changes made in the portal (eg, Aila extends your license or grants additional features/entitlements) are applied to your app on its next check.

Note: When cloud licensing is on, the SDK will fetch a newer Configuration Key that supersedes the one currently applied. You can watch for those changes via the AilaSetLicense notification (see Section 5).

Advanced cloud licensing behavior, including calling a license profile for apps with the same bundleID but require different entitlements, is documented in the Aila SDK API Manual. You do not need any of it for a standard migration.

4. Optional: Configuration Key​

If your app needs to be licensed before it has a network path to Aila's service, you can supply the Configuration Key to the SDK directly. The Configuration Key contains the same feature entitlements and expiration as the cloud license. The SDK will read and apply it immediately at startup, with no network round trip.

1. Get the Configuration Key from the portal. Open your organization in the Developer Portal, select the configuration for your app, and copy the Configuration Key.

Standard Users cannot view or copy Configuration Keys. You need an Org Admin or Developer role to retrieve one.

2. Read it at startup. The function signature (from the API manual) is:

void Aila_ReadLicense(NSString *license);

Recommended call order — initialize, configure, then read the Configuration Key:

Aila_Init()
Aila_SetConfiguration(config)
Aila_ReadLicense("<configuration key>")   // Optional baseline

Why this order: Aila_ReadLicense applies the entitlements that govern your configuration (for example, advanced symbologies or driver's-license parsing). Reading the Configuration Key after Aila_SetConfiguration ensures the configuration you just set is evaluated against fully applied entitlements. The Configuration Key can also be re-read at any time after Aila_Init() to swap or renew it without restarting.

How a Configuration Key and cloud licensing work together​

The two are not mutually exclusive, and you do not have to choose. Reading a Configuration Key while leaving cloud licensing on is the expected setup for offline-capable apps, and it is the arrangement this section assumes.

The SDK applies the local Configuration Key first, so the app is licensed from launch whether or not it has a network. When connectivity is available, it checks the cloud as well.

The newest Configuration Key always wins. Version and dates determine which one applies, irrespective of where it came from.

In practice:

  • Initially the two match. The key you copy from the portal and the one in the cloud are the same version with the same dates, so nothing changes at startup.
  • When something changes in the portal — a feature is enabled, an expiration is extended — the cloud generates a new Configuration Key. The SDK sees the newer version on its next check and updates itself automatically. No app update is required.
  • Your embedded copy becomes outdated, not broken. It stays a valid baseline; the cloud simply supersedes it. Refresh it when convenient — ship the new value in an app update if it is embedded in code, or push it via MDM if you read it from AppConfig.

An app that never reaches the cloud will keep using the Configuration Key it was given, so for those deployments plan a way to update it: an app update or an MDM push.

5. Verifying your licensing state​

Confirm your entitlements applied using these tools.

Inspect current state​

Aila_GetSDKLicensingInfo() returns a JSON snapshot of the SDK's licensing state (or nil on error). Dates are ISO-8601 UTC. Useful fields include currentConfiguration (e.g. "Kiosk" or "SoftScan") and per-feature enabled/expires entries for parsing, symbologies, and MRZ.

React to licensing changes​

The SDK posts AilaSetLicenseNotification (Swift: .AilaSetLicense) whenever licensing changes internally or via the cloud — including when a newer Configuration Key supersedes the one currently applied. AilaDemo observes it to show a confirmation:

center.addObserver(forName: .AilaSetLicense, object: nil, queue: mainQueue) { _ in
    ToastManager.shared.showToast(message: "License Processed")
}

6. What happens without valid licensing​

  • Standalone development limit (Kiosk). If you're licensed for kiosk scanning and not connected to Aila Hardware, up to 250 scans may be performed for development and testing. Beyond that, scans return the string <UNLICENSED>.
  • Entitlement-gated features. Capabilities such as driver's-license parsing, advanced symbologies (Aztec, Data Matrix, CodaBar, Micro QR), and SoftScan require the appropriate entitlement in your Configuration Key.
  • SoftScan. Using the SDK without Aila hardware in production (SoftScan) requires a licensing plan; the 250-scan development limit does not apply once SoftScan-licensed.

An unregistered bundle ID is the most common cause of an unlicensed build. If you hit <UNLICENSED> unexpectedly, check the portal first.

7. Migration checklist​

  1. Replace Aila.xcframework and AilaDecoder.xcframework with 3.3 or newer (Embed & Sign).
  2. Confirm every bundle ID your app ships with, including development and test bundles, are registered in the Developer Portal.
  3. Build and run with your existing startup sequence.
  4. Observe .AilaSetLicense to confirm your entitlements were processed.
  5. Call Aila_GetSDKLicensingInfo() and confirm the expected entitlements and expirations.
  6. Test the features your entitlements cover (e.g. DL parsing, MRZ, advanced symbologies).
  7. Offline-capable apps only: retrieve the Configuration Key from the portal, add Aila_ReadLicense(key) after Aila_SetConfiguration(config), and decide how you will refresh it later — app update or MDM.

Questions? Reach out to support@ailatech.com or visit the developer portal.