Sign up

Trial Licenses

Trial licenses let potential customers try your software for a limited period. KEYZY’s server-side trials are fully managed — you can track who is trialing, extend trial periods, and communicate with prospects.

Since server-side trials go through the KEYZY service, trial licenses follow the same activation and validation flow as perpetual and subscription licenses. The only difference is how the serial number is obtained: your application can request a trial serial directly from the KEYZY server, or you can distribute trial serials through your website or other channels. This tutorial shows how to request and activate a trial serial using the C++ Client Library.

Prerequisites

Setup

Create the activator and obtain the deposit handler and validator:

#include "KeyzyLicenseActivator.h"

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

std::unique_ptr<Keyzy::KeyzyLicenseActivator> pActivator =
    std::make_unique<Keyzy::KeyzyLicenseActivator>(productData);

std::shared_ptr<Keyzy::LicenseDepositHandler> pDepositHandler =
    pActivator->getLicenseDepositHandler();

std::shared_ptr<Keyzy::KeyzyLicenseValidator> pValidator =
    pActivator->getLicenseValidator();

Register a Trial

Use registerTrial() to request a trial license from the KEYZY server. You need to provide the SKU number for your trial SKU. Optionally, you can pass the user’s name and email to track the prospect:

Keyzy::LicenseInfo licenseInfo;

Keyzy::LicenseStatus status = pDepositHandler->registerTrial(
    licenseInfo,
    "YOUR_TRIAL_SKU_NUMBER",
    "Jane Doe",            // optional — licensee name
    "jane@example.com"     // optional — licensee email
);

if (status == Keyzy::LicenseStatus::VALID)
{
    // Trial registered — licenseInfo now contains the trial details
    std::string serialNumber = licenseInfo._serialNumber;
    std::int64_t startTime   = licenseInfo._startTime;
    std::int64_t endTime     = licenseInfo._endTime;
}
else
{
    // Registration failed — see Error Handling section below
}

If successful, the KEYZY server deposits a trial license and returns the serial number along with start and end times.

Activate the Trial

Once you have the trial serial number, activate it using any of the standard activation methods. Semi-online is the most common choice:

status = pActivator->activateSemiOnline(licenseInfo._serialNumber);

if (status == Keyzy::LicenseStatus::VALID)
{
    // Trial activated — unlock your application
}

The trial serial behaves exactly like a purchased serial from this point forward. All standard activation schemas work: semi-online, online, and offline.

Validate the Trial

Validation works the same as any other license. For semi-online activated trials, use offline validation:

Keyzy::LicenseStatus status = pValidator->validateOffline();

if (status == Keyzy::LicenseStatus::VALID)
{
    // Trial is still active
}
else if (status == Keyzy::LicenseStatus::TRIAL_LICENSE_EXPIRED)
{
    // Trial period has ended — prompt the user to purchase
}

Show Remaining Time

Display the remaining trial period to your users:

std::uint64_t daysLeft  = pValidator->getDaysLeft();
std::uint64_t daysTotal = pValidator->getDaysTotal();

// e.g. "5 days left of your 14-day trial"

Tip: Showing the remaining days creates a sense of urgency and helps convert trial users into paying customers.

Duplicate Trial Prevention

KEYZY prevents the same device from activating multiple trial licenses for the same product. If a user tries to register a second trial, registerTrial() returns ANOTHER_TRIAL_LICENSE_ALREADY_ACTIVATED.

Typical Application Flow

auto pActivator = std::make_unique<Keyzy::KeyzyLicenseActivator>(productData);
auto pDepositHandler = pActivator->getLicenseDepositHandler();
auto pValidator = pActivator->getLicenseValidator();

// 1. Check for an existing license (purchased or trial)
Keyzy::LicenseStatus status = pValidator->validateOffline();

if (status == Keyzy::LicenseStatus::VALID)
{
    // License is valid — continue
}
else if (status == Keyzy::LicenseStatus::TRIAL_LICENSE_EXPIRED)
{
    // Trial expired — show purchase prompt
}
else
{
    // No valid license — offer trial or activation
    // If user wants to try:
    Keyzy::LicenseInfo info;
    status = pDepositHandler->registerTrial(info, "YOUR_TRIAL_SKU_NUMBER");

    if (status == Keyzy::LicenseStatus::VALID)
    {
        pActivator->activateSemiOnline(info._serialNumber);
    }
    else if (status == Keyzy::LicenseStatus::ANOTHER_TRIAL_LICENSE_ALREADY_ACTIVATED)
    {
        // Already trialed — show purchase prompt only
    }

    // If user has a purchased serial:
    // pActivator->activateSemiOnline(purchasedSerial);
}

Collecting Contact Information

The name and email parameters in registerTrial() are optional but highly recommended. Collecting contact information during trial registration allows you to:

You can view all trial registrations and their contact information on the Licenses page in the dashboard.

Error Handling

The most common LicenseStatus values for trial operations are ANOTHER_TRIAL_LICENSE_ALREADY_ACTIVATED, TRIAL_LICENSE_EXPIRED, TRIAL_LICENSE_NOT_STARTED, NO_FREE_LICENSES, and SKU_NOT_ACTIVE.

For the complete list of all status codes and their descriptions, see the C++ License Status Codes reference.

Next Steps