# Licensing

> Which Client SDK licence you need (free for an individual, lifelong with yearly maintenance for an organisation, included with Growth and Scale), how to get a key, how Cloud mode delivers it, and how to supply a key and read its status. The key never blocks tracking.

Source: https://docs.getbeekon.com/reference/licensing/

A Beekon licence is a signed token (a `license-format-v1` JWS) that the SDK verifies on the device, with no network call. The SDK reports its status and never acts on it: no status blocks, degrades or delays anything. Without a key, Beekon runs in **evaluation mode** and works the same.

This page says which licence you need, how to get a key, and how the SDK reads it. The optional [build-time licence gate](#the-build-time-licence-gate) is not published yet.

## Which licence you need

The Client SDK licence covers all four SDKs (Android, iOS, Flutter and React Native) for the app ids it lists. Which one you have follows from your Beekon Cloud account:

| You are                                               | Your licence                                                                                                         | Updates it covers                                                                                                                                                                                 |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **An individual**: one person, building your own apps | **Individual**, free.                                                                                                | SDK versions released up to 12 months after the account was set up as an individual. **Renew updates** in the console, free and at any time, moves that date to 12 months from the day you renew. |
| **An organisation**: a company or a team              | **Organisation**: a lifelong licence, bought once, with one year of maintenance. Renew maintenance a year at a time. | SDK versions released until maintenance ends.                                                                                                                                                     |
| **On Growth or Scale** (either kind of account)       | **Included** with the Cloud plan, at no extra cost. Free does not include it.                                        | SDK versions released while the plan is paid, plus 30 days.                                                                                                                                       |
| **An organisation with none of the above**            | None: the SDK runs in **evaluation**.                                                                                | Evaluation works the same and suits development; production apps need a licence.                                                                                                                  |

**Lifelong** means that an SDK version released while you were covered stays licensed for good. When cover ends (maintenance not renewed, or a Growth or Scale plan ended), apps built with covered versions keep reporting `licensed`. Only SDK versions released after that date report `updateEntitlementLapsed`, and even then the SDK keeps working in full. The key has no expiry date: what it carries is the last release date it covers.

Individual and Organisation are the account kinds you choose when you [sign up](https://docs.getbeekon.com/cloud/sign-up/). An individual account has one member; to invite people, switch it to an organisation (see [Account kind](https://docs.getbeekon.com/cloud/billing/#account-kind)). Prices are not published yet: see the console’s plan picker.

The terms bind

This section is a plain summary. The licence terms in each SDK repository bind: [Android](https://github.com/beekonlabs/beekon-android/blob/main/LICENSE.txt), [iOS](https://github.com/beekonlabs/beekon-ios/blob/main/LICENSE.txt), [Flutter](https://github.com/beekonlabs/beekon-flutter/blob/main/LICENSE) and [React Native](https://github.com/beekonlabs/beekon-rn/blob/main/LICENSE.txt).

## Get a key

Keys are made in the Beekon Cloud console, under **Organisation › SDK licence** (owners and admins).

Coming to the console

The **SDK licence** tab and self-serve sign-up arrive with a coming console release. Until then, ask your Beekon contact for a key.

1. **Add each app** by its exact id: the Android `applicationId` or the iOS bundle id, such as `com.acme.driver`. Wildcards are not accepted. Builds whose id ends in `.dev`, `.debug`, `.staging`, `.qa` or `.test` are covered automatically, so `com.acme.driver.debug` needs no entry of its own. Your licence allows a number of apps; the console shows how many. **Add app** suggests the ids of your projects’ apps that aren’t on the licence yet, and each app’s row in a project’s [Apps](https://docs.getbeekon.com/cloud/console/developers/#apps) tab can add its id with one click.
2. **Copy the key.** The console shows the newest key, masked, with **Copy**. One key covers every app you added, on all four platforms.
3. **Supply it** to the apps that set a key in code or in the manifest or `Info.plist` ([below](#supply-a-key)). Apps in [Cloud mode](#in-cloud-mode) get it automatically.

Each change to the apps makes a new key, and the console says what changed, for example “This key adds com.acme.driver”. Paste the new key into apps that set `licenseKey` in code. An app whose id you removed reports `invalid(appIdMismatch)` once it uses the new key. The console also lists every key made for the organisation, newest first.

## In Cloud mode

In [Cloud mode](https://docs.getbeekon.com/start/configuration/#cloud-mode) the server sends the organisation’s newest key with the project’s config, and the SDK applies it. There is no `licenseKey` to set. Register the app’s id under **Organisation › SDK licence** as above: a device whose app id is not in the key reports `invalid(appIdMismatch)`, a log line only.

A key set in the manifest or `Info.plist` takes priority over the delivered one. If your app sets one, it is used instead.

The SDK keeps the last delivered key on the device with the time the config was last fetched successfully:

* A delivered key that fails verification never replaces a cached key that verifies.
* The cached key is used for **30 days** after the last successful config fetch, by the device’s clock. Past that the status is `evaluation`, and the SDK logs `[Beekon][license] The cloud-delivered license has not refreshed for 30 days; running in evaluation until the next successful config fetch.` The next successful fetch restores the key.
* If the server stops delivering a key (the licence was revoked), the cached key ages out the same way.

Android and iOS keep the key this way from SDK 0.6.0; SDK 0.5.0 applied each delivered key without the cache. Flutter and React Native follow the native SDK of the platform they run on.

## Supply a key

A key passed to `configure` overrides one set in the app’s manifest (`com.getbeekon.sdk.license` meta-data on Android, `BeekonLicenseKey` in `Info.plist` on iOS). A token is bound to your app id and platform, so it is safe to commit to source control.

* Android

  ```kotlin
  // a license-format-v1 token
  Beekon.configure(BeekonConfig.Local(licenseKey = "eyJ…"))
  ```

* iOS

  ```swift
  try await Beekon.shared.configure(BeekonConfig.local(licenseKey: "eyJ…"))
  ```

* Flutter

  ```dart
  await Beekon.instance.configure(
    BeekonConfig.local(licenseKey: 'eyJ…'), // a license-format-v1 token
  );
  ```

* React Native

  ```ts
  // a license-format-v1 token
  await Beekon.configure({ mode: 'local', licenseKey: 'eyJ…' });
  ```

## Read the status

`licenseStatus` is the current status. To follow changes, use `licenseStatusUpdates` on iOS and Flutter, `onLicenseStatus` on React Native, or collect the `Beekon.licenseStatus` `StateFlow` on Android. The status is one of `notDetermined`, `evaluation`, `licensed(tier, entitlements)`, `expired`, `updateEntitlementLapsed` or `invalid(reason)`.

* Android

  ```kotlin
  when (val s = Beekon.licenseStatus.value) {
    is LicenseStatus.Licensed -> Log.d("beekon", "licensed: ${s.tier}")
    is LicenseStatus.Evaluation -> Log.d("beekon", "evaluation mode")
    is LicenseStatus.Invalid -> Log.d("beekon", "invalid: ${s.reason}")
    else -> {}
  }
  ```

* iOS

  ```swift
  // Beekon is an actor, so reading the property needs await.
  switch await Beekon.shared.licenseStatus {
  case let .licensed(tier, _): print("licensed: \(tier)")
  case .evaluation: print("evaluation mode")
  case let .invalid(reason): print("invalid: \(reason)")
  default: break
  }
  ```

* Flutter

  ```dart
  // The current status; subscribe to Beekon.instance.licenseStatusUpdates
  // for changes.
  switch (await Beekon.instance.licenseStatus()) {
    case Licensed(:final tier): print('licensed: $tier');
    case Evaluation(): print('evaluation mode');
    case Invalid(:final reason): print('invalid: $reason');
    default: break;
  }
  ```

* React Native

  ```ts
  // The current status; subscribe with Beekon.onLicenseStatus((s) => …) for changes.
  const s = await Beekon.licenseStatus();
  switch (s.status) {
    case 'licensed': console.log('licensed:', s.tier); break;
    case 'evaluation': console.log('evaluation mode'); break;
    case 'invalid': console.log('invalid:', s.reason); break;
    default: break;
  }
  ```

The `reason` of `invalid(reason)` is one of these, with the platform’s casing (Android `Reason.UnknownKey`, iOS `.unknownKey`, Flutter `LicenseInvalidReason.unknownKey`, React Native `'unknownKey'`):

| `reason`             | Meaning                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `malformed`          | The token can’t be parsed: bad encoding or structure, a disallowed header, or a claim of the wrong type. |
| `unknownKey`         | Signed with a key this SDK version doesn’t know. Update the SDK.                                         |
| `badSignature`       | The signature does not verify.                                                                           |
| `appIdMismatch`      | The token’s `app_ids` don’t include this app’s id.                                                       |
| `productMismatch`    | The token’s `products` don’t include this platform.                                                      |
| `unsupportedVersion` | The token’s claim format is newer than this SDK understands.                                             |

Note

Android and iOS verify the token separately, so one app can report a different status on each. A key issued for `["android"]` reads `licensed` on Android and `invalid` (product mismatch) on iOS.

A token carries claims the SDK reads but never enforces: `products` (the platforms it covers), `app_ids` (the app ids it is bound to), `tier`, `max_release_stamp` (the last SDK release date it covers), `entitlements` and an optional `exp`. A key from the console has `tier` `individual`, `organisation` or `cloud`, covers all four products, and has no `exp`. To get one, see [Which licence you need](#which-licence-you-need) and [Get a key](#get-a-key).

## The build-time licence gate

Beekon also has a build-time gate: a tool your app adds to its own build that fails a **release** build when no usable licence is configured. It runs offline, on your machine or CI, never in your app. Debug builds always pass (on iOS, the configuration named `Debug`), and nothing about it changes what the SDK does at run time. It is opt-in, and it is not anti-tamper: an app that leaves it out is not checked.

Not yet published

The gate is not available to apps in SDK 0.6.0. The Android Gradle plugin is not on Maven Central or the Gradle Plugin Portal, and the `beekon-ios-binary` package your app installs has no `beekon-license-gate` tool. Both will ship with a later SDK release. Until then, a release build is not checked at build time; the licence status at run time works as described above.

How the gate works, for when it ships

The gate reads the key only from the manifest or `Info.plist`. A key passed only to `configure` is invisible at build time, so declare it there too, or acknowledge evaluation (below).

| Licence status at build time         | Release build                                                            |
| ------------------------------------ | ------------------------------------------------------------------------ |
| `licensed`                           | Passes.                                                                  |
| `expired`, `updateEntitlementLapsed` | Passes, with a warning.                                                  |
| `evaluation` (no key) or `invalid`   | Fails, unless evaluation is acknowledged; then it passes with a warning. |

* Android

  A Gradle plugin, `io.github.beekonlabs.license-gate`, applied in the app module. It adds a `checkBeekonLicense<Variant>` task to the `assemble` and `bundle` tasks of every variant whose build type is not named `debug`, and reads the merged manifest:

  * the key: `com.getbeekon.sdk.license` meta-data, or `-Pbeekon.licenseKey=…` on the Gradle command line (for CI);
  * the evaluation acknowledgment: `com.getbeekon.sdk.evaluationMode` meta-data set to `true`.

* iOS

  A command-line tool, `beekon-license-gate`, run from a **Run Script** build phase in the app target. It gates every configuration except one named `Debug`, so a custom configuration such as `Staging` is gated too. It reads the processed `Info.plist` at `$(TARGET_BUILD_DIR)/$(INFOPLIST_PATH)`:

  * the key: `BeekonLicenseKey`, or the `BEEKON_LICENSE_KEY` environment variable;
  * the evaluation acknowledgment: `BeekonEvaluationMode` set to the Boolean `YES` (a string does not count), or `BEEKON_EVALUATION_MODE`.

  With user script sandboxing on (`ENABLE_USER_SCRIPT_SANDBOXING = YES`, the default for projects created in recent Xcode versions), the script can read only the files it declares. Add `$(TARGET_BUILD_DIR)/$(INFOPLIST_PATH)` to the Run Script’s **Input Files**. Without it the tool sees an empty `Info.plist`, finds no key, and fails the build as evaluation.

  A non-zero exit fails the build, with the reason on stderr.

* Flutter

  Android needs nothing extra: the plugin’s manifest tells the Android gate that the product is `flutter`. On iOS, set `BEEKON_PRODUCT=flutter` in the Run Script, or add `BeekonProduct` = `flutter` to the app’s `Info.plist`.

* React Native

  Android needs nothing extra: the library’s manifest tells the Android gate that the product is `rn`. On iOS, set `BEEKON_PRODUCT=rn` in the Run Script, or add `BeekonProduct` = `rn` to the app’s `Info.plist`.
