Device Variables Usage

Device variables play a crucial role in LicenseSpring's SDKs by facilitating the exchange of data from devices to the vendor platform.

This mechanism allows developers and administrators to gather real-time device-specific information, empowering them to make informed decisions and tailor licensing strategies based on accurate insights.

The aim of this section is to provide you with a comprehensive understanding of effectively utilizing device variables.

Prerequisites

1

Complete the Getting Started tutorial

You should have completed the Getting Started tutorial, including:

• Initialized LicenseManager (or LicenseHandler) with your configuration using the appropriate settings.
• Created a LicenseID using either LicenseID::fromKey or LicenseID::fromUser function, depending on the activation method you prefer.
• Activated a license of any type.
• Implemented routine local and online checks within the application.

Understanding Device Variable Usage

Some examples of scenarios where device variables are useful:

Hardware Specifications

Device variables can be utilized to capture and transmit hardware specifications, such as CPU type, RAM size, and storage capacity.

This information can be invaluable for tailoring licenses based on the user's hardware capabilities.

Tracking User Registration Data

User registration data includes names and user information, which can be sent and kept track of on the LicenseSpring platform using these variables.

This enables you to gather and manage essential user details directly within the licensing framework, streamlining administrative tasks and enhancing user experience.

User Preferences

Store user preferences, settings, and configurations using device variables to create a more personalized and seamless user experience.

Adding Device Variables

Integrating device variables on existing licenses can be done in three different ways.

1

Adding a name-value pair

C++

// 1. Adding a name-value pair
license->addDeviceVariable("Name", "Value", false);

// Finally, to send our variables to the LicenseSpring server:
license->sendDeviceVariables();

C#

// 1. Adding a name-value pair
license.AddDeviceVariable("Name", "Value");

// Finally, to send our variables to the LicenseSpring server:
license.SendDeviceVariables();

Swift

// Swift: send a dictionary of variables
try license.sendDeviceVariables([
    "Name1": "Value1",
    "Name2": "Value2"
])

Python

# 1. Adding name-value pairs (directly supported within set_device_variables)
license.set_device_variables({"a":"b","c":"d"})

# send device variables to LS server
license.send_device_variables()

Go

// Go SDK v2: construct custom fields and send
customFields := []core_request.CustomFields{}
customFields = append(customFields, core_request.CustomFields{Name: "name", Value: "device1"})
err = lh.SendDeviceData(ctx, customFields)

Java

String licenseKey = "<SAMPLE-KEY>";
String licenseIdentity = LicenseIdentity.fromKey(licenseKey);
DeviceVariables variables = DeviceVariables.builder()
  .variable("var1", "value1")
  .variable("var2", "value2")
  .build();

licenseManager.trackVariables(licenseIdentity, variables.getVariables());

JavaScript

const license = licenseManager.loadLicense();
// set variables locally; second parameter determines whether to save locally
license.setDeviceVariablesLocal({ key1: 'value1' }, true);
// sync updated device variables with the server; boolean determines whether to save locally
license.setDeviceVariables(true);

2

Adding a DeviceVariable object

C++

// 2. Adding a DeviceVariable object
DeviceVariable deviceVar = DeviceVariable("Name", "Value");
license->addDeviceVariable(deviceVar, false);

// Finally, to send our variables to the LicenseSpring server:
license->sendDeviceVariables();

C#

// 2. Adding a DeviceVariable object
DeviceVariable deviceVariable = DeviceVariable("Name", "Value");
license.AddDeviceVariable(deviceVar);

// Finally, to send our variables to the LicenseSpring server:
license.SendDeviceVariables();

Swift

// Swift: send a dictionary of variables
try license.sendDeviceVariables([
    "Name1": "Value1",
    "Name2": "Value2"
])

Python

# Using set_device_variables with a mapping supports adding variables
license.set_device_variables({"a":"b","c":"d"})

# send device variables to LS server
license.send_device_variables()

Go

// Go SDK v2: construct custom fields and send
customFields := []core_request.CustomFields{}
customFields = append(customFields, core_request.CustomFields{Name: "name", Value: "device1"})
err = lh.SendDeviceData(ctx, customFields)

Java

String licenseKey = "<SAMPLE-KEY>";
String licenseIdentity = LicenseIdentity.fromKey(licenseKey);
DeviceVariables variables = DeviceVariables.builder()
  .variable("var1", "value1")
  .variable("var2", "value2")
  .build();

licenseManager.trackVariables(licenseIdentity, variables.getVariables());

JavaScript

const license = licenseManager.loadLicense();
// set variables locally; second parameter determines whether to save locally
license.setDeviceVariablesLocal({ key1: 'value1' }, true);
// sync updated device variables with the server; boolean determines whether to save locally
license.setDeviceVariables(true);

3

Adding multiple DeviceVariable objects via vector/array

C++

// 3. Adding multiple DeviceVariable objects via vector
std::vector<DeviceVariable> deviceVariables = {
    DeviceVariable("Name1", "Value1"),
    DeviceVariable("Name2", "Value2")
};
license->addDeviceVariables(deviceVariables);

// Finally, to send our variables to the LicenseSpring server:
license->sendDeviceVariables();

C#

// 3. Adding multiple DeviceVariable objects via array
DeviceVariable[] devVariables = {
    new DeviceVariable("name1", "value1"),
    new DeviceVariable("name2", "value2")
};
license.AddDeviceVariables(devVariables);

// Finally, to send our variables to the LicenseSpring server:
license.SendDeviceVariables();

Swift

// Swift: send a dictionary of variables
try license.sendDeviceVariables([
    "Name1": "Value1",
    "Name2": "Value2"
])

Python

# 1,2,3 are directly supported within set_device_variables
license.set_device_variables({"a":"b","c":"d"})

# send device variables to LS server
license.send_device_variables()

Go

// Go SDK v2
customFields := []core_request.CustomFields{}
customFields = append(customFields, core_request.CustomFields{Name: "name", Value: "device1"})
err = lh.SendDeviceData(ctx, customFields)

Java

String licenseKey = "<SAMPLE-KEY>";
String licenseIdentity = LicenseIdentity.fromKey(licenseKey);
DeviceVariables variables = DeviceVariables.builder()
  .variable("var1", "value1")
  .variable("var2", "value2")
  .build();

licenseManager.trackVariables(licenseIdentity, variables.getVariables());

JavaScript

const license = licenseManager.loadLicense();
// the following sets the variables on the license object; 
// the second (boolean) parameter determines whether to save the changes to the license file:
license.setDeviceVariablesLocal({ key1: 'value1' }, true);
// the following syncs the updated device variables with the server;
// the boolean parameter determines whether to save the changes to the license file:
license.setDeviceVariables(true);

Note: To update a device variable, you can simply add the device variable with the same name and its updated value.

Device variables can also be set on license activation:

C#

DeviceVariable[] deviceVariables = {
    new DeviceVariable("name1", "value1"),
    new DeviceVariable("name2", "value2")
};
LicenseID id = LicenseID.FromKey("license-key-goes-here");
ILicense license = licenseManager.ActivateLicense(id, deviceVariables);

// Offline activation is also supported.
string offlineActivationFile = licenseManager.GetOfflineActivationFile(id, deviceVariables);

C++

std::vector<DeviceVariable> deviceVariables = { {"name1", "value1"}, {"name2", "value2"} };
auto licenseId = LicenseID::fromKey("license-key-here");

auto license = licenseManager->activateLicense(licenseId, deviceVariables);

// Offline activation is also supported.
std::wstring offlineActivationFile = licenseManager->createOfflineActivationFile(licenseId, deviceVariables);

Python

# Only supports offline activations
req_folder = "req_folder_path"

lm.create_offline_activation_file(license_id, req_folder, device_variables={"a":"b","c":"d"})

Java

String licenseKey = "<SAMPLE-KEY>";
String licenseIdentity = LicenseIdentity.fromKey(licenseKey);
DeviceVariables variables = DeviceVariables.builder()
  .variable("var1", "value1")
  .variable("var2", "value2")
  .build();

ActivateOfflineParams params = ActivateOfflineParams
  .builder()
  .variables(variables)
  .build();
  
String file = licenseManager.offlineActivationFile(licenseIdentity, null, params);

JavaScript

const offlineActivationPayload = licenseManager.createOfflineActivationPayload({ variables: { key1: 'value1' } });

Accessing Device Variables

To locate the device variables through the vendor platform, first navigate to your license then to the "Devices" tab.

Device tab where device variables are found.

Next, click on the device variables button to open a list of the device's device variables.

Device Variables button

C++

std::vector<DeviceVariable> device_vec = license->getDeviceVariables(true);

C#

DeviceVariable[] devVariables = license.GetDeviceVariables(true);

Swift

// Just access variables (updated after latest online check).
let existingVariables = license.deviceVariables

// Request variables from the LicenseSpring platform.
let updatedVariables = try license.requestDeviceVariables()

Python

device_var_list = license.get_device_variables(get_from_be=True)

print(device_var_list)

Go

// Go SDK v2
vars, err := lh.GetDeviceVariables(ctx, true)

Java

// Offline: Retrieve Device Variables
License license = licenseManager.getCurrent();
LicenseData data = license.getData();
List<DeviceVariable> variables = data.getVariables();

// Online: Retrieve Device Variables
LicenseIdentity identity = license.getIdentity();
List<DeviceVariable> variables = licenseManager.getVariables(identity);

JavaScript

const license = licenseManager.loadLicense();
// the following line syncs device variables by fetching them from the server
await license.getDeviceVariables();
const variables = license.getDeviceVariablesLocal();

Note: The SDKs can retrieve device variables from either the local license or from the backend. The Boolean parameter passed into the getDeviceVariables function decides where they are retrieved from:

• true gets the device variables from the backend.
• false gets them from the local license.

By default, this parameter is false. If no parameter is passed to this method, it will retrieve from the local license.