Revision as of 09:44, 6 January 2012

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

Version 5

The addon files are now included in WHMCS by default, a licence must still be purchased from our website. Then you just need to move the licenses_manager.php file from /modules/servers/ to /modules/admin/licenses_manager (you will need to create these directories) and then you simply need to activate the addon module in Setup -> Addon Modules and then follow the steps below to setup a product.

Version 4 and Below

• Begin by downloading the addon from our client area by going to My Licenses & Services, clicking the active license key where the addon was ordered for and then selecting the licensing addon which you'll find in the downloads below the license information
• Next, unzip the files to a folder locally on your computer
• Now to install, simply upload the files to the following locations:

licensing.php - /modules/servers/licensing/
verify.php - /modules/servers/licensing/
licenses_manager - /modules/admin/licenses_manager/
clientareaproductdetails.tpl - /templates/xx/ (where xx is your active template name)

• Next, login to the admin area and go to Help > Check for Updates to force an immediate update of your local license key.
• Navigate to Setup > Addon Modules and activate the Licensing Addon.
• The installation is now complete and you'll be able to access the licensing addon under the Addons menu item.

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 - determines whether to ignore domain mismatches on license checking (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 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 > 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 file check_sample_code.php. 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.