C++ Client Library Upgrade Guide

What to check and change in your code when you move to a newer version of the KEYZY C++ Client Library. Each section goes from one version to the next one to move to. Coming from an older version, start at the lowest section that applies and work up to the top. Every change is listed in the Changelog.

Each change carries a likelihood of impact: High means most products need a code change, Medium means some do, Low means few do or the change is optional.

Upgrading to 1.10.2 from 1.9.0

Two breaking changes. Read these first.

High impact

• Breaking, since 1.10.0. Host ID scheme V2 is now the default. V2 identifies a device from more stable hardware information: the host id stays the same through network changes and OS reinstalls.

  • New product: keep the default, V2.
  • Product released on an earlier version: keep V2 and call migrateHostIdV1toV2() on every start (from 1.10.2). Existing users move to V2 without re-activating. See Move a Released Product to Host ID V2.
  • Product sold with offline licenses: keep V1, passed as the last argument:

  Keyzy::ProductData productData("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_PRODUCT_CODE",
                                 "YOUR_CRYPTION_KEY", true, Keyzy::HostIdScheme::V1);

• Breaking, since 1.10.1. KeyzyLicenseValidator::getHostIdHash() no longer throws CannotReadHostIdError. It returns an empty string when the device identifier cannot be read. If you catch the exception around this call, check for an empty string instead.

Low impact

• Since 1.10.1. Creating KeyzyLicenseActivator no longer throws when the device identifier cannot be read. validateOffline() and activateOffline() return CANNOT_READ_HOST_ID instead.
• Since 1.10.1. When a license stops for a reason that can be undone (an expired subscription, a product or SKU switched off), the serial stays on the device. Once the cause is fixed, the user is back without entering it again. To benefit, call activateSemiOnline() without a serial before asking for one; see the semi-online activation tutorial.
• Since 1.10.0. Deprecated: client-only trials (activateClientTrial() and related). Use server-side trials (LicenseDepositHandler::registerTrial()).

Already on 1.10.0 or 1.10.1

The changes above apply to you as well, and one more:

• Since 1.10.2. The recommended upgrade path for a product released on a version before 1.10.0 changed: keep V2 and call migrateHostIdV1toV2() on every start, instead of staying on V1. This needs a change in your start-up flow. Products sold with offline licenses still stay on V1.

The steps are in Move a Released Product to Host ID V2.

Upgrading to 1.9.0 from 1.7.x

Make the changes in this section, then continue with Upgrading to 1.10.2 from 1.9.0. Do not stop at 1.9.0: the version to ship with is 1.10.2.

Two behaviour changes apply as soon as you upgrade from any v1.7.x build:

High impact

• Since 1.8.0. registerTrial() and registerOfflineDistributedLicense() now require a non-empty email. The server made email mandatory on 2026-04-20, and the library mirrors that: an empty email is rejected immediately with EMAIL_VALIDATION, without a network request. If your integration calls either method without an email, supply one before upgrading.

Low impact

• Since 1.8.0. SERIAL_VALIDATION and CODE_VALIDATION were added for per-field validation failures on those two calls. NAME_OR_EMAIL_VALIDATION is deprecated and is no longer produced by the server; it remains in the enum for ABI compatibility.
• Since 1.9.0. Network diagnostic status codes: CONNECTION_ERROR is now refined into NETWORK_DNS_FAILED, NETWORK_REFUSED, NETWORK_TIMEOUT, NETWORK_TLS_FAILED, NETWORK_PROXY_REQUIRED and NETWORK_HOSTS_TAMPERED, so you can show users a specific, actionable message instead of a generic connection error. The change is additive: existing switch (status) code keeps working unchanged, and the new values are only reached once you add explicit cases for them. See the C++ License Status Codes reference.