{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 {eac}SoftwareRegistry 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 Custom Hooks

With the {eac}SoftwareRegistry Custom 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.

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_title'        => 'Product Title',                 //   your product title
    '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_title'        -> 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.

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

Automatic Plugin Installation

Due to the nature of this plugin, it is NOT available from the WordPress Plugin Repository and can not be installed from the WordPress Dashboard » Plugins » Add New » Search feature.

Upload via WordPress Dashboard

Installation of this plugin can be managed from the WordPress Dashboard » Plugins » Add New page. Click the [Upload Plugin] button, then select the eacSoftwareRegistry.zip file from your computer.

See Managing Plugins -> Upload via WordPress Admin

Manual Plugin Installation

You can install the plugin manually by extracting the eacSoftwareRegistry.zip file and uploading the 'eacSoftwareRegistry' folder to the 'wp-content/plugins' folder on your WordPress server.

See Managing Plugins -> Manual Plugin Installation

Activation

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

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

Updates

Updates are managed from the WordPress Dashboard » 'Plugins' » 'Installed 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 information 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.

Deactivation

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

Uninstall

When uninstalled, the plugin will delete custom tables, settings, and transient data based on the options selected in the general settings. If settings have been backed up, the backup is retained and can be restored if/when re-installed. Tables are not backed up.

1. {eac}SoftwareRegistry General Settings

2. {eac}SoftwareRegistry License Limitations

3. {eac}SoftwareRegistry Distribution

4. {eac}SoftwareRegistry Hooks

5. {eac}SoftwareRegistry Woocommerce

6. {eac}SoftwareRegistry Registration

7. {eac}SoftwareRegistry Add New Registration

8. {eac}SoftwareRegistry All Registration

Additional Information

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

See Also

• Implementing the Software Registry SDK
• {eac}SoftwareRegistry Custom Hooks
• {eac}SoftwareRegistry WebHooks for WooCommerce
• {eac}SoftwareRegistry Subscriptions for WooCommerce

Copyright © 2019-2022, EarthAsylum Consulting, All rights reserved.

This is proprietary, copyrighted software.

• Title to the Software will remain the exclusive intellectual property of EarthAsylum Consulting.

• You, the customer, are granted a non-exclusive, non-transferable, license to access, install, and use this software in accordance with the license level purchased.

• You are not permitted to share, distribute, or make available this software to any third-party.

See: EarthAsylum Consulting EULA

Version 1.2.0 – November 20, 2022

• Updated for WordPress 6.1 and {eac}Doojigger 2.0.
• Improved auto-updater (through {eac}Doojigger).
• Added contextual help.
• Updated registration code.
• Updated {eac}SoftwareRegistry distribution kit.

Version 1.1.0 – September 21, 2022

• Added settings_refresh_intervals filter.
• Enhanced environment check on load.
• Improved registry value sanitization.
• Added new 'registry_title' value for short title (i.e. plugin name)
• Added filter to exclude 'softwareregistry' comments from WP comment query.
• Disable title field in custom post editor.
• Moved license limitations to new extension.
• Changed tab 'License Limitations' to 'License Limits'.
• Information updates to the distribution tab.
• Client and admin email can be styled in dashboard Additional Custom CSS
  • body class = 'eacSoftwareRegistry-email'
  • registration table class = 'eacSoftwareRegistry-table

Version 1.0.8 – August 26, 2022

• Only add actions when is_admin() (not on front-end).
• Updated for {eac}Doojigger 1.2
• Standardized settings link url with $this->getSettingsLink().
• Standardized documentation link url with $this->getDocumentationLink().

Version 1.0.7 – August 5, 2022

• Updated documentation and directory structure.
• Support eacSoftwareRegistry Custom Hooks v2

Version 1.0.6 – July 29, 2022

• Updated filter used in custom hooks.

Version 1.0.5 – July 15, 2022

• Updated registration extension.

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.

Requires {eac}Doojigger version 2.0+