Home >

Blog >

Working with Custom Fields and Device Variables

Custom Fields and Device Variables: Tutorial and Implementation Guide

Published on: August 12, 2022

Table of Contents:

Custom fields are a component of the LicenseSpring SDK that allow users to send data from LicenseSpring to your application at the license level. Device variables operate in the other direction, allowing the transfer of data back into the platform from the device level. In this tutorial, we will learn the basics of custom fields and device variables using the LicenseSpring SDK.

Follow the linked video for an overview on LicenseSpring’s Custom Fields and Device Variables:

This guide will walk you through implementing custom fields and device variables within the LicenseSpring SDK. By the end of this tutorial, you should understand how to send data from LicenseSpring to a device and from a device back to the platform. We will also examine useful scenarios for these tools, the interactions between local license files and custom fields, caching and sending device variables periodically, and device variable caveats when using offline licensing. We will create a basic program that lists current custom fields, creates device variables, and lists existing device variables. You can find the sample C++ console program here.

In order to set up custom fields to follow this tutorial, follow the guide given at the link below:

.Custom Fields - Documentation (licensespring.com)

In this tutorial, we will discuss:

Useful Scenarios
Local License Files and Custom Field Interactions
Pushing Device Variables
Caching/Sending Device Variables Periodically
Accessing Device Variables within the Program
Device Variables Caveats When Using Offline

Useful Scenarios

Defining a License/Product type:

You can have a custom field, for multiple products, all with the same custom field key, but with different values to differentiate between products. Thus, you only require very minimal code changes between product types (product code + maybe key + user info depending on how it is implemented). Furthermore, if you ever decide to change the name of the product, it can be changed by simply creating a custom field for your product name, and updating it on the LicenseSpring platform.

Notifications:

You can create a Custom Field object where the key is ‘Notification’ and the value can be your notification message. Then, if you want to change your message, you can simply go into your product’s custom fields, find the key: ‘Notification’ and update the value with your new message. When the user updates their license (by performing an online license check), then the new notification message will be updated as well.

Other Uses:

Wanting to send/keep track of user registration data (name, user info) on the LicenseSpring platform using Device Variables
Using the value of a custom field to configure the edition that should be available to the end-user without needing to distribute separate binaries. For example, a field called “LicenseType” could have a value of “lite”, “standard” or “pro”. A different edition of the application can be made available for the end user, depending on which value is used for the custom field for a given license.

Behavior of the Local License File with Custom Fields

A custom field is just a key-value pair. The local license will hold all the custom field data. You can access this data using:

cpp

csharp

java

std::vector<CustomField> customFields = license->customFields();

When you activate your license (online or offline) and create a local license file, all the custom fields will be found on the local license file. However, since custom fields can be added, removed or updated after a license has already been issued and activated, the other way to update your local license file with any newly added, removed or updated custom fields is to perform an online check using:

cpp

csharp

java

license->check();

Or, in the case of an offline license, use the offline refresh response file, see our Offline Tutorial for more information.

Creating and Pushing Device Variables to LicenseSpring

Device variables are a way to transfer data from the end-user’s machine, at the device level, to the LicenseSpring platform. We can send these key-value pairs to the LicenseSpring server, which will display our data. Unlike custom fields, any device variables present on the LicenseSpring server will not be transferred to your local license file when you run an online check or activate your license.

cpp

csharp

java

//We can add device variables to our license object, but not save it to our file
license->addDeviceVariable( "Name", "Value", false );
//Or if we want to add many variables at a time we can do:
std::vector<DeviceVariable> deviceVariables = { DeviceVariable( "Name1", "Value1" ), DeviceVariable( "Name2", "Value2" ) };
//Finally, to send our variables to the LicenseSpring server:
license->sendDeviceVariables();

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

Caching and Sending Device Variables Periodically

In the C++ SDK, it is possible to store device variables locally on the device's local license file. Since these device variables are not restricted to memory, they can be accessed at any time. So, to send device variables periodically, in your code, you just need to set up the code to send the device variables to the LicenseSpring server on some sort of interval.

cpp

1
2

//We can add these device variables to our local license file where they will stay cached
license->addDeviceVariable( "Name", "Value" );

Accessing Device Variables within the Program

The C++ SDK also has the capabilities to retrieve these device variables from within the program. As stated earlier, running online checks will not bring any device variables onto your local license file. You will need to use:

cpp

//Retrieve list of device variables from the LicenseSpring server for this device
std::vector<DeviceVariable> device_vec = license->getDeviceVariables( true );
//Retrieve list of device variables from local license file on this device
std::vector<DeviceVariable> device_vec = license->getDeviceVariables( false );

It is important to note that you can pull device variables from the LicenseSpring servers, or from your local license file. If these two files are out of sync, then you may need to pull device variables from both ends to get a full list.

If the device variable is on your local license file, you can retrieve it with the following:

cpp

//Collect a single device variable from your local license file using its key
DeviceVariable dv = license->deviceVariable( "device variable name" );
//Collect the value of a single device variable from your local license file using its key
std::string value = license->deviceVariableValue( "device variable name" );

Device Variable Caveats with Offline Licensing

For offline licensing, we can still add device variables, although they will require a bit more work. First, it is important to note that you can only add device variables after creating a local license on your device. That will require you to submit and obtain your offline activation request and response file respectively, see our Offline Tutorial for more details. As of August 12, 2022, offline deactivation will not upload your device variables to the LicenseSpring server, so it is recommended to save the device variables to your local license, and upload them when the device has access to the internet.

Note: As of August 15, 2022, offline deactivation for the C++ SDK ver. 7.17.0 will now transfer device variables back to the LicenseSpring servers upon uploading their deactivation request file.

Conclusion

You should now have a thorough understanding of what custom fields and device variables are. You should also have an idea of what they can be used for, and how they can be implemented into your projects.

FAQ

Q: Does changing my custom fields on the platform change the values for all my license?

Yes and no. Custom fields are created on the product level. Here you can create key-value pairs. Every license you create under this product will share this same key and value when created. These key value pairs cannot be deleted on the license level, and the keys cannot be altered. The values however can be altered on the license level, changing this will not affect any other licenses issued under the same products. On the product level, you can also alter the custom fields. Adding, deleting, or changing a key will reflect on every license under this product. However, changing the value of a key-value pair has slightly different effects. If that value has been altered on the license level, then it will not be affected if altered on the product level. If that value has not been altered on a license, then that license will reflect whatever value changes are made on the product level.

Q: Are there any other ways to retrieve device variables outside of the C++ SDK?

Yes. Here is the documentation on how to retrieve device variables from the LicenseSpring backend by using our license API.

William Gong