Custom license fields

You can create as many custom license fields and meta-data to associate with your product keys as you need. You can use theses license fields for your own backoffice purposes (to track users, companies, resellers, etc.). You can also use license fields in your application. After the user has activated, you can read the custom field values within your app.

You can use these fields to limit parts of your app, license individual components or modules, time-limit your app or individual parts of it, etc. With license fields you have absolute control over every piece of your order process and your app.

Possible uses of license fields

There are no bounds to what you can do with license fields. Here are just a few concrete examples of how our customers are using license fields:

• Fields for the customer information (company name, company VAT, etc.)
• Fields for reseller-specific ID's
• Using the fields to enable certain features & plugins in their app depending on what the customer purchased.
• Using the fields to sell their software on a renewal basis (e.g. free updates for a year after purchase with the ability to renew).

In short, you can use the license fields for everything from storing meta-data alongside your product keys to limiting specific features in your app based on what a customer purchased.

Adding a new field

Adding a custom license field is as simple as clicking the "Custom license fields" link on your dashboard or on the sidebar:

You'll be presented with a fields page where you add, edit, and remove your custom fields for that version of your software.

Data types

There are 3 basic types of fields: strings, dates and times, and integers.

String

Strings are the default field type. You can store any data you want in the string field types — there's no limitation.

Date / Time

The Date / Time field types are stored in the form YYYY-MM-DD hh:mm:ss. If you're entering the field data using LimeLM, you'll get a nice date / time picker shown to the right. If you're using web API then you must make sure the data is in the form YYYY-MM-DD hh:mm:ss.

Integer

With the integer license field type you're limited to entering only integers.

How to use license fields in your app

When a user activates your app the fields data is sent along with signed activation data. This means as soon as a user has activated you can use the TurboActivate function GetFeatureValue() to get the field value.

There are many ways you can use license fields in your application, here are just 2 examples:

Example #1: Optional components

A common use of license fields is to make it easy to sell sub-modules or components to your customer. For instance, let's say you're selling your main app "YourApp" and 2 optional subcomponents "ExtensionX" and "ExtensionY". In this example we're going to keep it simple and just say the extensions can either be enabled or disabled.

1. If you haven't already, add your product to LimeLM.
2. Create a new field with the name "ExtensionX", the type of "String", and leave the "Required field" checkbox checked.
3. Do the same for "ExtensionY".

Now, when you create product keys for "YourApp" either using the LimeLM interface or the limelm.pkey.generate web API function then you'll have to set your 2 custom field values "ExtensionX" and "ExtensionY". In this example let's say you set the extension to either "true" or "false".

Inside your application you can read the field value to see if the extensions are enabled. That is, to see if the users have purchased your components use the GetFeatureValue() function. A simple example in C# looks like this:

if (TurboActivate.GetFeatureValue("ExtensionX") == "true")
{
    // the user has purchased your ExtensionX
    //TODO: enable the extension
}
else
{
    // tell the user that they can buy ExtensionX on your website
}

Example #2: SaaS or time limited restrictions

Another popular use of license fields is to limit parts of the app by time. For instance, selling the app (or parts of the app) on a subscription basis. We cover one possibility in the "SaaS and time-limited licensing" article.

The way you limit your app, or any individual part of it, by time is to create a license field of the "Date / Time" type. For example, let's say I create a field named "updates_expires" to represent the date on which the customer can no longer receive free updates.

Seeing if the value is expired in the app

The way to check if the date has expired is to use the GetFeatureValue() function in tandem with the IsDateValid() functon. A simple example in C# looks like this:

if (TurboActivate.IsDateValid(TurboActivate.GetFeatureValue("updates_expires"),
                              TurboActivate.TA_DateCheckFlags.TA_HAS_NOT_EXPIRED))
{
    // the updates_expires date hasn't yet been reached
}
else
{
    // the update period has expired
}

Using license fields on your servers. Example: Limiting updates

You can also use these license fields on your server. If you're using license fields to limit updates to your customers, then you can use these fields to choose whether to send an update file to the customer. Here's a broad overview of how it would be done:

• When your app requests the update file from your server, pass along the customer's product key as part of the request.
• Convert the product key to a product key ID using the limelm.pkey.getID API function.
• Get the field values of the product key using the limelm.pkey.getDetails API function.
• Verifying the "update_expires" field value is a date later than today.
• Deliver the update file requested OR throw an error (403 error code).

This particular example of limiting updates on the server side has a fully written example. If you're using PHP or ASP.NET (C# or VB.NET) use the "\PHP\limit-updates\index.php" file or the "limit-updates.aspx" file for ASP.NET (get the Web API pack on your API page).

Renewing the update subscription

Now let's say the customer's update contract has expired and they want to purchase another year of updates. Making this possible requires 2 steps. On your server side (specifically after the customer has successfully purchased the renewal) you can set the new field value using the limelm.pkey.setDetails web API function. Then, in order for the customer to get that new value on their machine they have to re-activate by calling Activate() again.

Changing fields & getting the changed data in your app

If you change the field data for a product key (either within your LimeLM dashboard or using the limelm.pkey.setDetails web API function) then LimeLM will automatically send this new field data to your customer when they re-Activate. For your app to get the latest field data call Activate(), IsGenuine(), or the IsGenuineEx() function. We recommend calling the IsGenuineEx() function because you can automate how often your app should check for new changes to the license fields on LimeLM.

Example: Customer purchasing an optional component

Let's continue with the example from above. In this example let's also say that a customer purchases "YourApp" but doesn't initially buy your optional components (ExtensionX or ExtensionY). Then after using your program a while, the customer decides to buy your "ExtensionX" optional component.

Here's how you handle the subtleties of enabling optional components for a customer:

Step 1: Purchase page changes

The first thing you need to do is either create a new purchase page that allows users to purchase components for their existing licenses, or modify your existing purchase page to accept the customer's product key for upgrades.

Step 2: Modify the fields for the customer's product key

Now that the customer has purchased your optional component "ExtensionX" you will have to edit the product key to enable the "ExtensionX" license field. You can either manually edit the product key in your LimeLM dashboard. Or you can use the limelm.pkey.setDetails web API function to set the new field value.

Step 3: Re-Activate your app

After the user has purchased the new component and you've set the field value for the customer's product key, now you just have to get this latest field value to your customer. The way you do this is to call the "Activate()" function (or for offline activation use the "ActivationRequestToFile()" and "ActivateFromFile()" functions). This will re-Activate the customer and download the latest field value data.

Get/Set license fields using the web API

When you use either the limelm.pkey.generate or limelm.pkey.setDetails web API functions you can set the field values by using the feature_name[] and feature_value[] arguments. For example let's say you have 2 fields that you want to set:

• first_feature set with the value professional.
• update_expires set with the value 2012-06-25 04:13:16.

To generate a product key you would urlencode the field names and values as follows:

...?method=limelm.pkey.generate&feature_name[]=first_feature&feature_value[]=professional&feature_name[]=update_expires&feature_value[]=2012-06-25%2004%3A13%3A16