Skip to content

Latest commit

 

History

History
866 lines (706 loc) · 45.8 KB

juce-module.md

File metadata and controls

866 lines (706 loc) · 45.8 KB

JUCE module: moonbase_licensing

A drop-in JUCE module that adds Moonbase license activation, with a polished built-in UI, to any JUCE app or plugin. It integrates natively with the Moonbase licensing API; it does not use juce::OnlineUnlockStatus.

Prefer the juce::OnlineUnlockStatus bridge? That older, copy-paste reference still lives in examples/juce/ and is unchanged. This module is the native alternative.

Lives at modules/moonbase_licensing/. Requires JUCE 6.1.3 or later (6.x, 7.x, 8.x and 9.x are all supported and all covered by CI) and C++17. 6.1.3 is the floor because it is the first release with juce::URL::DownloadTaskOptions, which the in-app updater uses. It is also the version HISE pins, so the module drops into a HISE project.

Why it's drop-in

A normal JUCE module is self-contained and links only JUCE + system frameworks. This one is too — it has no third-party dependencies:

Concern How
HTTP juce::WebInputStream (juce_http_transport), so no HTTP library of its own
JSON bundled nlohmann/json single header (in the module's vendor/)
RS256 JWT verification OS-native: Security.framework (macOS/iOS), CNG/bcrypt (Windows), system libcrypto (Linux)

So a downstream project adds the module and builds, with nothing to brew or vcpkg install. (Linux is the one platform with caveats: the module links the always-present system libcrypto, and JUCE needs libcurl there for HTTPS, as the Linux note below explains. macOS and Windows need nothing beyond the OS.)

The module sets MOONBASE_CRYPTO_NATIVE and MOONBASE_DISABLE_CURL_TRANSPORT itself; the core SDK keeps its OpenSSL + CURL defaults for non-JUCE consumers, so nothing about the existing find_package(moonbase_cpp) path changes.

Add it to your project

Add this repository as a git submodule, then point your build at the module folder.

CMake

juce_add_module(external/moonbase-cpp/modules/moonbase_licensing)

target_link_libraries(MyPlugin PRIVATE moonbase_licensing)

CMake, through FetchContent

Fetch the repository instead and turn on MOONBASE_JUCE_MODULE_ONLY. The build then adds the moonbase_licensing module target and nothing else: the core SDK target and its OpenSSL and CURL lookups are skipped, so the machine needs neither. The module is added with JUCE's own juce_add_module, so make JUCE available first. When your JUCE has juce_animation, the build links it into the module for you.

include(FetchContent)
FetchContent_Declare(moonbase_cpp
    GIT_REPOSITORY https://github.com/Moonbase-sh/moonbase-cpp.git
    GIT_TAG v4.14.0)
set(MOONBASE_JUCE_MODULE_ONLY ON)
FetchContent_MakeAvailable(moonbase_cpp)  # after JUCE

target_link_libraries(MyPlugin PRIVATE moonbase_licensing)

Projucer — Modules → Add a module from a specified folder… → select modules/moonbase_licensing. The bundled SDK headers and nlohmann/json resolve from the module's own search paths.

juce_animation is deliberately not a declared dependency, since the API the module needs from it only exists from JUCE 8.0.4. The module detects it: link it and the transitions run on juce::Animator, leave it out and they run on the module's own equivalent. Nothing to configure either way.

The header is safe to include from a translation unit with a file-scope using namespace juce;, in either include order. Getting there costs one thing worth knowing about: it renames the two system-header names that would otherwise be ambiguous with JUCE's, Carbon's Point and GDI's Rectangle(), so neither is reachable under its own name once you include the module header. Define MOONBASE_DISABLE_SYSTEM_NAME_SHIM if you need them.

Linux needs libcurl

On Linux, juce::WebInputStream makes HTTPS requests through libcurl. Without it JUCE can only reach http:// URLs, so the module could never reach the Moonbase API. Leave JUCE_USE_CURL on (JUCE's default), install libcurl's development package (libcurl4-openssl-dev on Debian and Ubuntu), and pass NEEDS_CURL TRUE to juce_add_plugin() or juce_add_gui_app() so JUCE links it. In the Projucer, leave JUCE_USE_CURL enabled in juce_core's module settings.

With JUCE_USE_CURL=0 the module fails to compile on Linux, rather than build a product that can never activate. Other platforms use the OS's own HTTP stack and ignore the flag.

Configure + show it

#include <moonbase_licensing/moonbase_licensing.h>
using namespace moonbase::juce_integration;

ActivationConfig config;
config.endpoint    = "https://your-tenant.moonbase.sh";
config.productId   = "your-product";
config.publicKey   = embeddedPublicKeyPem;
config.productName = "Your Plugin";
config.manufacturerName = "Your Manufacturer";
config.accent      = juce::Colour(0xff186cdc);

Embed in a plugin editor:

activation = std::make_unique<ActivationComponent>(config);
addAndMakeVisible(*activation);
activation->onActivationChanged = [this](bool active) { /* enable/disable UI */ };

…or pop it as a standalone window:

ActivationDialog::show(config, [](bool wasActivated) { /* … */ });

The flow

ActivationComponent owns an ActivationController — a headless state machine over moonbase::licensing. Network calls run on a controller-owned thread pool; all state changes and repaints happen on the message thread, gated by a generation counter so a slow request can never clobber a newer state. Destroying the controller cancels any in-flight request, stops waiting on another instance's license check, and joins its workers, so nothing keeps running after teardown: you can call start() straight from the editor constructor and destroy the editor at any time (plugin scanning, pluginval, rapid open/close) without deferring or guarding it. The screens:

  • Welcome — Activate online (browser flow) or Activate offline.
  • Activating — opens the browser and polls get_requested_activation() every 2 seconds; the device chip shows the local fingerprint + platform; Cancel aborts. A "Copy the link" action is always there for a browser that didn't show up. When the browser can't be opened at all (Windows with no default browser set, say), the screen says so and makes copying the link its main action, so the user can finish in any browser, on this computer or another. If the request expires (after an hour) or is cancelled, the server answers 400, polling stops and the welcome screen returns with "This activation expired or was cancelled. Activate again to continue."; the server's reason goes to onDiagnostic. If the request can't be started, the welcome screen's message says whether Moonbase was unreachable, busy (rate limiting or a server error), or refused it for this product, or that the machine has no identity to activate. A failure that is none of those (a bug in a custom device id resolver, say) is shown in its own words rather than passed off as a connection problem.
  • Success — animated confirmation with a mini license card.
  • Offline — two-step machine-file flow: save the request (generate_device_token), then load the response file (read_offline_license, validated locally).
  • Trial — days-left badge, progress bar, included/excluded feature list, and an Unlock action that routes into online activation. An endless trial (a product whose trials never expire, so the token has no exp) shows a plain "Trial" badge and no progress bar; trialIsEndless() tells you which one is loaded.
  • License details — issued-to / email / plan / activation / expiry, a seat counter, and a Deactivate action (server-side revoke_activation, with a local-forget fallback for offline or trial licenses). With config.showAddOns, an "Add-ons" row too.
  • Add-ons (opt-in): the product's add-ons, each with where it stands on this computer and a Try free, Buy or Activate action. See Add-ons.
  • Trial expired — a locked "trial has ended" screen with Unlock / Activate offline.
  • Upgrade needed. A locked screen for a license that doesn't cover this version of the app, such as one whose updates ended before it came out. It says what the license covers and offers the upgrade, and the license stays stored; see Licenses that cover some versions.
  • Update available. Shown when a validated license reports a released version (the current_release_version / p:rel claim) newer than the app version. Loads the release notes from the inventory endpoints and downloads the new installer for the current platform in-app, with progress. "Skip this update" dismisses it (recorded so the quiet startup path won't re-prompt for that version; a newer release still does). Controlled by config.enableUpdatePrompt / config.applicationVersion / config.downloadDirectory / config.autoPresentUpdate.

Animated throughout: cross-fade + fade-up between screens, the activating spinner, the success pop, and the breathing top-edge glow. From JUCE 8.0.4 these run on juce_animation (juce::Animator / ValueAnimatorBuilder / Easings) when your project links it; otherwise the module uses its own equivalent, with the same cubic-bezier curves, so the motion is identical on every JUCE version. Either way a 60 Hz juce::Timer supplies the ticks, not a VBlankAnimatorUpdater. That timer only runs while the component is on screen: hiding it or any parent stops it, so a panel kept hidden in every editor costs nothing. Set config.reduceMotion to turn off the transitions, the success pop, the appear animation and the glow. The activating spinner keeps turning, because it is the one sign that the wait is still alive.

Starting a trial without the browser

The built-in screens get a trial through the browser page. For a product whose trials need no account, a UI of your own can start one on the computer directly, with no browser (moonbase::licensing::request_trial):

activation.requestTrial ([] (bool started, const juce::String& message) {
    // message says why, for the user, when it didn't start
});

The trial is stored and the Trial screen shows, as for one started in the browser, and onLicenseChanged fires. isStartingTrial() is true until the answer lands. A computer gets one trial: one that had it gets it back with the days it has left, or the Expired screen once it has ended. Moonbase refuses a trial this call can't start, and the Error screen says so. For a product whose trials need a signed-in customer or a newsletter opt-in, beginOnlineActivation() is the way to its trial, as the browser page offers it. The call is ignored while a license is loaded, until start() has checked the stored one, and while an activation is in progress. A license another instance stores while the request is out is kept, and shown, instead of the trial.

Gating

For correctness in a plugin, give the processor the controller (so license state survives the editor's lifetime) and have the editor share it — one license, no hand-rolled re-sync:

// In your AudioProcessor:
ActivationController activation { makeConfig() };   // persistent
// activation.start();  // load any stored license

// In createEditor(): share the processor's controller with the UI.
auto* editor = new ActivationComponent (processor.activation);   // non-owning overload

Gate the audio thread off the lock-free flag — no ChangeListener needed:

void processBlock (juce::AudioBuffer<float>& buffer, ...) override
{
    if (! activation.licensedFlag().load())
        buffer.clear();
}

Or use LicenseGate for a click-free fade on activate/deactivate (you still own the gating; the module never silences audio itself):

LicenseGate gate;                                  // a member of your processor
void prepareToPlay (double sr, int) override { gate.prepare (sr); gate.reset (activation.licensedFlag().load()); }
void processBlock (juce::AudioBuffer<float>& b, ...) override
{
    gate.process (b.getArrayOfWritePointers(), b.getNumChannels(), b.getNumSamples(),
                  activation.licensedFlag().load());
}

controller().license() is the full moonbase::license (trial, expires_at, issued_to.email, owned_sub_product_ids, sub_products, custom properties and so on) for richer gating decisions; read it on the message thread. For add-ons, see Add-ons.

To react to the license itself (reload features, update your own status), assign onLicenseChanged before start(). It runs on the message thread once start() has settled, then only when the license changes: activated, refreshed into a new token, picked up from another instance, revoked, expired or cleared. Screen changes, progress and a re-check that changed nothing don't fire it. ActivationComponent::onActivationChanged follows the same rules, separately for each component.

activation.onLicenseChanged = [this] (bool licensed) { reloadFeatures(); };
activation.start();

Expiry and other instances

Once started, the controller keeps an eye on the license by itself, with a local check every 2 seconds (a look at the license file and the clock, no network):

  • A trial or subscription whose exp passes while the plugin is open locks then, not at the next launch. A trial goes to the Trial expired screen.
  • A license that has gone unverified for longer than onlineGracePeriod gets one more online check, and locks if Moonbase can't be reached, as it would at launch.
  • If either happens while the user is activating (typically a trial being unlocked), the license locks on the spot and the activation carries on; when it lands, it replaces the license. The same goes for a license another instance removes during an activation.
  • When another plugin instance, the standalone app, or a host that runs each plugin in its own process activates, refreshes or deactivates, the other controllers pick it up within a couple of seconds, with no reload. They all share the license file. A refresh elsewhere updates the license in place without moving the screen; a different activation replaces it, and anything still in flight for the old one is dropped. A stored license nobody has verified within onlineGracePeriod is not picked up until an instance re-validates it.

Sandboxed formats (AUv3, Mac App Store builds) each keep the license in their own container, so they don't share an activation with the other formats.

When the plugin locks

Every way of losing a license ends the same way: licensedFlag() drops, onLicenseChanged(false) and onActivationChanged(false) fire, and an ActivationComponent presents itself. That covers expiry, the grace period running out, a revoke found on re-validation, and a deactivation in this or another instance. It also happens when an editor opens on a plugin that locked while the editor was closed. So an overlay the user closed after activating comes back on its own, and one you add hidden with addChildComponent shows when it is needed.

  • It leaves the host's keyboard focus alone. The overlay takes focus only when it is already in the plugin's window, so the controls it covers stop getting keys. When the user is working in the host, the plugin window doesn't become the key window, and the host's shortcuts (the space bar, say) keep working. appear() follows the same rule, so calling it from a background event is safe too; call grabKeyboardFocus() on the component to focus it regardless.
  • It says why. The welcome screen swaps its title and body for the reason, from controller.lockReason(): Deactivated (here or in another instance), Expired (a subscription or offline license reached its end date), Invalid (Moonbase no longer accepts it: revoked, or bound to another device) or Unverified (not checked online within onlineGracePeriod). A trial that ends gets the Trial expired screen instead, and a license that doesn't cover this version of the app the Upgrade needed screen (NotCovered). The copy is in config.strings (deactivatedTitle, licenseExpiredBody, and so on), and lockReason() goes back to None once a license is loaded. A custom UI can read it from onLicenseChanged(false).
  • It steps back when the license returns. If the overlay only opened for the lock and the license comes back from elsewhere (activated again in another instance), it closes itself, without calling onClose. One the user opened, or activated in, stays up.
  • It presents once per lock, not on every change while the plugin stays locked, and it doesn't replay the appear animation over an overlay that is already up.

Set config.autoPresentOnLock = false to present it yourself, for example from onActivationChanged(false) after your own "license ended" notice.

For a custom UI, pendingBrowserUrl() returns the browser link while an online activation is waiting, so you can show or copy it when the browser didn't open; a change is broadcast when it arrives. browserOpenFailed() tells you the launch failed, so you can put the link front and centre. To open the link your own way, set config.openBrowser (return false when it couldn't be opened).

Branding / theming

Everything in ActivationConfig after the connection fields is brand/UI: product + manufacturer name, accent colour, the Moonbase co-brand badge (showMoonbaseBadge), the trialLengthDays + trialFeatures list (shown on the Trial / Expired screens; an endless trial ignores trialLengthDays), enableOffline, and the activationUrl.

For a deeper re-skin, config.palette holds every other colour in the UI as its own token, and config.fonts takes your typefaces for the three font roles:

config.accent = juce::Colour(0xffe4a03c);

config.palette.backgroundTop = juce::Colour(0xff2a1c12);   // see ActivationTheme.h
config.palette.panelTop      = juce::Colour(0xff1e1610);   // for the full token list
config.palette.textPrimary   = juce::Colour(0xfff7ecdc);
config.palette.onAccent      = juce::Colour(0xff2a1a08);   // text drawn on the accent

// Bundle faces with juce_add_binary_data and hand them over per role. Do this
// rather than setting a default LookAndFeel: inside a DAW that one is shared
// with the host and every other plugin in the process.
config.fonts.heading = juce::Typeface::createSystemTypefaceFor(
    BinaryData::InterBold_ttf, BinaryData::InterBold_ttfSize);
config.fonts.body = juce::Typeface::createSystemTypefaceFor(
    BinaryData::InterRegular_ttf, BinaryData::InterRegular_ttfSize);
config.fonts.mono = juce::Typeface::createSystemTypefaceFor(
    BinaryData::SpaceMono_ttf, BinaryData::SpaceMono_ttfSize);

Set both before you construct the ActivationComponent (or pass the config to ActivationDialog::show, which also frames its window in palette.backgroundBottom). The component reads the theme once, when it builds its LookAndFeel and pre-renders its icons, so a palette changed afterwards would only reach half the screen.

Leave any token alone and it keeps the built-in design's value, so a single line is a valid theme. config.fonts.makeFont is the escape hatch when one typeface per role is not enough: set it and it decides every font the UI asks for, by role and height.

Device identity

By default the module identifies the device with moonbase::moonbase_device_id_resolver, which implements the cross-SDK device fingerprint spec (moonbase:fingerprint:v2). A license activated in a web or Electron app built on @moonbase.sh/licensing validates in your plugin, and the other way round. See Device identity for the stability contract and the Linux caveats.

It still shells out to nothing: IOKit on macOS, world-readable files on Linux and the firmware table on Windows all work inside a sandboxed host, and none of them depend on the process running elevated.

Supply your own with config.deviceIdResolver, and inspect what the default resolved to with controller().describeDevice(), which returns the id, spec version, platform tag and the names of the contributing parameters. That is safe to put behind a "Copy diagnostics" button; parameter values are hardware serial numbers and are never exposed.

Migrating an already-shipped plugin

This changed in 4.0.0. Earlier versions used juce::SystemStats::getUniqueDeviceID(), so every already-activated user's license is bound to that id. Without action they are locked out at next launch and must re-activate, which consumes a fresh activation seat and resets any device-scoped trial. One line avoids it:

config.deviceIdResolver = std::make_shared<moonbase::migrating_device_id_resolver>(
    // The platform default, NOT moonbase_device_id_resolver directly: on iOS and
    // Android that has no identity to read and throws, and a migrating resolver
    // asks its current resolver for an id before consulting any historical one,
    // so hard-coding it locks mobile users out of validation *and* activation.
    ActivationConfig::defaultDeviceIdResolver(),                                     // binds
    std::make_shared<moonbase::juce_integration::legacy_juce_device_id_resolver>()); // still accepted

New activations bind the spec id; existing licenses keep validating; the fleet migrates as devices naturally re-activate, and you drop the wrapper in a later release. Because getUniqueDeviceID() is JUCE's own derivation rather than a published format, the historical resolver only vouches for a binding if the plugin still ships the JUCE version that created it, so do not combine this upgrade with a JUCE major bump. Full options in Migrating from 3.x.

iOS and Android use a scoped identity

On iOS and Android the module emits a scoped spec id, stamped mbd2s_, built from identifierForVendor and ANDROID_ID respectively. Both readers live in the core SDK, not in this module: the fingerprint is framework-independent by design, so a non-JUCE app computes the same id.

Neither platform exposes a device identifier that unrelated applications can read. iOS has had no accessible hardware serial since iOS 7, and identifierForVendor is scoped to the App Store vendor; Android's Build.SERIAL returns unknown without a privileged permission from Android 10, and ANDROID_ID has been scoped to the app signing key since Android 8. Cross-SDK parity on mobile is therefore impossible by construction. Rather than hide that, the spec's scoped identity rules stamp the limitation into the id: it is stable for your device within the platform's scope, and must never be correlated with an id from another scope, in either direction.

Note the scope is the platform's, not yours: one vendor's two differently-signed Android apps do not share an id.

config.allowDeviceNameFallback is forbidden on both, not merely ignored. Since iOS 17 gethostname() returns the literal localhost on every device and UIDevice.name returns the model name; on Android the label is Build.MODEL. An SDK that fell through to the fallback when the scoped identifier was momentarily absent would hand its entire install base one device id, and a single activation would unlock every device. The ladder is scoped identity, then insufficient identity, and nothing else. Absence is transient, so retry later.

The Android reader deliberately does not use juce::SystemStats::getUniqueDeviceID(). That reads the static field Settings.Secure.ANDROID_ID, which is the key name "android_id" rather than the device's value, so every JUCE Android app reports the same id. The spec's ^[0-9a-f]{1,16}$ rule makes that mistake mechanically impossible here, since "android_id" is not hex.

Mobile needs the same migration as desktop. mbd2s_<hash> is a different value from the raw getUniqueDeviceID() string bound before 4.0.0, so pass legacy_juce_device_id_resolver as a historical resolver there too.

When a machine has no hardware identity

Elsewhere, activation fails with moonbase::insufficient_device_identity_error rather than binding something weak, and the controller routes it to the Error screen with a diagnostic explaining why. This is reachable on cloned VM images whose SMBIOS carries an unset UUID and a blank baseboard serial, and on minimal containers.

Set config.allowDeviceNameFallback = true to accept a weaker id derived from the computer name instead. Those ids are stamped mbd2n_ so the server can tell them apart from real hardware bindings. Weigh it against the "iPhone" problem above: the fallback is only safe where computer names are actually distinct.

Sample app

examples/juce-native/ is a runnable standalone app that drops the component against the public Moonbase demo tenant:

cmake -B build -DMOONBASE_BUILD_JUCE_NATIVE_EXAMPLE=ON
cmake --build build --target MoonbaseActivationNative

It fetches JUCE on first configure and adds the module with juce_add_module, exactly how a downstream project consumes it. Pass -DMOONBASE_JUCE_VERSION=9.0.4 to build the sample against JUCE 9, or 6.1.3 (or 7.0.12) for an older JUCE.

Tests

Two automated suites cover the module:

  • Behavioral (tests/juce/) drives ActivationController against injected fake store / transport / fingerprint and asserts the state machine: startup routing (Welcome / Details / Trial), expired-offline-license removal, online revoke vs. local forget vs. unreachable, and the offline activation round-trip. Tokens are signed with OpenSSL and verified by the module's native crypto backend, so the suite also exercises cross-backend RS256 parity.
  • Visual (tests/visual/) renders every screen offscreen to PNGs for Argos diffing.
cmake -B build -DMOONBASE_BUILD_JUCE_TESTS=ON
cmake --build build --target MoonbaseJuceTests
ctest --test-dir build -R "Juce\." --output-on-failure

The controller is built for injection: alongside the production constructor there is an ActivationController(config, std::shared_ptr<moonbase::licensing>, deviceName) overload that takes ready-made dependencies, so tests run with no network and no real device id.

Both suites can be built under a sanitizer (the controller and the license store both spawn threads, so this guards against races and use-after-free):

cmake -B build-tsan -DMOONBASE_BUILD_TESTS=ON -DMOONBASE_SANITIZER=thread
cmake -B build-asan -DMOONBASE_BUILD_TESTS=ON -DMOONBASE_SANITIZER=address,undefined

CI: sanitizers.yml runs the SDK suite under ASan/UBSan and TSan on Linux; juce.yml builds the module and runs the behavioral suite on Linux, macOS and Windows against JUCE 8.0.4 and 9.0.4, and on macOS against 8.0.0, 7.0.12 and 6.1.3.

Diagnostics

The UI shows friendly, end-user-facing copy for every failure it can name. One it can't (an exception that is neither Moonbase's answer nor a failed connection) is shown verbatim, so a customer's screenshot carries the actual error. To see the underlying reason behind any failure (bad config, rejected token, unreachable server, persist failure), wire a diagnostic sink:

config.onDiagnostic = [] (const juce::String& message) {
    juce::Logger::writeToLog ("[activation] " + message);
};

It is invoked on the message thread. A missing or malformed endpoint / productId / publicKey does not throw out of construction; the component shows an Error state and the reason is reported through this sink (and DBG in debug builds).

Escape hatch: on the license details screen, double-clicking the green "Active" pill reveals the configured license folder (where license.mb and license.state.json live) in the OS file browser. It's an undocumented gesture (no pointer cursor) for support / debugging, e.g. to inspect or clear persisted state.

Refreshing entitlements

After a user buys something mid-session (a sub-product, an upgrade), re-validate the license online so the new entitlements load without a restart:

activation->controller().refreshLicense (/*force*/ true, [] (bool refreshed) {
    if (refreshed) reloadFeatures(); // read controller().license() again
});

It runs async and silently (no screen change). On success the license is updated + persisted, and when the server sent a new token onLicenseChanged and onActivationChanged fire; controller().license() then reflects the new owned_sub_product_ids, properties, expiry, and seat counts. force bypasses the SDK's online_validation_min_interval throttle (you want that right after a purchase); pass false for a polite background re-check that respects it. A network failure is non-fatal: the current license is kept and the reason goes to onDiagnostic. So are rate limiting, a server error, and a response that didn't come from Moonbase (a captive portal's sign-in page), as long as the license is within onlineGracePeriod of its last successful check. A definitive rejection is not: when the server says the license was revoked or has lapsed, the controller drops it and shows the welcome screen, and onActivationChanged fires. The same happens when the grace period has run out and Moonbase still can't be reached. The license file stays, as it does when start() meets the same answer, so the next launch checks it again: a lapsed subscription that is renewed unlocks there. A revoked license doesn't stay. Moonbase never restores one, and a revoked activation only comes back by activating again, so the controller deletes the file when Moonbase says either, at launch as on re-validation. An offline launch then has nothing to fall back on, and other instances lock within a couple of seconds, as they do for a deactivation. Offline licenses are a no-op (they are permanent and not server-tracked).

Cadence and timeouts

How often the app re-checks online, how long it tolerates being offline, and the request timeouts are all configurable:

config.onlineCheckInterval = std::chrono::hours (1);     // min spacing between online checks (default 5 min)
config.onlineGracePeriod   = std::chrono::hours (24 * 30); // max time offline before locking (default 7 days)
config.httpConnectTimeout  = std::chrono::seconds (5);
config.httpRequestTimeout  = std::chrono::seconds (15);

The SDK never polls the server on a timer; it validates online on launch (start()) and whenever you call refreshLicense(), throttled to no more than once per onlineCheckInterval. A license stays usable offline until onlineGracePeriod elapses since its last successful online validation; the controller's local check (see Expiry and other instances) enforces that mid-session too, with one last online attempt before it locks. Both are measured by the computer's clock; a last validation more than a few minutes ahead of it counts as past both.

Add-ons

An add-on (a sub-product, with a product ID like my-app.drum-kit) that the merchant includes in the product's license travels in it. When a device activates or validates the product, it takes a seat of each add-on the customer owns, and the license says which ones this device may unlock. Ask the controller, on the message thread:

if (activation.hasSubProduct ("drum-kit"))
    enableDrumKit();

hasSubProduct takes the add-on's own part of its ID or the whole ID, and is true while the license lists the add-on as active and it hasn't expired. activeSubProducts() lists every such add-on. It only knows add-ons the merchant includes in the license: for one that is just owned, without seats on devices (the add-ons screen shows it as "Owned"), check license()->owned_sub_product_ids instead. One bought after activating shows up at the next validation, or right away with refreshLicense (true). When an add-on's trial runs out while the plugin is open, the license watch notices: onLicenseChanged and onActivationChanged fire, with the license itself still in place. So reading hasSubProduct again from those callbacks is all a host has to do.

hasSubProduct and activeSubProducts are for the message thread only: they read the license the controller holds there, and allocate (debug builds assert when they're called from another thread). For the audio thread, ask for the add-on's subProductFlag once, on the message thread, keep the pointer, and read it in processBlock, as you would a parameter from AudioProcessorValueTreeState::getRawParameterValue:

const std::atomic<bool>* drumKit = nullptr;   // a member of your processor

// In the processor's constructor:
drumKit = activation.subProductFlag ("drum-kit");

void processBlock (juce::AudioBuffer<float>& buffer, juce::MidiBuffer& midi) override
{
    if (drumKit->load())
        renderDrumKit (buffer, midi);
}

The flag is never null and lives as long as the controller. It changes in the same step as licensedFlag(), and within a couple of seconds of an add-on running out while the license carries on. One the license doesn't include stays false. To fade an add-on in and out without clicks, give it a LicenseGate of its own and pass it drumKit->load().

The add-ons screen

Set config.showAddOns = true and the license view gets an "Add-ons" row, with how many are active here. It opens a screen listing the product's add-ons the customer can do something with (moonbase::licensing::list_sub_products), each saying where it stands on this computer and offering what makes sense:

  • Try free for an add-on whose trial the customer can start. One whose trial is for newsletter subscribers says so until the customer joins.
  • Buy for one on sale. It opens the add-on's store page in the browser, through config.openBrowser when set. When the customer comes back to the app, the license is re-validated, so the new add-on takes its seat, and the add-ons are listed again. "Bought an add-on? Refresh" under the list does the same by hand, for a platform that can't tell when the app is in the background.
  • Activate for one the customer owns that this computer holds no seat of: one they deactivated here from their account, or any of them when config.autoActivateSubProducts is off.

License details screen with an Add-ons row reading '2 active' and a chevron, under the licensed-to, email, plan, activation and expiry rows. Add-ons screen: 'Laniakea Pack' active on this computer, 'Keys' in its trial with 5 days left and a Buy button, and 'Drum Kit' offering a 7-day free trial at €39 with Buy and Try free buttons.

The license view's Add-ons row, and the add-ons screen it opens.

Opening the screen lists the add-ons without checking the license. When the list shows one the customer owns, with a seat free, that this computer doesn't hold yet (bought since the license was last checked), the license is checked once to take the seat, unless config.autoActivateSubProducts is off.

A refusal shows under the list in the user's terms (no free seat, an add-on that can't be tried here, no connection), and the server's reason goes to onDiagnostic. The screen opens from a full license only, since add-ons are activated and tried from one.

A UI of your own

The screen runs on calls you can make yourself:

activation.loadAddOns();   // fills activation.addOns(), then broadcasts a change (can take a seat, see below)
activation.requestSubProductTrial ("drum-kit", [] (bool started, const juce::String& message) {
    // message says why, for the user, when it didn't start
});
activation.activateSubProduct ("drum-kit");
activation.buySubProduct ("drum-kit");   // opens its buy link from addOns()

loadAddOns() can take a seat. It is not read-only while config.autoActivateSubProducts is on (the default). The list itself changes nothing on the server, but when it shows an add-on the customer owns, with a seat free, that this computer doesn't hold yet, the controller re-checks the license once, and that check takes the seat, as every license check does. With the option off, loadAddOns() only reads, and seats are taken only through activateSubProduct.

addOns() holds the list (each a moonbase::sub_product_catalog_entry, with prices, ownership, trial status and buy link), whether it is loading, why it failed, and which add-on is being activated (busyId). Activating and trying run one at a time; each stores the license that comes back, and lists the add-ons again if they were loaded. When the server refuses the license itself (revoked elsewhere, say), the controller re-checks it and locks as refreshLicense would.

App updates

A validated license carries the product's current released version in its claims (license.licensed_product.current_release_version, the JWT p:rel claim). On launch and after every re-validation, the controller compares it (via moonbase::update_available, a small SemVer compare in moonbase/version.hpp) against the running app version:

config.applicationVersion = "2.3.1";   // or rely on JucePlugin_VersionString
config.enableUpdatePrompt = true;       // default; set false to never prompt
config.downloadDirectory  = {};         // default: the user's Downloads folder

When the released version is newer, the Update available screen shows instead of the Details / Trial screen (it never interrupts the locked Expired screen). It then:

  1. Fetches the release notes (plain text) from GET /api/customer/inventory/products/{productId}?version={released}.
  2. On "Download", resolves an authenticated, short-lived installer URL from GET /api/customer/inventory/products/{productId}/download/{platform}/latest?redirect=false and downloads it into config.downloadDirectory with progress, then reveals it.

Download gating. The product response says whether this customer may download the release (downloadsAllowed), which Moonbase decides with every rule the release has: owning the product, belonging to a group of customers it is limited to, and the versions their licenses cover. moonbase::can_download(license, info) uses that answer. An older Moonbase doesn't send it, so there it applies the release access-control level (downloadsNeedsUser / downloadsNeedsOwnership) itself: a full (non-trial) license owns the product and can download; a trial cannot download from an owners-only product (the default). When the license can't download it, the screen swaps the Download button for a short note, so the user never hits a 403 (updateInfo().canDownload). When a full license is what's missing, as for a trial, it offers an Unlock full version CTA (updateInfo().needsFullLicense); for a release Moonbase keeps from this customer for another reason, it says the license can't download it and offers nothing. When Moonbase says the customer's licenses don't cover the new version, the screen offers the upgrade instead and says what they cover (updateInfo().covered, releaseAccess and upgradeUrl; see Licenses that cover some versions).

Both inventory requests authenticate with the license token via the Authorization: LicenseToken <jwt> scheme (moonbase::inventory_client). Observe controller().updateInfo() for the phase, versions, notes, progress, and canDownload.

When it appears. With config.autoPresentUpdate (default on), the module presents the update screen automatically when the plugin opens with an available, non-skipped update (the controller routes there on startup / re-validation and the component appears the overlay). Opening the license view explicitly (e.g. the host's "License" button) never auto-shows it — closing the update overlay returns the resting screen to the license view, so re-opening lands on the license screen. The license view also keeps a clickable "Update available" badge next to the "Active" pill (whenever updateAvailable() is true) that opens it on demand; ActivationComponent::presentUpdateIfAvailable() is the explicit host hook. The overlay also presents itself when the plugin locks (see When the plugin locks).

"Skip this update". Dismissing records the version in the ignoredUpdates list (so it won't auto-present again for that version; a newer release still does). Where it goes depends on how the screen was entered (tracked via updateCameFromLicenseView()): from the license-view badge → back to the license view; auto-presented on open → it just closes the overlay (the host's onClose).

What is and isn't cached between sessions. The released version is part of the license token, so it is read from the persisted license.mb on every launch (no network needed) and refreshed on the next successful online validation. The release notes and the installer URL are not cached: fetchUpdateInfo() re-fetches the notes each time the screen is shown, and the presigned installer URL is resolved fresh on each "Download" click (it expires after ~15 minutes). The skip list lives in a small JSON state file beside the license (<license>.state.json); that file (ActivationState) is the general place for client state that should survive restarts, so future cached/remembered values live there too.

Licenses that cover some versions

A license bought outright can cover only some versions of the plugin: those released while its updates lasted ("12 months of updates"), or every version up to a major ("versions up to 2.x"). Moonbase checks the running version against it on every online validation, and the module checks it on this computer when Moonbase isn't asked, so set config.applicationVersion (or rely on JucePlugin_VersionString) to the version that has to be covered.

A license that doesn't cover the running version locks the plugin, like a trial that ended, but stays stored: it still covers the versions it did, so the customer can go back to one of them. The Upgrade needed screen names the version, says what the license covers, and offers:

  • Upgrade license, or Renew updates for a license whose updates ended (controller().upgradeLicense()). It opens the upgrade page Moonbase named for the license. Without one (the license was judged on this computer, offline or moments after a check), it starts an online activation instead: Moonbase's activation page offers the upgrade to a signed-in customer where the store sells one, then activates this computer on it.
  • Already upgraded? Check again (controller().refreshLicense()), which unlocks once the upgrade has gone through. An offline license is never checked online, so it gets a link to load the upgraded license file instead.

An offline license is judged by its license file alone. A version limit holds either way, but a time limit in a file made while updates lasted can't say which version came last, so once the updates end that file keeps covering later versions until the customer loads a new one (see the core SDK guide).

Instances share the license file, so this works both ways: an upgrade another instance picks up unlocks this one, and a refusal another instance gets from Moonbase locks it.

For a custom UI, controller().notCovered() holds the license, the version it doesn't cover, what it covers (releaseAccess) and the upgrade link (upgradeUrl, empty when Moonbase didn't name one), and lockReason() is LockReason::NotCovered. config.notCoveredTitleText() and config.notCoveredBodyText() give the built-in copy, which config.strings.notCoveredTitle and notCoveredBody override.

Telemetry / analytics

Off by default. One flag attaches JUCE system + host metadata to every activation and validation request (the same juce.* keys the reference bridge collects):

config.analytics.enabled = true;          // OS, CPU, JUCE version, memory
config.analytics.includeHostInfo = true;  // DAW host + plugin format (VST3/AU/AAX/...)
config.analytics.includeLocaleInfo = true; // language / region (opt in)

Host/plugin fields are captured only when juce_audio_processors is part of the build (gated on JUCE's JUCE_MODULE_AVAILABLE_juce_audio_processors), so they light up automatically in a plugin and are skipped in a plain app. Add your own fields, or rewrite the assembled map last:

config.metadata["app.channel"] = "beta";  // sent as-is; wins on key collisions
config.onCollectMetadata = [] (std::map<std::string, std::string>& m) {
    m["cohort"] = abTestCohort();
};

The collected map flows into moonbase::licensing_options::metadata and is sent with the SDK's requests. When you don't set config.applicationVersion, it auto-fills from JucePlugin_VersionString in a plugin build (or the running app's version otherwise), so telemetry reports a version without extra wiring.

Identifying an integration built on the module

Every request carries a layered User-Agent: the SDK, then this module, then anything a higher-level integration adds. Out of the box:

User-Agent: moonbase-cpp/4.3.1 moonbase-juce/4.3.1 (JUCE v8.0.4; macOS 15.2)

A framework, wrapper or white-label host that embeds the module can add its own segment with config.clientInfo:

config.clientInfo << " HISE/4.1.0";   // append, don't assign
User-Agent: moonbase-cpp/4.3.1 moonbase-juce/4.3.1 (JUCE v8.0.4; macOS 15.2) HISE/4.1.0

Your segment is appended after the module's own, never in place of it, so support and analytics still see which module and SDK version ran underneath. Append with << rather than assigning, so a stack of layers (framework, then a plugin built on it) each keeps its mark.

Use product tokens (Name/Version, with an optional (comment)), keep it ASCII, and keep it short: control characters are stripped and the whole segment is capped at 256 characters before it reaches the header. Unlike the analytics capture above, this is sent on every request and is not gated by config.analytics.enabled; it identifies the software, not the machine or the user.