License Key Generators

A License Key Generator allows you to create customized licensing information for customers at the time of purchase. Unlike license key lists, these licenses are not pre-generated. Rather, when the customer clicks 'Buy', the Cleverbridge platform calls your license key generator, submits the purchase details, and requests the license information back as a response.

This offers you the following advantages:

  • Manual effort is not required any longer to regularly upload additional license key lists.
  • The license can include information about the customer. This helps reduce software piracy because customers are less likely to pass this information on to someone else.

Simulate a License Key Generator Call

when Cleverbridge wants to generate a license key for your product, we make a HTTP(S) POST request of a web form to a URL that is hosted on your web server. Your server then takes the submitted data, generates the license, and returns it in the response to Cleverbridge.

To simulate what happens when Cleverbridge calls your web key generator, do the following:

  1. Download the following sample HTML page: https://www.cleverbridge.com/ca/LicenseGeneratorTest.html
  2. Replace the URL in the <form> tag with your key generator URL.
  3. Click the Send button. You will receive the data in HTTP POST variables. This is the same data that Cleverbridge receives when it calls your key generator.

References

Field Descriptions

The data submitted in web key generator calls is form-encoded with the following fields:

Field Description
XML/JSON

The XML or JSON notification document for this purchase.

Note

The XML or JSON notification document used in web key generator calls is identical to the PaidOrderNotification, with the exception of the Deliveries Array.
RUNNING_NO The position of the item in the shopping cart.
PRODUCT_ID The Cleverbridge ID of the product purchased.
PURCHASE_ID The order reference number.
PURCHASE_DATE The date of the key generation call. The format is dd/mm/yyyy.
QUANTITY The quantity of the product purchased.
EMAIL The licensee’s email address.
COMPANY The licensee’s company name, if available.
FIRSTNAME The licensee’s first name.
LASTNAME The licensee’s last name.
REG_NAME The licensee’s company name. If none is provided, the licensee’s first and last names are used.
STATE The licensee’s state.
COUNTRY The licensee’s country.
INTERNAL_PRODUCT_ID The internal product ID of the purchase item.
AFFILIATE_ID The affiliate ID of the purchase item.

Important

By default, data submitted in web generator calls no longer contains unnecessary PII (Personally Identifiable Information). However, if you would like us to submit specific contact information to your key generator, you may receive the following:

Field Description
PHONE The licensee’s phone number.
FAX The licensee’s fax number.
STREET The licensee’s street.
CITY The licensee’s city.
ZIP The licensee’s postal code.

If you currently receive this data and would like us to discontinue submitting it to your key generator, contact Client Experience.

For more information about these changes, see Ensure Global Compliance.

XML/JSON Definitions

For more information about the definitions of the XML or JSON document submitted in the POST request, see Schema Definitions for Notifications.

Implement License Key Generator

To implement a simple license key generator, you can use the following:

Resources for Setting Up a Generator

In the following example, you can see how a simple license key generator can be implemented in PHP:

keygen.php

To understand more about the basic concept, see the following:

keygen2.php

In this example, the PHP license key generation environment includes the class cbNotification to easily extract information from the XML notification.

Tip

PHP offers a simple way to handle the XML document used in key generation. PHP versions 5 and above also include XPATHing based on the following:

http://www.php.net/manual/en/ref.dom.php

Note

By default, XML Processing with ASP.NET does not accept FORM data that contains HTML/XML tags. This causes an error message when we call your ASP.NET license key generator with our XML data. This applies to ASP.NET versions 1.1 and above.

You can find additional information on this topic at:

http://www.asp.net/faq/RequestValidation.aspx

To circumvent this problem, add the following line to your ASP.NET script:

<%@ Page validateRequest="false" %>

Formatting Options for Licenses

You can offer licenses in the following ways:

To designate a license as a text license, the license key generator has to set the HTTP header Content-Type to text/html or text/plain. The Cleverbridge system includes the license information in the order confirmation pageClosed The confirmation page is displayed after a customer makes a purchase. The confirmation page contains the order confirmation and delivery information. and the confirmation email that is sent to the customer.

A license key generator can create a license that the customer must download as a file. A license file is triggered by any HTTP Content-Type other than text/html and text/plain. To ensure that a download process is initiated when the customer clicks the license, we recommend a Content-Type of application/octet-stream.

When returning a file license, the license key generator also returns the file name of the license in the HTTP header. You can do this with the HTTP header Content-Disposition.

Use the following format for the Content-Disposition value:

attachment; filename="<filename>"

Replace <filename> with the file name you would like to use. The file name can only contain alphanumeric characters (no umlauts, e.g. ä, ö, ü) and the following special characters: . _ -

The maximum file size for file licenses is 100 KB. If you need a bigger file license response, contact Client Experience.

Tip

If you need to provide instructions with your license key, you have two options:

  1. Return Instructions as Part of License:

    Because Cleverbridge forwards the license information to the customer, you can also simply return these instructions as part of the license. A drawback to this approach is that the key cannot be used later for additional processing by Cleverbridge (for example, printing it on a backup CD/DVD).

  2. Define a Template:

    Enter the instructions in a template. For more information, see Define a License Key Template.

HTTP Response Code Information

Cleverbridge considers any content returned with a HTTP response code 200 a valid license key. In case you run into technical problems generating the license key, you should provide a response code in the 400 or 500 range. If Cleverbridge receives a response code in this range, we will inform the customer that the completion of the transaction will be delayed. After that, we will initiate a retry once the license key generation issue is resolved.

Security Methods

Your license key generator can be secured in two different ways:

Cleverbridge recommends that you protect your license key generator URL with a username and password. If you choose this method, you must specify this information when you configure your license key generator in the Subscription Commerce Manager. For more information, see Add a License Key Generator.

Cleverbridge does not recommend protecting your license key generator by restricting IP addresses. This only offers limited security and can create problems when requested changes cannot be implemented in time. However, you can limit the IP ranges from which your license key generator can be accessed. Cleverbridge accesses from one of the following networks:

  • 185.55.69.129 - 185.55.69.158
  • 185.55.70.33 - 185.55.70.62

These IP ranges are subject to change, but we will alert you in advance of any alterations.

Define a License Key Template

Cleverbridge offers you the option to define a template for your license key. To set up a template in the Subscription Commerce Manager, do the following:

  1. In the Product portal, select the product for which you would like to create a license key template.
  2. Under Delivery, select the Delivery Texts tab.

    3. 3. Create a template. You can use the following placeholders:

    Placeholder Description
    <Key> License key
    <RegName> Customer name
    <ProductId> Product ID

    <InternalProductId>

    		Internal product ID
    <[NAME_OF_X_PARAM]> Corresponding x-parameterClosed The x-parameter is a variable appended to a URL that allows grouping and tracking orders for later reporting purposes. It also enables you to pass through data that you want to capture in the order process. X-parameters can also be used to control design elements based on the value of the x-parameter.
    <ProductName> Name of the ordered product
    <Quantity> Quantity of the ordered product
    <ProductTrialUrl> URL to download a trial version of the product

4. Click Save and Complete

Tip

Defining a template in the Subscription Commerce Manager, as opposed to using standard software, allows you to:

  • Use a generic template
  • Insert placeholders that are replaced by purchase info
  • Define multiple languages
  • Use HTML

Note

If you do not enter a key template, the default template is used. A key template starts with <Key>.

For more information about templates, including information about email key templates, see Products ✱.

For more information about templates, including information about email key templates, see Products.

Add a License Key Generator

You can use the Key Generator section to add, view, and edit a web key generator. To add a web key generator, do the following:

  1. In the main menu of the Subscription Commerce Manager, select Tools > Key Generator, and click Add Key Generator.
  2. Enter information in the following fields:
    3. Field Description
    Name Enter a unique name for the key generator.
    Path

    Enter the full URL of the key generator.

    Note

    The URL of your key generator must have an HTTPS scheme.

    Note

    SSL certificates for HTTPS are only supported if they are signed by a trusted authority.
    Authenticate Select to authenticate username and password access to the key generator.
    Username and Password Enter a username and password to access the key generator.
    Interface Select Type 1, unless Client Experience has instructed you otherwise.
    Character Encoding Select the type of JSON or XML character encoding to use for the key generation. Most clients typically choose Unicode (UTF-8).
    Use Romanized Contact Values Select to render western characters for the Company, First name, and Last name contact values for languages such as Chinese, Japanese, and Russian.
    Call Once Per Purchase If selected, the key generator is called once for the entire purchase in the shopping cart. If left unchecked, the key generator is called once for every purchase item in the shopping cart.
    Notification Document Type

    Depending on if and which type is selected here, an XML or JSON notification with transactional data is pushed to the key generator during the API call. If not selected, the key generator will receive a limited amount of information.

    Note

    The notification document used in web key generator calls is identical to the PaidOrderNotification, with the exception of the Deliveries Array.
    XML Schema Select the XML schema version. XML notifications can be generated so that they are compatible with newer or older versions of XML.
    Client Handles Errors

    Select if you wish to manage key generation errors on your own. If you do not select this option, Cleverbridge manages key generation errors (recommended).

    Note

    If a key generation or key list error occurs, the following happens:

    • If you have set up this notification type, you receive an ErrorNotification.
    • An error log entry is created.
    • The Cleverbridge platform makes up to five attempts to generate or obtain the key (after 1-2-4-8-16 hours). After each unsuccessful attempt, an ErrorNotification is sent and an error log entry created.
    • If the fifth attempt to generate or obtain the key fails, our Customer Support will investigate the error (unless Client handles errors is activated).
  3. Click Save and Complete.