LWSDOCUMENTATION

WooSoftware

Welcome to the Long Watch Studio Document Centre dedicated to WooSoftware, the digital goods and software selling plugin for WooCommerce. Learn how to use the API, activate licenses, set the maintenances and versions for your softwares.

The documentation below is divided into several sections :

  1. WooSoftware admnistration interface
  2. Product Settings
  3. API Usage

 

Administration interface

Our plugins have all been designed with simplicity of use in mind. For most of them, the options available, as well as their effects on the plugin, are explained directly in the user interface.

However, it may be that you have specific requirements or that certain available options are less easy to understand. The knowledge base below explains, point by point, all the available options in the WooSoftware administration panel.

You can access the WooSoftware administration panel from your WordPress administration by going to WooCommerce → WooSoftWare.

Settings → Features

This is the first administration page you should visit. It will allow to enable the different WooSoftware features that you need.

1 – API

A full API (Application Programming Interface) is provided with WooSoftware. This API will manage all the exchanges between your sold softwares and your online store. When you install WooSoftware, an API url is automatically created. You can change this url in WooSoftware → Settings → API.

You must activate the API feature in order to allow product license activation and update.

2 – Licences

You can protect your softwares against copying by using licenses. When you activate the license feature, every sale of a software or digital good will generate one or several license keys. The customer will have to enter a license key in his software copy in order to use it.

Warning ! WooSoftware doesn't provide code to manage licenses inside your sold softwares.

WooSoftware generates license keys and API functions you can call in order to activate and track running licenses.

3 – Versions

By using the Versions feature, you can manage multiple versions of the softwares you sell. This way, you can propose updates of your solutions to your customers while keeping older versions available if needed.

Each version can be categorized according to your needs in order to present multiple files for one version. Finally, you can set a release date for versions. Release dates set in the future will prevent downloading until the date is met.

4 – Maintenances

Maintenances exist to add a support/update period for your products. Each time a maintenance period is about to expire, customers will receive an email inviting them to buy a new maintenance period.

Maintenance can't be activated if both licenses and versions features aren't.

Activating the maintenance feature automatically restricts the possibility to download new versions of your products to customers with active maintenance. Though, customers will still be able to download older versions which they where entitled to.

5 – Lite/Full Versions

This feature allows you to propose free and light versions of your products. Activating this feature will change the WooCommerce product entry to propose files for both the light and complete versions of your softwares.

The full version will only be available through a free version update using the API.

Lite/Full versions can't be activated if licenses aren't.

6 – WordPress Plugins

By activating this feature, you'll add new values in product entry allowing you to sell WordPress plugins.

Settings → API

API usage is further explained in the dedicated part of this documentation. However, common API URLs are given inside the admin panel screen dedicated to API settings to make your life easier.

1 - Options

API Endpoint : By setting and endpoint, you can simplify the API call URLs by adding a specific term. Setting an endpoint will change the "/wp-admin/admin-ajax.php?action=lwswoosoftware" part of the URLs by your endpoint.

Allow private products returned by API : WooCommerce forces customers to be logged in to see private products. WooSoftware's API respects this parameter. However, you can decide to override this parameter.

Allow free products returned by api even without license : Free products aren't returned by the API by default as they don't require a licence. Still, you can decide to override this value.

API answer for update request with expired license : When a license has expired, software users can still send update requests. By default, the API will respond with a "401 - Unauthorized" error. If you propose light/free versions of your softwares, you can decide to send the free version instead of the error.

Showcase page : If need be, you can send the content of a WordPress page through an API call (for advertising purposes for example).

 

2 - Version Settings

When you set up versions of your softwares, you can enter categories along the downloadable files. In this section, you can add or delete these categories.

Settings → Emails

Within WooSoftware, emails are sent to customers when their maintenances are about to expire. Emails containing licenses are sent by WooCommerce and can't be modified here.

1 - Rappel

This setting specifies the number of days before maintenance expiration for which an email will be sent. If you don't set a value, no reminder email will be sent to your customers.

2 - Email Settings

In this part, you can set several email settings :

  • Header picture : Image that appears in all your emails. Should be 600 pixels wide maximum.
  • Footer text : That text will appear in all your emails footers. You can add html code here, with a link to your website for example.

3 - Renew maintenance

In this part, you can customize the emails sent by WooSoftware when their maintenance is about to expire.

  • Subjet : Email subject
  • Title: Email title
  • Header : Header text presented before the content.
  • Style Generator : Customize the look of your emails by changing colors, spacings or fonts. You should not use Google fonts in emails as they're not read in all email clients.
  • Send test email : You can see the email result in your inbox by sending a test email. Specify the recipient email and click on the Send test email button (your website needs to have valid smtp parameters in order for emails to be sent. We advise you to use WP Mail SMTP).

Licenses → Active Licenses

In this page, you can see all the licenses generated by WooSoftware since its activation. A research field is at your disposal to filter the list to help you find a specific license.

For each license, you have several informations :

  • User : User Id of the license owner
  • Product : The software for which the license has been generated.
  • Expiration : License expiration date if relevant. "Not activated" if the license has never been used or "Unlimited" along with the activation date if no expiration date has been set.
  • License key : The generated software license key.

You can delete licenses directly in this list. Be advised : deleting a license also deletes maintenance and other associated options.

Finally, if a license has been activated, you can reset its fingerprint in order to proceed with a new activation.

Licenses → Options

Only one option is available for licenses : key pattern.

WooSoftware allows you to create the key pattern of your licenses. The different possibilities are explained on the top of the page. License keys must allways have a 20 or more characters length.

Maintenances → Running Maintenances

In this page, you can see all the generated maintenances since the "Maintenance" feature has been activated. A research field is at your disposal to filter the list in order to find a specific maintenance.

For each maintenance, you have different informations :

  • User : User Id of the license owner
  • Product : The software for which the license has been generated.
  • State : State of the maintenance (active or inactive)
  • Expiration : Maintenance expiration date if active. Initial free maintenance period if inactive.
  • License key : The generated software license key.

You can delete maintenances directly in this list. You can also extend maintenance periods of active maintenances by selecting the desired lines and setting the new expiration date in the "Extend up to" field.

Maintenances → Options

Maintenance options are general setting that will be set for all products with an active maintenance feature.

These settings can be replaced by specific values in each product if need be.

  • Default price percent (%) : Percentage of the product price used for the maintenance price calculation.
  • Default lifetime : Free maintenance period when customers buy the product.
  • Minimum renewal period : Customers can't renew their maintenance for a period inferior to this value.
  • Minimum renewal price : Customers can't renew their maintenance for an amount inferior to this value.
  • Renewal prices rounding precision : Number of digits after the decimal point.

Products Settings

WooSoftware adds many elements to WooCommerce products, depending on the features you activated. For each product, you can use one or several WooSoftware features.

WooSoftware features are only available in Simple Products with the Virtual and Downloadable boxes checked.

Once WooSoftware is activated, the product entry is modified and some fields are added :

  • API Product Id : The API Id of the solde product. This ID must be coded inside the software you're selling. It will be sent in all exchanges between the software and the WooSoftware API.
  • Localisation : Product language. If you sell your product in multiple languages, you will have to create as many copies of the product.
  • Default language : Defines if this is the default product language.

Licenses

When you check the License box inside a product, a new tabulation appears. Get to this tabulation to enter the specific values for this product :

  • Secret key : It's a specific hash for your product, used to increase security during the activation process. This value is optionnel and should only be set if your software uses it.
  • Licence count : Number of license keys generated when the product is sold.
  • License Lifetime : Validity period of the license in days. Leave empty if the license doesn't expire. This value is useful if you propose trial version of your products.
  • Single Purchase : Defines if the product can only be purchased one time per customer (for trial versions).
  • Key prefix : If you desire a specific license key for your product, you can set a key prefix which will be at the beginning of every license keys generated for this product.

Versions

When you check the Versions box in your WooCommerce product, the file entry is modified.

The button Add Version permits to add a new version block to the list of existing versions.

For each version, you have to fill differents fields :

  • Version Numver :Your software's version number (for example 2.4.3)
  • Release Date : Release date of the version. Can be defined in the future to hide it until the date is met.
  • Files : You can specify multiple files by using the Add file button. For each file, you have to fill different fields :
    • File Name : Name of the file as it will appear to customers on downloads page.
    • Catégory : Optionnal. The category helps you specify the purpose of the file (OS for example).
    • File Url : File to be downloaded.

 

Warning ! Files MUST be uploaded from the product page in order to have the correct access rights. If you upload your files through your Media page, everybody with the correct url will be able to download them !

Maintenances

If you've activated maintenances in WooSoftware, a Maintenance tab will appear in your WooCommerce Product once you check the Versions box.

Go to the maintenance tab in order to fill the fields specific to your product :

  • Maintenance applied : Check this box to activate maintenance on this product.
  • Initial offered maintenance duration : When the product is purchased, an initial free maintenance period is granted. The value must be greater than 0. A default maintenance period is specified in the WooSoftware general settings. You can override this value here.
  • Renewal price per year : You have two ways to set the annual maintenance price. By default, it's a percentage of the sold product, as defined in the general settings of WooSoftware. You can also set the price directly or change the percentage for a specific product.

WordPress Plugins

If you wish to sell WordPress Plugins (such as us, since we user WooSoftware for ourselves), WooSoftware has a specific option that will allow you to fill some 'WordPress Plugins' related fields :

  • Requires at least WordPress version : When customers will go through plugin update, they will see this information.
  • Tested up to WordPress version : When customers will go through plugin update, they will see this information.
  • Use this product text as description page : When your customer click on More details on the plugins page, they will see the text of your product.
  • Description page : When your customer click on More details on the plugins page, they will see the content of the specified page.

Lite/Full Versions

If you wish to propose light/free versions of your software, you have to activate this options in the general settings of WooSoftware.

The Lite/Full Versions is available only if the corresponding feature is has been activated. The tab allows you to specify the files available through software update from the free/light version to the full version.

The files for the free version are the files specified in the General tab.

If you check the "Enabled" box, you commit yourself to add new versions of your softwares to both the General and the Lite/Full Versions tabs.

The update from the free/light version to the full one is done through an API call during the license activation.

API Usage

In the following examples, we will consider a selling website (with WooSoftware installed) with the url https://my.example.com. We will also considerp that the Endpoint value hasn't been set. The API base url will then be :

https://my.example.com/wp-admin?admin-ajax.php?action=lwswoosoftware

Please be advised that in case of error, API error logs will be with those of WooCommerce (Woocommerce → Status → Logs tab)

License activation

When you entered the product, you filled the API Product ID as well as the secret key. These 2 informations will be useful for your API Calls.

 

API Calls

To activate a licence, your software will have to make a HTTP[S] POST request at the following address where api_product_id will be replaced by the value set in the product :

https://my.example.com/wp-admin?admin-ajax.php?action=lwswoosoftware&product=api_product_id&activate

The POST arguments are as follow:

  • version : The current version of the product.
  • fingerprint : a unique value that identifies the computer where the software was installed. It prevents customers to activate the same license on different computers. The composition of this value is leaved to the software developer. However, the fingerprint can only be composed of alphanumeric characters, the character '-' and the character underscore '_' (for example, 1234-abc_def is a valid fingerprint).
  • token : the license key generated by WooSoftware and provided to the customer when he bought the software. This key has been sent by email to the customer. The customer can allays find it in his WooCommerce "My Account" page.
  • hash : hexadecimal security value . This value is build by concatenation of the following values, separated by slashes and encoded in sha256 :
    • API Product ID for which the licence needs activation.
    • The current version of the product
    • the fingerprint
    • a nonce. Arbitrary value defined by the product. Preferably random.
    • the secret key associated with the product. This value is only known by the selling website, it is never exchanged in clear.

A cookie must also be provided containing the following value:

  • nonce : The value used in the hash.

For example, a hash which text is:

mon_produit/2.0.1/print-sherlock42/nonce-72616e646f6d/key-123456789

would become :

a27bf3b0d1291b6ec1dd93752e0435f50c665581992dbe42370c8557d69a48a3

API Response

To this call, the API will respond :

  • HTTP 400 error code. Some arguments are missing or don't respect the mandatory format.
  • HTTP 200 code (or 301 depending on the server configuration). The response's body is then a JSON array containing the following data :
    • ok : boolean indicating if the license has been activated.
    • html : clear text containing the result of the activation.
    • slug : (only on a successful activation) API Product ID of the activated product.
    • token : (only on a successful activation) the license key.
    • fingerprint: (only on a successful activation) the same fingerprint that the one send on the request.
    • hash : (only on a successful activation) hexadecimal security value. This value is build by concatenation of the following values, separated by slashes and encoded in sha256 :
      • API Product ID for which the licence needs activation.
      • The activated licence key.
      • la clé de licence qui a été activée.
      • the nonce provided by the caller.
      • an arbitrary value provided in the cookie joined to the response under the key rand.
      • the secret key associated with the product. This value is only known by the selling website, it is never exchanged in clear.
    • expire : (optionnal) if the license is temporary, this entry contains the expiration date of the licence in the format YYYY-MM-DD. For example 2036-02-29.

Download and update

When you entered the product, you uploaded several files

 

API Calls

To download a file, your software will have to make a HTTP[S] POST request at the following address where api_product_id will be replaced by the value set in the product :

https://my.example.com/wp-admin?admin-ajax.php?action=lwswoosoftware&product=api_product_id&get=vX.X.X

Ici, v.X.X.X doit être remplacé par la version que vous voulez télécharger. Le numéro de la version la plus récente disponible pour un produit peut être demandé à l'API via la fonction d'information sur un produit. Si la gestion des versions n'a pas été activée pour ce produit sur le site vendeur, cette valeur peut rester vide.

Here, v.X.X.X has to be replaced by the version you wish to download. The most recent available version can ba asked to the API using the Information on a Product function. If the versions feature hasn't been activated for the product, this value can be empty.

The POST arguments are as follow:

  • product : The API Product Id.
  • version : The desired version of the product. This information must be the same as the get element above. If the versions feature hasn't been activated for the product, this value can be empty.
  • token : the license key generated by WooSoftware and provided to the customer when he bought the software. This key has been sent by email to the customer. The customer can allays find it in his WooCommerce "My Account" page.
  • fingerprint : a unique value that identifies the computer where the software was installed. It must be the same than the fingerprint sent on product activation.
  • category : (optionnal) if multiple files are available for a same version, this parameter filters the files to download. If the versions feature hasn't been activated for the product, this value will apply on files names. If there is only one file to download, it will be sent as is. If multiple files are available even after the filter, they will be compressed in a zip archive and sent.
  • hash : hexadecimal security value . This value is build by concatenation of the following values, separated by slashes and encoded in sha256 :
    • API Product ID for which the licence needs activation.
    • The desired version of the product
    • the fingerprint
    • an empty string (reserved value).
    • the secret key associated with the product. This value is only known by the selling website, it is never exchanged in clear.

A cookie must also be provided containing the following value:

  • nonce : The value used in the hash.

For example, a hash which text is:

mon_produit/v2.0.1/print-sherlock42//key-123456789

would become :

46b6f23d4bdf0ed4c8d51cd5c69ce27e112af71937b75f7ff8ea93eeca2492ff

API Response

If the request is a success, the response header will be a 200, 206 or 301 HTTP code, depending on the server configuration. The response itself is the file requested or the zip archive containing the files requested.

If the request fails, the response header will be a HTTP code :

  • between 400 and 499 : Your request is invalid. The license doesn't exist, is not valid, has expired or there is no file to send back.
  • between 500 and 527 : The server has a problem. You need to retry later or contact the vendor.

 

API Calls

To get information about a product, your software will have to make a HTTP[S] POST request at the following address where api_product_id will be replaced by the value set in the product :

https://my.example.com/wp-admin?admin-ajax.php?action=lwswoosoftware&product=api_product_id&info

If you have a license key for this product, you can optionally send it in POST.

If the lite/full feature is active, this parameters will determine if the returned information is about the light or the full version of the product.

The POST arguments are as follow:

  • key : the license key generated by WooSoftware and provided to the customer when he bought the software. This key has been sent by email to the customer. The customer can allays find it in his WooCommerce "My Account" page.
  • force : (optionnal) if the product has a maintenance and the key argument is filled, the returned version value will be the last available version considering the maintenance associated. You can override this restriction by setting this force argument. Beware, the returned version may not be available for download if the maintenance has expired.

API Response

If the request is a success, the response header will be a 200 or 301 HTTP code, depending on the server configuration. The response itself is a JSON array containing the following data (this data is compatible with the WordPress plugin update system. Some data can be added in product entry) :

  • slug : The API Product ID.
  • plugin_name : Public product name.
  • version : The most recent version available. If a key has been sent, a maintenance exists AND force wasn't sent in the request, then it contains the most recent downloadable version.
  • categories : If multiple files are available, the categories entry is added. It's a JSON array containing the categories associated with the last version files if the versions feature is active. Otherwise, it's a JSON array containing the list of available files.

If these values have been filles in the product entry, the following fields are added to the JSON array:

  • author : the product author
  • requires : the minimum WordPress version required for the product
  • tested : the last tested WordPress version for this product.

The following fields are added in order to enhance the update screens if the sold software is a WordPress plugin.

  • last_update : Last update date of the product
  • homepage : vendor website url.
  • icons : a JSON array containing the image for the product.
  • sections : a JSON array containing :
    • description : the text associated with the product.
    • changelog : if the versions feature is active, this field's content is generated from the information you entered for each version of the product. Otherwise, it's a free text on product entry.

If the request fails, the response header will be a HTTP code :

  • between 400 and 499 : Your request is invalid. The product doesn't exist, the license doesn't exist, is not valid or has expired. If the license hasn't been sent, it's possible that the product doesn't propose a free version.
  • between 500 and 527 : The server has a problem. You need to retry later or contact the vendor.