Revision as of 09:00, 21 January 2015

The WHMCS licensing addon module allows you to license your own web applications for selling to end users. Supporting both local license keys and periodic remote checking, it offers a robust and secure way of licensing your scripts.

Installation

By purchasing the licensing addon, this will unlock access to the licensing addon module files which are now bundled with the default WHMCS install package. So after purchasing, there are no manual installation steps necessary any more - you just need to activate and configure the module in Setup > Addon Modules.

Upgrading

To upgrade to the latest V3.0 release of the licensing addon from V2.1 or earlier, simply follow the steps below:

1. Begin by deleting the existing /modules/admin/licenses_manager/ folder
2. Now upload the new files from the licensing addon zip file download to the /modules/ folder of your WHMCS installation
3. And finally to complete the process, navigate to Setup > Addon Modules and activate the new Licensing Manager addon that you'll find listed there

Setting up a licensing product

1. Begin by creating a product in the normal way (Setup > Products/Services)
2. On the module settings tab, choose "Licensing" in the Module dropdown
3. The options for a licensing product will then appear. These are explained in detail below:

• Key Length - this defines how long the randomly generated key will be - enter the numerical value you want
• Key Prefix - this defines the start of the license key and is how you can validate an applicable key for the product you're performing the checking in has been entered - eg. Monthly-, Owned-, Mobile-, etc...
• Allow Reissue - determines whether a client can reissue the license from the client area
• Allow Domain Conflict - When unticked WHMCS will make sure the location at which the licence is being used matches the 'Valid Domain' value in the service record. Tick the option if you want to allow a user to run the product on multiple domains.
• Allow IP Conflict - as above but for the IP address
• Allow Directory Conflict - as above but for the directory
• Support/Updates Addon - explained in detail below

Downloads

Downloads are how your client receives the software product after purchase. These are configured using the existing digital download product release mechanism. For more information on this, refer to http://docs.whmcs.com/Product_Downloads_Distribution

Addons

Each product can be assigned multiple addon products which can be added at the time of initial ordering or at a later date. Uses for addons include extra value added services such as installation, configuration, upgrades, etc... They allow you to charge additional fees for items which aren't required in order to utilise the actual product.

Support & Update Addons

If you enable these on your licensing product, then the client is required to have an active support & updates package in order to receive support & download the related product downloads. This means you can charge your users for the continued support and updates using any of the recurring terms available to you in WHMCS. For example we charge you annually for this service on an owned license.

Setting up a Support & Updates Addon Package

The guide below explains how to create a support & updates package which is include free with the initial license purchase and then requires renewal once it expires.

1. Ensure your licensing product is created first
2. Then, go to Setup > Products/Services > Product Addons > Add New
3. Enter the name, description, price and recurring cycle - leave the Show on Order setting unchecked
4. Now tick the licensing product(s) in the applicable products section for the addon
5. Now go back to the product configuration area and click the edit icon next to your licensing product
6. On the Module Settings tab, choose the addon you just created in the "Support/Updates Addon" field and save

And that's it! If you didn't want to include it free with the initial purchase, you would leave the setting on the Module Settings tab at None and tick the box for Show on Order in the addon configuration.

Module Commands

• Create - Used to generate the license key for the product with status Reissued
• Suspend - This will set the license status to Suspended
• Unsuspend - This will set the license status back to Active
• Terminate - This will set the license status to Expired
• Reissue - Sets the license status to Reissued so the domain, IP & directory is saved on the next check
• Revoke - This command will completely remove the license key and allow the number to be reused in future
• Manage - This button takes you to where you can view & edit the allowed domain, IP & directory for the license

http://www.whmcs.com/images/addons/licensingaddon.jpg

Managing Licenses

To manage licenses, go to Addons > Licenses Manager. From here you can browse through all the license keys that have been issued, search for license keys and make changes to the allowed domains, ips and directory for a license.

Integrating the Check Code

The code used to integrate the license check is included with the addon in the /modules/servers/licensing/check_sample_code.php file. The idea here is that you would have your user enter the license key they get issued during an install process or by simply pasting it into a file, and then you load that in your file before calling the check_license function to validate where the file is being run. For each successful check, a local key is returned which you then also store in your DB or a file to verify against locally on subsequent page loads.

The steps to integrate are described in more detail below:

1. Copy & paste the code into the top of the file you want to protect
2. Enter the URL to your WHMCS system root directory in the $whmcsurl variable
3. Customise the $licensing_secret_key variable used to ensure your local keys are different from other licensing addon users
4. Optionally change the $localkeydays & $allowcheckfaildays variables if you want to change how often a remote check is made
5. Now retrieve the license key and local key from the database or file storage you have saved them in
6. Then call the check_license function
7. And then act on the result based on the sample code if statements
8. You then store the local key that gets returned

Frequently Asked Questions

What is the local key?

The local key is the thing that stops the license checking code having to call your server on every page load. It's basically just an encrypted version of the license check data, so that when it's present and valid, the licensing addon doesn't have to make a remote call which would slow down your application/code, thus improving performance. The local key will always be empty on the first check your client makes, but then with every successful remote check, a local key value is returned (sample code provided) which you then just need to store and pass into any future license check calls. We recommend storing into a database for ease of updating and retrieval, but flat files can work just as well.