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::OnlineUnlockStatusbridge? That older, copy-paste reference still lives inexamples/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.
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 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.
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.
#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) { /* … */ });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 toonDiagnostic. 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). Withconfig.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:relclaim) 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 byconfig.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.
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.
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 overloadGate 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();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
exppasses 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
onlineGracePeriodgets 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
onlineGracePeriodis 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.
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; callgrabKeyboardFocus()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) orUnverified(not checked online withinonlineGracePeriod). 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 inconfig.strings(deactivatedTitle,licenseExpiredBody, and so on), andlockReason()goes back toNoneonce a license is loaded. A custom UI can read it fromonLicenseChanged(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).
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.
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.
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 acceptedNew 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.
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 fieldSettings.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.
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.
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 MoonbaseActivationNativeIt 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.
Two automated suites cover the module:
- Behavioral (
tests/juce/) drivesActivationControlleragainst 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-failureThe 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,undefinedCI: 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.
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.
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).
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.
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().
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.openBrowserwhen 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.autoActivateSubProductsis off.
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.
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.
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 folderWhen 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:
- Fetches the release notes (plain text) from
GET /api/customer/inventory/products/{productId}?version={released}. - On "Download", resolves an authenticated, short-lived installer URL from
GET /api/customer/inventory/products/{productId}/download/{platform}/latest?redirect=falseand downloads it intoconfig.downloadDirectorywith 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.
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.
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.
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 assignUser-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.

