{eac}SoftwareRegistry – Software Registration Server

Document Header

Homepage:https://swregistry.earthasylum.com/ Author:EarthAsylum Consulting Current Version:1.0.4 Last Updated:15-Jun-2022 Requires WordPress Version:5.4.0 Compatible up to:5.9.3 Requires {eac}Doojigger:1.1.0 Requires PHP Version:7.2 Contributors:Kevin Burkholder License:EarthAsylum Consulting Proprietary License (EACPLv1) License URI:https://swregistry.earthasylum.com/end-user-license-agreement/ Tags:software registration, software registry, software license, license manager, registration API

{eac}SoftwareRegistry - A feature-rich and easily customized software registration and licensing server for WordPress.

Description

{eac}SoftwareRegistry is a derivative plugin of and requires installation and registration of {eac}Doojigger.

Summary

{eac}SoftwareRegistry is a WordPress software licensing and registration server with an easy to use API for creating, activating, deactivating, and verifying software registration keys.

Registration keys may be created and updated through the administrator pages in WordPress, but the system is far more complete when your software package implements the {eac}SoftwareRegistry API to manage the registration.

One of two scenarios typically occur when a client receives your software:

  1. The client purchases your software, registers your software, then installs your software.

    With {eac}SoftwareRegistry, a new registration key may be created through the purchase process (or manually by the administrator) and then the client may enter the registration key and activate the registration when installing the software.

  2. The client downloads your software, installs your software, and then registers your software.

    The client is presented with a "new registration" screen when installing the software and may request a new registration key through the API which will automatically generate the key and activated the registration.

Registration keys may be verified via API on a scheduled basis so that any updates made by the administrator, via other transaction, or due to renewal or expiration, are updated in the client software.

Registration status may be:

  • Pending (awaiting approval)
  • Trial (limited time trial period)
  • Active
  • Inactive
  • Expired
  • Terminated

Registrations may include (but do not require):

  • Valid domain(s).
  • Valid site URL(s).
  • Number of users/sites/devices.
  • License level (i.e. 'basic', 'pro').
  • Software product-specific options and variations.

{eac}SoftwareRegistry API

The built-in Application Program Interface (API) is a relatively simple method for your software package to communicate with your software registration server ({eac}SoftwareRegistry).

See the API Details section.

{eac}SoftwareRegistry Distribution SDK

The added Software Distribution Development Kit (SDK) extension makes it even easier to implement software registrations in your software package.

With the inclusion of the SDK generated for your package, you may be able to implement the APIs for {eac}SoftwareRegistry with only a small amount of code.

The SDK includes everything needed to create, activate, deactivate, revise, and refresh a registration. It also includes the storing of the registration key, the caching of the registration data, and the scheduling of verification requests.

Both WordPress and non-WordPress projects are supported by the SDK.

{eac}SoftwareRegistry Hooks

With the SoftwareRegistry Hooks extension, you can add custom PHP code for the many hooks (filters and actions) available in the server software. With these hooks you can customize the registry server options, incoming API requests, outgoing API responses, and client emails and notifications.

{eac}SoftwareRegistry and WooCommerce

With the added {eac}SoftwareRegistry WebHooks for WooCommerce extension, software registrations can be created, updated, and/or terminated via WebHooks from WooCommerce.

A Webhook is an event notification sent to a URL of your choice. Users can configure them to trigger events on one site to invoke behavior on another.

Simply create the needed webhooks in the WooCommerce administration (order created, order updated, order deleted, order restored) and enable the corresponding end-points in {eac}SoftwareRegistry.

When an order placed on your WooCommerce site is created, the registration will be created on your software registration server. If the customer updates or cancels their order, their registration will also be updated or cancelled.

Your WooCommerce and registration server do not need to be the same server and neither needs to be running the other software. In fact, you can have multiple WooCommerce sites all sending webhook updates to your registration server.

{eac}SoftwareRegistry Subscriptions for WooCommerce

Go one step further by adding the {eac}SoftwareRegistry Subscriptions for WooCommerce plugin to your WooCommerce store site and subscription updates will also be passed to your registration server keeping your registrations updated by your subscription renewals.

Top
API Details

First, from the Distribution tab of the Software Registry Settings, you will need your API keys and endpoint URL.

API parameters

API parameters are passed as an array:

$apiParams =
[
    'registry_key'          => 'unique ID',                     // * registration key (assigned by registry server)
    'registry_name'         => 'Firstname Lastname',            //   registrant's full name
    'registry_email'        => 'email@domain.com',              // * registrant's email address
    'registry_company'      => 'Comapny/Organization Name',     //   registrant's company name
    'registry_address'      => 'Street\n City St Zip',          //   registrant's full address (textarea)
    'registry_phone'        => 'nnnnnnnnnn',                    //   registrant's phone
    'registry_product'      => 'productId',                     // * your product name/id ((your_productid))
    'registry_description'  => 'Product Description',           //   your product description
    'registry_version'      => 'M.m.p',                         //   your product version
    'registry_license'      => 'Lx',                            //   'L1'(Lite), 'L2'(Basic), 'L3'(Standard), 'L4'(Professional), 'L5'(Enterprise), 'LD'(Developer)
    'registry_count'        => int,                             //   Number of licenses (users/seats/devices)
    'registry_variations'   => array('name'=>'value',...),      //   array of name/value pairs
    'registry_options'      => array('value',...),              //   array of registry options
    'registry_domains'      => array('domain',...),             //   array of valid/registered domains
    'registry_sites'        => array('url',...),                //   array of valid/registered sites/uris
    'registry_transid'      => '',                              //   external transaction id
    'registry_timezone'     => '',                              //   standard timezone string (client timezone)
];

API Remote Request

Example code to execute the remote request

/**
 * remote API request - builds request array and calls api_remote_request
 *
 * @param   string  $endpoint create, activate, deactivate, revise, verify
 * @param   array   $params api parameters
 * @return  object api response (decoded)
 */
public function registryApiRequest($endpoint,$params)
{
    $endpoint = strtolower($endpoint);
    switch ($endpoint)
    {
        case 'create':
            $apiKey = "<Registration Creation Key>";
            $method = 'PUT';
            break;
        case 'activate':
        case 'revise':
            $apiKey = "<Registration Update Key>";
            $method = (count($params) > 1) ? 'POST' : 'GET';
            break;
        case 'deactivate':
            $apiKey = "<Registration Update Key>";
            $method = 'DELETE';
            break;
        case 'verify':
            $apiKey = "<Registration Read Key>";
            $method = (count($params) > 1) ? 'POST' : 'GET';
            break;
    }

    $request = [
        'method'        => $method,
    ];

    $request['headers'] = [
        'Accept'        => 'application/json',
        'Referer'       =>  sprintf('%s://%s%s', isset($_SERVER['HTTPS']) ? 'https' : 'http', $_SERVER['HTTP_HOST'], $_SERVER['REQUEST_URI']),
        'Authorization' => 'Bearer '.base64_encode($apiKey),
    ];
    if (in_array($method,['GET','HEAD','DELETE'])) {
        $request['headers']['Content-Type'] = 'text/plain';
        $remoteUrl = "<API Endpoint URL>".'/'.$endpoint .'?'. http_build_query($params);
    } else {
        $request['headers']['Content-Type'] = 'application/json';
        $request['body'] = json_encode($params);
        $remoteUrl = "<API Endpoint URL>".'/'.$endpoint;
    }

    $response =  $this->api_remote_request($endpoint,$remoteUrl,$request);

    if ($response->status->code == '200') && $endpoint != 'deactivate' && isset($response->registration))
    {
        // update the current registration cache (save the registration object and key)
        $this->setRegistrationCache($response);
        // schedule the next refresh event
        $this->scheduleRegistryRefresh($response->registrar->refreshInterval,$response->registrar->refreshSchedule,$response->registration);
    }
    return $response;
}

/**
 * API remote request - remote http request (wp_remote_request or curl)
 *
 * @param   string  $endpoint create, activate, deactivate, verify
 * @param   string  $remoteUrl remote Url
 * @param   array   $request api request
 * @return  object api response (decoded)
 */
public function api_remote_request($endpoint,$remoteUrl,$request)
{
    $result = wp_remote_request($remoteUrl,$request);
    $body   = json_decode(wp_remote_retrieve_body($result));
    if (!empty($body) && isset($body->code) && isset($body->message)) {
        $result = new \wp_error($body->code,$body->message,$body->data);
    }

    if (is_wp_error($result))
    {
        $code   = $result->get_error_data() ?: [];
        $code   = $code->status ?? $result->get_error_code();
        $msg    = $result->get_error_message();
        $error  = json_decode('{"status":{"code":"'.$code.'","message":"'.$msg.'"},'.
                             '"error":{"code":"'.$code.'","message":"'.$msg.'"}}');
        return $error;
    }

    return $body;
}

Using registryApiRequest()

Create/request a new registration...

$response = $this->registryApiRequest('create',$apiParams);

Activate an existing registration...

$response = $this->registryApiRequest('activate',['registry_key' => "<registration_key>"]);

Deactivate an existing registration...

$response = $this->registryApiRequest('deactivate',['registry_key' => "<registration_key>"]);

Verify/Refresh an existing registration...

$response = $this->registryApiRequest('verify',['registry_key' => "<registration_key>"]);

Revise an existing registration...

$response = $this->registryApiRequest('revise',$apiParams);

API Remote Response

The API response is a standard object. status->code is an http status, 200 indicating success.

status      ->
(
    'code'                  -> 200,             // HTTP status code
    'message'               -> '(action) ok'    // (action) = 'create', 'activate', 'deactivate', 'verify', 'revise'
),
registration =>
(
    'registry_key'          -> string           // UUID,
    'registry_status'       -> string,          // 'pending', 'trial', 'active', 'inactive', 'expired', 'terminated', 'invalid'
    'registry_effective'    -> string,          // DD-MMM-YYYY effective date
    'registry_expires'      -> string,          // DD-MMM-YYYY expiration date
    'registry_name'         -> string,
    'registry_email'        -> string,
    'registry_company'      -> string,
    'registry_address'      -> string,
    'registry_phone'        -> string,
    'registry_product'      -> string,
    'registry_description'  -> string,
    'registry_version'      -> string,
    'registry_license'      -> string,
    'registry_count'        -> int,
    'registry_variations'   -> array,
    'registry_options'      -> array,
    'registry_domains'      -> array,
    'registry_sites'        -> array,
    'registry_transid'      -> string,
    'registry_timezone'     -> string,
    'registry_valid'        -> bool,            // true/false
),
registrar ->
(
    'contact'               -> object(
        'name'              -> string           // Registrar Name
        'email'             -> string           // Registrar Support Email
        'phone'             -> string           // Registrar Telephone
        'web'               -> string           // Registrar Web Address
    ),
    'cacheTime'             -> int,             // in seconds, time to cache the registration response (Default Cache Time)
    'refreshInterval'       -> int,             // in seconds, time before refreshing the registration (Default Refresh Time)
    'refreshSchedule'       -> string,          // 'hourly','twicedaily','daily','weekly' corresponding to refreshInterval
    'options'               -> array(           // from settings page, registrar_options (Allow API to...)
        'allow_set_key',
        'allow_set_status',
        'allow_set_effective',
        'allow_set_expiration',
        'allow_activation_update'
    ),
    'notices'               -> object(
        'info'              -> string,          // information message text
        'warning'           -> string,          // warning message text
        'error'             -> string,          // error message text
        'success'           -> string,          // success message text
    ),
    'message'               -> string,          // html message
),
registryHtml                -> string,          // html (table) of human-readable registration values

Software Distribution Development Kit

All of this code, and more, is included in the Software Distribution Development Kit (SDK) making it very easy to implement the API for your software package.

Top
Installation

{eac}SoftwareRegistry is a derivative plugin of and requires installation and registration of {eac}Doojigger.

Installation of the plugin can be managed through WordPress on the 'Plugins' page » 'Add New' » 'Upload Plugin' and then selecting the eacSoftwareRegistry.zip file from your computer. You can also install the plugin manually by extracting the file and uploading the 'eacSoftwareRegistry' folder to the 'wp-content/plugins' folder on your WordPress server.

See Managing Plugins -> Upload via WordPress Admin

{eac}SoftwareRegistry should NOT be Network Enabled on multi-site installations.

On Activation, default settings/options are created. Be sure to visit the 'Settings' page to ensure proper configuration.

Updates are also managed from the 'Plugins' page. When a new version is available, a notice is presented under this plugin. Clicking on the 'update now' link will install the update; clicking on the 'View details' will provide more detail on the update from which you can click on the 'Install Update Now' button. When updated, any custom tables and/or option changes are applied. Be sure to visit the 'Settings' page.

On Deactivation, the plugin makes no changes to the system but will not be loaded until reactivated.

When Uninstalled, the plugin will delete settings and transient data (including the registration). If settings have been backed up, the backup is retained and can be restored if/when re-installed.

Top
Screen Shots
  1. {eac}SoftwareRegistry General Settings <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> General Settings

  2. {eac}SoftwareRegistry License Limitations <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> General Settings

  3. {eac}SoftwareRegistry Distribution <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> Distribution

  4. {eac}SoftwareRegistry Hooks <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> Hooks

  5. {eac}SoftwareRegistry Woocommerce <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> Woocommerce

  6. {eac}SoftwareRegistry Registration <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> Registration

  7. {eac}SoftwareRegistry Add New Registration <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> Add New Registration

  8. {eac}SoftwareRegistry All Registration <span class='eac-product'>{<span class='eac-brand'>eac</span>}SoftwareRegistry</span> All Registrations

Top
Other Notes
  • {eac}SoftwareRegistry is a derivative plugin of and requires installation and registration of {eac}Doojigger.
  • Coming soon: Software product-level defaults and settings.

See Also

Top Top
Change Log

Version 1.0.4 – June 15, 2022

  • Updated "License limitations" by license level.

Version 1.0.3 – May 22, 2022

  • Updated customer email message, include Additional Custom CSS.
  • Added notices to customer email.
  • Added registry_timezone (client timezone).

Version 1.0.2 – May 17, 2022

  • Added "License limitations" by license level.
  • Tweaked transaction id validation & display.
  • Fixed column sorting in "All Registrations".
  • Proper parsing/removal of 'www.' domain prefix.

Version 1.0.1 – Apr 19, 2022

  • Enhanced support for webhooks and subscriptions.
  • Rewrite/condense API field validation.

Version 1.0.0 – Mar 29, 2022

  • After months... Initial stable release.
Top

    Write a Reply or Comment

    Your email address will not be published.


    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>