Latest revision as of 14:36, 29 August 2023

About this Addon Module

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.

Activating Licensing Addon

You must first purchase this addon. Then, you can activate it through the Admin Area.

To do this:

1. Purchase the addon in the WHMCS Marketplace.
2. Go to Configuration () > System Settings > Addon Modules or, prior to WHMCS 8.0, Setup > Addon Modules.
3. Click Activate.
4. Click Configure.
5. Choose one of the following options:
   • Public License Verification Tool — Enable this option to make available a verification page which visitors can use to check whether a domain is licensed to be using your software. The appearance can be customised by editing the /modles/addons/licensing/licenseverify.tpl template file at http://www.yoursite.com/whmcs/index.php?m=licensing.
   • Maximum Allowed Reissues — To limit how many times a client can reissue a licence, specify the maximum number of reissues here.
   • Auto Logs Prune — To prevent the licence access logs from becoming too large you can specify for how long they should be kept.
6. Select the admin role groups who will have access to this addon.
7. Click Save Changes.

Using this Addon

To set up a licensing product:

1. Create a product at Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services.
2. In the Module Settings tab, choose License Software.
3. Configure the following options:
   • Key Length — The length of the randomly generated key.
   • Key Prefix — The beginning of the license key. You can use this to validate an applicable key.
   • Allow Reissue — Whether a client can reissue the license from the Client Area.
   • Allow Domain Conflict, Allow IP Conflict, and Allow Directory Conflict — If you don't check these, WHMCS will make sure the location at which the licence is being used matches the Valid values in the service record. Check the option if you want to allow a user to run the product on multiple domains, IP addresses, or directories.
   • Support/Updates Addon — See below.
   • Free Trial — This option can be checked to prevent clients from using more than one licence of this product on the same domain. If a client tries to order a second copy of this product and use it on the same domain as a previous service, it will be automatically suspended with the reason "Duplicate Free Trial Use". Useful for limiting free trials to one per domain.

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 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 or upgrades. 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.

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 Configuration () > System Settings > Product Addons or, prior to WHMCS 8.0, Setup > Products/Services > Product Addons.
3. Click Add New.
4. Enter the name, description, price and recurring cycle - leave the Show on Order setting unchecked
5. Check the licensing product(s) in the applicable products section for the addon
6. Now go back to the product configuration area and click the edit icon next to your licensing product
7. 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 check 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

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 user can then enter their license key during an installation process or by pasting it into a file. You can then load that key in your file before calling the check_license function to validate in which the file is run. For each successful check, a local key is returned. You can then store that local key in your database or a file to use locally for license verification on subsequent page loads.

To integrate the license check, perform these steps:

1. Copy and paste the license check code from the check_sample_code.php file into the top of the file you want to protect.
2. Enter the System URL from your WHMCS installation 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 and $allowcheckfaildays variables if you want to change how often a remote license check is made.
5. Ensure that your code performs the following actions:
   • Retrieve the license key and local key from the database or file storage.
   • Call the check_license function.
   • Perform the desired actions in accordance with the results of the check_license function. For sample if statements, see the check_sample_code.php file.
   • Store the local key that the license check returns.

Using Product Addons

If the licensing product has any ordered addons, the results from the licensing addon will include a pipe separated string called "addons" with their details that can be processed and used for any number of purposes. For example: restricting access to certain features unless a particular addon has been ordered.

[addons] => name=Test Addon;nextduedate=2017-12-26;status=Active

This can be processed into a named array called $addons from the $results array returned by your check_license function. To do so, use the following code:

$tempresults = explode("|",$results["addons"]);
foreach ($tempresults AS $tempresult) {
  $tempresults2 = explode(";",$tempresult);
  $temparr = array();
 
  foreach ($tempresults2 AS $tempresult) {
  $tempresults3 = explode("=",$tempresult);
    $temparr[$tempresults3[0]] = $tempresults3[1];
  }
 
  $addons[] = $temparr;
}

Using Configurable Options

If the licensing product has any ordered configurable options, the results from the licensing addon will include a pipe separated string called "configoptions" with their details that can be processed and used for any number of purposes. For example: limiting usage of software to a particular number of clients or admin users.

[configoptions] => Test=0|Test 002=

This can be processed into a named array called $configoptions from the $results array returned by your check_license function. To do so, use the following code:

$tempresults = explode("|",$results["configoptions"]);
foreach ($tempresults AS $tempresult) {
  $tempresults2 = explode("=",$tempresult);
  $temparr = array();
 
  foreach ($tempresults2 AS $key => $value) {
    $temparr[$key] = $value;
  }
 
  $configoptions[] = $temparr;
}

License Statuses

The license may be in one of these states:

• Reissued — The license is ready to use and will record the domain, IP address, and installation path.
• Suspended — The license has been suspended and cannot be used at this time.
• Active — The license is currently being used with a valid domain, IP address, and installation path.
• Expired — The license has reached its expiration date.

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.

Troubleshooting

Invalid Key

This generally indicates that the licensing checking code is not passing a license key back to the licensing addon. The code being used will need to be corrected to ensure that it is returning the full license key to WHMCS.

Remote Check Failed

This suggests a connection problem between the user's server and the end client's server.

The first step will be to provide the user with a cURL test script that attempts to connect to your WHMCS installation and run it from their server, correcting any detected issues.

If that all appears clear, it could be due to a SSL configuration issue on the user's server. As a workaround, you can potentially add the following into your licence checking code:

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

A new local key is being generated on every request

This behaviour suggests that the local licence key returned by the license checking function after a successful check is not being stored. When no local licence key is stored and passed into the licensing checking function, a remote check has to be performed and a new local key is generated.

Storing the local license key returned by the license checking function and passing it back into the checking function should resolve this. We recommend storing it in a way most appropriate for your particular software, for example in a flat file or in a database.

Change Log

Licensing Addon v3.0

Release Date: 9th February 2012

New Features Added:

• Free Trial Option
• Public License Verification Tool
• Banned Domains
• Intelligent Search Integration
• Added Maximum Allowed Reissues Limit
• Auto Logs Prune