Documentation · SoftActivate Licensing

Automatic trials

An automatic trial lets anyone who downloads your application try it without asking you for a key. You build one public trial key into the application, and the application activates it on its first run. Each machine then gets its own trial period, 30 days by default, counted from that machine's first activation. The customer types nothing.

A trial is a setting of the product: switching it on creates the product's trial license, and that license's key is the trial key. The trial license is an ordinary license with trial terms, so activation, validation and renewal work as they do for any license. It works with SDK 1.1.0 and later. SDK 1.2.0 adds a few conveniences, noted below.

Turning trials on for a product

In the product's form (Products, then Create, or Edit on a product), tick Enable trial support in the license settings. Two fields appear:

  • Trial length (days): how long each machine's trial lasts, counted from its first activation. 30 by default.
  • New trial on the same machine after (days): how many days after a machine's trial ended it may start a new one. 365 by default; 0 or empty means one trial per machine.

Saving the product creates its trial license. Its other terms come from the product's license settings:

  • no limit on the number of machines;
  • Allow virtual machines, as set on the product (virtual machines);
  • the product's Maximum offline period: a machine in its trial renews its certificate online at least that often, as the devices of any license do. A floating product's seat lease is not an offline period, so the trial of a floating product gets none;
  • the license metadata: the product's own, plus "edition": "trial".

The product's page then has a Trial section:

  • the trial key in full, with Copy. The key ships inside every copy of your application, so it is public anyway, which is why it is the one key the console shows;
  • Trial length and New trial after, such as "30 days" and "365 days" ("Never" when each machine gets one trial);
  • Trial devices, whose View link opens the trial license's page.

A product has one trial. When you save the product, its trial license follows the changes: the trial length, the new-trial window, Allow virtual machines, the Maximum offline period and the metadata. A new trial length reaches every machine at its next contact with the licensing service, so trials already running get longer or shorter.

Deleting the product leaves its trial license in place, like the product's other licenses: copies of your application that carry the trial key keep starting and validating trials. To stop them, switch trials off first (stopping trials).

Building it into your application

At every start, the application picks its key: the purchased key once the customer has bought, the built-in trial key until then. The rest is the usual validation call (activation and validation). On the first run there is no stored license, so the call activates the trial key and this machine's trial begins. Save the updated license whenever the SDK issues one, as for any license.

C++

#include "softactivate/sws_licensing.h"
#include <ctime>
#include <fstream>
#include <memory>
#include <sstream>
#include <string>

// built into the application: the product's trial key (emailed to you when you created it)
const char* TRIAL_KEY = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX";

// a whole file as a string; "" when there is none
auto read_file = [](const char* path) {
    std::ifstream file(path);
    std::stringstream buffer;
    buffer << file.rdbuf();
    return buffer.str();
};

auto client = sws::licensing::client::create(endpointUrl);
client->set_metadata("trusted_domain", trustedDomain);
client->set_vendor_id(vendorId);
client->set_product_id("YOUR_PRODUCT_ID");

// the purchased key, saved when the customer buys; empty until then
std::string purchased = read_file("purchased-key.txt");
bool trial = purchased.empty();
client->set_license_key(trial ? TRIAL_KEY : purchased.c_str());

// the stored license: none on the first run, or after a reinstall
auto params = client->create_license_validation_params();
std::unique_ptr<sws::licensing::license> stored;
std::string stored_data = read_file("license.dat");
if (!stored_data.empty())
{
    stored = std::make_unique<sws::licensing::license>(stored_data.c_str());
    params->set_license(stored);
}

// with no stored license, this starts this machine's trial, or resumes it
auto result = client->validate_license(params);

auto updated = result->get_updated_license();
if (updated)
    std::ofstream("license.dat") << updated->serialize();

int status = result->get_status();

if (status == SWS_LICENSE_STATUS_VALID)
{
    auto& current = updated ? updated : stored;

    // a trial license's metadata carries "edition": "trial"
    const char* edition = current->get_license_metadata_value("edition");

    if (edition && std::string(edition) == "trial")
    {
        // a trial license expires at the last moment of this machine's trial
        long long days_left = (current->get_expiration_date() - std::time(nullptr)) / 86400;
        // show "N days left in your trial" and a Buy button
    }
}
else if (trial && (status == SWS_LICENSE_STATUS_EXPIRED ||
                   status == SWS_LICENSE_STATUS_REVOKED))
{
    // this machine's trial is over (EXPIRED), or you stopped all trials by revoking
    // the trial license (REVOKED): show your purchase page
}
else
{
    // as for any license (statuses reference); on a first run, UNAVAILABLE with the
    // error code "new_device_limit" means: try again after midnight UTC
}

// on purchase: activate the purchased key with no stored license first; only when that
// succeeds, save the key and write its license over license.dat (see "Buying")

C#

using System;
using System.IO;
using SWS.Licensing;

// built into the application: the product's trial key (emailed to you when you created it)
const string TrialKey = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX";

using var client = new LicensingClient(endpointUrl)
{
    VendorId = vendorId,
    TrustedDomain = trustedDomain
};
client.SetProductId("YOUR_PRODUCT_ID");

// the purchased key, saved when the customer buys; empty until then
string purchased = File.Exists("purchased-key.txt")
    ? File.ReadAllText("purchased-key.txt").Trim()
    : "";
bool trial = purchased.Length == 0;
client.LicenseKey = trial ? TrialKey : purchased;

// the stored license: none on the first run, or after a reinstall
License? stored = File.Exists("license.dat")
    ? License.Parse(File.ReadAllText("license.dat"))
    : null;

// with no stored license, this starts this machine's trial, or resumes it
LicenseValidationResult result = await client.ValidateLicenseAsync(stored);

if (result.UpdatedLicense != null)
    File.WriteAllText("license.dat", result.UpdatedLicense.Serialize());

if (result.IsValid)
{
    License current = result.UpdatedLicense ?? stored!;

    // a trial license's metadata carries "edition": "trial"
    if (current.GetMetadataValue("edition") == "trial")
    {
        // a trial license expires at the last moment of this machine's trial
        int daysLeft = (int)(current.ExpirationDate - DateTimeOffset.UtcNow).TotalDays;
        // show "N days left in your trial" and a Buy button
    }
}
else if (trial && (result.Status == LicenseStatus.Expired ||
                   result.Status == LicenseStatus.Revoked))
{
    // this machine's trial is over (Expired), or you stopped all trials by revoking
    // the trial license (Revoked): show your purchase page
}
else
{
    // as for any license (statuses reference); on a first run, Unavailable with the
    // error code "new_device_limit" means: try again after midnight UTC
}

// on purchase: activate the purchased key with no stored license first; only when that
// succeeds, save the key and write its license over license.dat (see "Buying")

VB.NET

Imports System
Imports System.IO
Imports SWS.Licensing

' built into the application: the product's trial key (emailed to you when you created it)
Const TrialKey As String = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"

Using client As New LicensingClient(endpointUrl) With {
    .VendorId = vendorId,
    .TrustedDomain = trustedDomain
}
    client.SetProductId("YOUR_PRODUCT_ID")

    ' the purchased key, saved when the customer buys; empty until then
    Dim purchased As String = If(File.Exists("purchased-key.txt"),
                                 File.ReadAllText("purchased-key.txt").Trim(), "")
    Dim trial As Boolean = (purchased.Length = 0)
    client.LicenseKey = If(trial, TrialKey, purchased)

    ' the stored license: none on the first run, or after a reinstall
    Dim stored As License = Nothing
    If File.Exists("license.dat") Then
        stored = License.Parse(File.ReadAllText("license.dat"))
    End If

    ' with no stored license, this starts this machine's trial, or resumes it
    Dim result As LicenseValidationResult = Await client.ValidateLicenseAsync(stored)

    If result.UpdatedLicense IsNot Nothing Then
        File.WriteAllText("license.dat", result.UpdatedLicense.Serialize())
    End If

    If result.IsValid Then
        Dim current As License = If(result.UpdatedLicense, stored)

        ' a trial license's metadata carries "edition": "trial"
        If current.GetMetadataValue("edition") = "trial" Then
            ' a trial license expires at the last moment of this machine's trial
            Dim daysLeft As Integer = CInt(Math.Floor(
                (current.ExpirationDate - DateTimeOffset.UtcNow).TotalDays))
            ' show "N days left in your trial" and a Buy button
        End If
    ElseIf trial AndAlso (result.Status = LicenseStatus.Expired OrElse
                          result.Status = LicenseStatus.Revoked) Then
        ' this machine's trial is over (Expired), or you stopped all trials by revoking
        ' the trial license (Revoked): show your purchase page
    Else
        ' as for any license (statuses reference); on a first run, Unavailable with the
        ' error code "new_device_limit" means: try again after midnight UTC
    End If
End Using

' on purchase: activate the purchased key with no stored license first; only when that
' succeeds, save the key and write its license over license.dat (see "Buying")
  • Days left. The license's expiration date is this machine's trial end: get_expiration_date() (unix seconds) in C++, License.ExpirationDate in .NET (SDK 1.4.0 and later). get_offline_expiration_date() / License.OfflineExpirationDate says until when the trial keeps validating offline (the two dates).
  • Trial or purchased license. SDK 1.2.0 says so directly: is_trial() in C++, License.IsTrial in .NET. With SDK 1.1.0, the license metadata tells them apart: the trial license's metadata carries "edition": "trial". Read it with get_license_metadata_value("edition") in C++, and with License.GetMetadataValue("edition") or the whole License.Metadata in .NET (product binding).
  • Online once. The first run needs a connection, as every activation does. After that, the trial validates on the machine itself, offline included, until its end. With a Maximum offline period on the product, the machine also renews online within each period, as for any license.

What your customer sees

  • The first run: nothing to type. The application activates the built-in trial key, and the trial starts.
  • During the trial: the application validates as with any license, and can show the days left.
  • At the end: validation returns EXPIRED on this machine. Show your purchase page. Other machines are unaffected: each one's trial ends on its own date.
  • After buying: the purchased key replaces the trial key (buying).

Following trials in the console

Trial devices, on the product's page, opens the trial license's page. It lists every device that started a trial, with when its trial started and when it ends (licenses). From there you can:

  • Extend one device's trial. Extend… on the device's row adds 1 to 365 days to that device's current trial, an ended one included, and the row shows "+N days". The device picks up its new end at its next contact with the service, and at the latest when its current certificate expires and the SDK renews it. Other devices are unaffected. There is no "end now" for a single device: a trial certificate keeps validating offline until its own end. To stop every trial, switch trials off on the product (stopping trials).
  • See which machines bought. When a machine in a trial later activates a purchased license of the same product, its row on the trial license reads converted, and its tooltip names the purchased license. Conversions are recorded for the product's current trial license: after trials were switched off and on again, a machine that tried the earlier key is not marked when it buys.

Elsewhere, trial activity stays out of the way: the Notifications page shows it only when Show trial activity is switched on, and the dashboard shows trial starts as a figure of their own under Activations (7d), when there were any. The Trial funnel report, on the Reports page, counts trial starts and conversions over a period, day by day, with the conversion rate (reports).

Webhooks

If your systems receive the console's outbound webhooks (Settings → Webhooks), two events follow trials:

  • trial.started: a device began a trial. Its data carries license_id (the trial license), sku_id, device_id, started_at, and ends_at.
  • trial.converted: a machine in a trial activated a purchased license of the product. Its data carries trial_license_id, license_id (the purchased license), sku_id, device_id, and converted_at.

device_id is the licensing service's id for the machine: the same machine has the same id in both events.

Reinstalls, hardware changes, and virtual machines

A machine's trial period starts at its first activation and ends Trial length days later. If you set a Valid to date on the trial license, no trial runs past it: on a trial license, Valid to reads as "the last day any trial may run".

What keeps that end, and what starts a new trial:

  • Repeat runs and renewals keep the same end.
  • Reinstalling your application, which deletes the stored license file, keeps the same end: the next start activates again and gets the same trial back.
  • Deactivating and then activating again keeps the same end, because a deactivation no longer makes the service forget the machine (hardware IDs).
  • Routine hardware changes keep the same machine.
  • A different machine is a new device, with its own trial.

What counts as a different machine depends on the platform:

Platform A new device, with its own trial
Windows A different computer. Reinstalling the operating system keeps the same device.
Linux A different computer, or a reinstalled operating system.
WSL2 (SDK 1.3.0 and later) A new installation of the distribution. Restarting WSL or Windows keeps the same device.
macOS A different computer.
AWS and GCP instances A new instance.

So a new virtual machine, a copied virtual machine that is given a new identity, a new cloud instance, or a newly installed WSL distribution gets a fresh trial. Other licensing vendors document the same class of limit.

To keep virtual machines out of your trials, untick Allow virtual machines in the product's license settings. It is an ordinary license setting, so it applies to the product's licenses and to its trial alike: a new device that reports running in a virtual machine cannot activate, and the service answers HTTP 403 vm_not_allowed. Devices already activated keep working, machines in their trial included. The common hypervisors and cloud platforms are recognised, and SDK 1.3.0 and later also count WSL2 (Windows Subsystem for Linux 2) as a virtual machine; a physical PC that uses virtualization-based security does not count as one. SDK 1.2.0 and later send this report. SDK 1.1.0 does not, so devices running it are never refused.

Setting the device clock back keeps a time-limited certificate, a trial certificate included, validating within its window while the device stays offline, as for any license. Clock-rollback detection is not offered yet. A Maximum offline period on the product shortens that window for its trial machines: their certificates end at the offline period, and a renewal goes by the licensing service's clock.

Limits and abuse bounds

The trial key is public: anyone who has your application has the key. All it buys is a trial certificate for the machine whose fingerprint is presented, and the SDK checks that fingerprint against the real machine at every validation, so a certificate requested for an invented machine is useless on a real one. Mass requests are bounded by the activation service's limit per IP address (60 requests a minute), by the daily cap on new trial machines, and by monitoring.

The daily cap is 1,000 new machines a day per product. If your application needs more, write to support@softactivate.com with the product's Reference Id. Virtual machines are a setting of the product (virtual machines); a change applies from the next new device on.

Trial devices are not active devices. They do not appear in the active-device count, are never billed, and do not count toward your plan's device limit (plan and billing). A flood of requests therefore costs you nothing you pay for. The worst it can do is use up a day's cap: new machines then get "try later" until midnight UTC (HTTP 429 new_device_limit, which SDK 1.1.0 reports as UNAVAILABLE). Renewals and returning devices are never capped, so machines already in their trial carry on.

Your own SoftActivate Licensing plan matters in one case. When your account's own 30-day trial has ended without a subscription, no new trial device starts (HTTP 402 payment_required with the reason trial_expired, reported as PAYMENT_REQUIRED), exactly as no new device of any license activates. Devices already in their trial keep renewing.

Weak fingerprints

A device that cannot be identified reliably enough to recognise it again is refused with HTTP 403 device_unidentifiable, which the SDK reports as NOT_FOUND. The usual case was a .NET application published with Native AOT on SDK 1.1.0, running on some Windows machines. SDK 1.2.0 and later identify those machines reliably, so upgrade, or publish trial builds without Native AOT (publishing your app).

Buying

When the customer buys, they enter the purchased key. Activate it before changing anything on disk, so that a mistyped key never costs the customer a working trial:

  1. Set up a client as at startup, but with the purchased key, and validate with no stored license. That activates the purchased key on this machine.
  2. Only if the status is VALID, save the purchased key and write the returned license over the stored trial license.
  3. Otherwise, leave the trial license as it is and tell the customer why. A mistyped key gives NOT_FOUND with the error code license_not_found, and the error code names any other cause (why an activation failed).

The trial license must not stay on disk as the stored license for the purchased key. The SDK validates a stored license only under the key it was issued for, so the trial license under the purchased key gives BAD_CONTEXT, without asking the service. Writing the purchased license over it on success takes care of that.

C++

#include "softactivate/sws_licensing.h"
#include <fstream>
#include <string>

// the customer bought and entered the key from their purchase email (customerLicenseKey):
// a client set up as at startup, but with the purchased key
auto client = sws::licensing::client::create(endpointUrl);
client->set_metadata("trusted_domain", trustedDomain);
client->set_vendor_id(vendorId);
client->set_product_id("YOUR_PRODUCT_ID");
client->set_license_key(customerLicenseKey);

// validate with NO stored license: this activates the purchased key on this machine.
// Never pass the trial license here: the SDK validates a stored license only under the
// key it was issued for, so the trial license would give SWS_LICENSE_STATUS_BAD_CONTEXT.
auto params = client->create_license_validation_params();
auto result = client->validate_license(params);
auto purchased = result->get_updated_license();

if (result->get_status() == SWS_LICENSE_STATUS_VALID && purchased)
{
    // only now: keep the purchased key, and write its license over the trial license
    std::ofstream("purchased-key.txt") << customerLicenseKey;
    std::ofstream("license.dat") << purchased->serialize();
}
else
{
    // nothing on disk changed, so the trial goes on; tell the customer why, from the
    // error code: "license_not_found" is a mistyped key, "network" means no connection
    std::string code = result->get_error_code();
}

C#

using System.IO;
using SWS.Licensing;

// the customer bought and entered the key from their purchase email (customerLicenseKey):
// a client set up as at startup, but with the purchased key
using var client = new LicensingClient(endpointUrl)
{
    VendorId = vendorId,
    TrustedDomain = trustedDomain,
    LicenseKey = customerLicenseKey
};
client.SetProductId("YOUR_PRODUCT_ID");

// validate with NO stored license: this activates the purchased key on this machine.
// Never pass the trial license here: the SDK validates a stored license only under the
// key it was issued for, so the trial license would give LicenseStatus.BadContext.
LicenseValidationResult result = await client.ValidateLicenseAsync(null);

if (result.IsValid && result.UpdatedLicense != null)
{
    // only now: keep the purchased key, and write its license over the trial license
    File.WriteAllText("purchased-key.txt", customerLicenseKey);
    File.WriteAllText("license.dat", result.UpdatedLicense.Serialize());
}
else
{
    // nothing on disk changed, so the trial goes on; tell the customer why, from the
    // error code: "license_not_found" is a mistyped key, "network" means no connection
    string? code = result.Error?.Code;
}

VB.NET

Imports System.IO
Imports SWS.Licensing

' the customer bought and entered the key from their purchase email (customerLicenseKey):
' a client set up as at startup, but with the purchased key
Using client As New LicensingClient(endpointUrl) With {
    .VendorId = vendorId,
    .TrustedDomain = trustedDomain,
    .LicenseKey = customerLicenseKey
}
    client.SetProductId("YOUR_PRODUCT_ID")

    ' validate with NO stored license: this activates the purchased key on this machine.
    ' Never pass the trial license here: the SDK validates a stored license only under the
    ' key it was issued for, so the trial license would give LicenseStatus.BadContext.
    Dim result As LicenseValidationResult = Await client.ValidateLicenseAsync(Nothing)

    If result.IsValid AndAlso result.UpdatedLicense IsNot Nothing Then
        ' only now: keep the purchased key, and write its license over the trial license
        File.WriteAllText("purchased-key.txt", customerLicenseKey)
        File.WriteAllText("license.dat", result.UpdatedLicense.Serialize())
    Else
        ' nothing on disk changed, so the trial goes on; tell the customer why, from the
        ' error code: "license_not_found" is a mistyped key, "network" means no connection
        Dim code As String = result.Error?.Code
    End If
End Using

Stopping trials

To stop all trials at once, untick Enable trial support on the product, save, and confirm with Stop trials. Revoke on the trial license's page does the same. From that moment no new device starts a trial and no device renews: the service answers HTTP 403 license_revoked, which the SDK reports as REVOKED, and the product's Trial section says when trials stopped. Trial certificates are never put on the revocation list, because a trial license may have tens of thousands of devices, so a trial already running keeps validating until its certificate ends at the latest: the trial's own end, or sooner when the product sets a Maximum Offline Period (revocation). The startup code above shows the purchase page for REVOKED, as it does for EXPIRED.

Ticking Enable trial support again creates a new trial license, with a new key. The earlier key stays refused, so build the new one into your application.

For a planned end, set a Valid to date on the trial license instead (Edit on its page). No trial runs past it, including the ones already running.

A new trial for a new major version

A trial key belongs to one product. To give every machine a fresh trial of a new major version, give that version a product of its own (for example "MyApp 2") with trial support, and build that product's trial key into the new version. The earlier version's trials carry on. Switching trials off and on again on the same product also gives a new key, but it stops the earlier key's trials.

Within one trial license, a machine may start a new trial period once its last one ended more than New trial on the same machine after (days) ago: 365 days by default, and never when the field is 0 or empty.

Statuses you may see

On top of VALID, a trial brings these statuses. The error code comes from get_error_code() in C++ or result.Error.Code in .NET (why an activation failed).

  • EXPIRED: this machine's trial is over (HTTP 403 license_expired, whose expired_at field gives the end). Show your purchase page.
  • UNAVAILABLE with the error code new_device_limit: the product's daily cap on new trial machines is reached (HTTP 429). The machine can start its trial after midnight UTC, so ask the customer to try again later.
  • NOT_FOUND with the error code device_unidentifiable: this device's fingerprint is too weak to recognise again (weak fingerprints).
  • NOT_FOUND with the error code vm_not_allowed: the product does not allow virtual machines, and this new device reported running in one (virtual machines). Only SDK 1.2.0 and later can get this status.
  • REVOKED: you switched the product's trials off, or revoked the trial license (stopping trials).

Every other status means what it means for any license; see the statuses and errors reference.