PHP

Below is a full-code example of using the Serial Sense Licensing API with PHP. To help you understand how you may write your own module, the example code is broken into segments, and each segment is explained.

API Constants

Below is a list of constants to either include in your class or define globally:

define('API_LOCATION',	'http://www.serialsense.com/api/');
define('API_SIGNATURE',	'replace_with_your_developer_signature');
define('API_KEY',		'replace_with_your_developer_key');

API Parameters

All Licensing API parameters are stored in this single array. Note that 'call' and ‘type’ are the only required indexes here. 'call' is the name of the API call, and 'type' is the type of API credentials–’developer’ by default, or ‘application’–to use with the API call.

$parameters = array(
	'call' => '',
	'type' => 'developer'
	);

Calling the API – General

When calling the API, you need to know whether you are calling a Developer function or an Application function. Remember, Developer functions require your developer API signature, while Application functions require your developer API key. This is handled in the $parameters array. This function accepts the array $p, which should be set to the API parameters specified above. LicenseAPI() returns false if there was a problem with the parameters array. On success, the API call’s return string is ultimately returned.

function LicenseAPI(array $p) {
	// check for required indexes!
	if (!isset($p['call']) || !isset($p['type']))
		return false;
 
	// create credentials API parameter
	$credentials     = ($p['type'] == 'developer') ? 
	$p['sig']    = API_SIGNATURE : 
	$p['apikey'] = API_KEY;
 
	/**
	 * before we generate our data string, remove items from parameter 
	 * array that are not actual API parameters.
	 */
	$call = $p['call'];
	unset($p['call']);
	unset($p['type']);
 
	// generate our URL
	$api_url  = API_LOCATION . $call;
 
	// get the API call result
	$curl = curl_init($api_url);
	curl_setopt($curl, CURLOPT_POST,              true);
	curl_setopt($curl, CURLOPT_POSTFIELDS,        $p);
	curl_setopt($curl, CURLOPT_CONNECTIONTIMEOUT, 10);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER,    1);
	$result = curl_exec($curl);
 
	// finished!
	curl_close($curl);
	return $result;
}

Calling the API – Create a New License for Customer

The API call to create a new license will return the new License Activation Code upon success. Notice that the parameters array is copied and then edited for this specific call. To protect your developer account, do NOT deploy this code to where the end user might have access to it.

// create a single-machine license for the end user.
$params = $parameters;
$params['call']  = 'create';
$params['email'] = 'enduser@example.com';
// upon creation, email the license code to end user
$params['send']  = 1;
 
$license = LicenseAPI($params);
if (! $license)
{
	echo "Error! There is something wrong with your parameters.";
}
else
{
	echo "The API returned the following:<br>";
	print_r($license);
}

Calling the API – End User License Activation

On the end users’ side of your application’s code, you will always do activation at least once. Remember that the license activation API call will return the license alias upon success. Here’s an example of activating the end user’s machine to use a license code:

// activates a machine using the license activation code
$params = $parameters;
$params['call'] = 'activate';
$params['type'] = 'application';
// user's activation code
$params['code'] = $_POST['license_code'];
// to generate the machine's code
$params['mach'] = MachineCode();
 
$license = LicenseAPI($params);
if (! $license)
{
	echo "Error! There is something wrong with your parameters.";
}
else
{
	// look at example output below
}

Notice the function MachineCode(). This would be your defined function to generate the user’s never-changing machine code. Examples of the machine code may be generated from:

  • A random string of data discretely stored on end user’s system.
  • The end user website base URL.
  • The end user IP address–not recommended unless your user agreement specifies a static IP!
  • An MD5 of the activation time, discretely stored.

Example output: Upon success, the API returns the license’s alias. Remember: for end-user security purposes, the license alias is safe to save to the user’s hard drive or local database; the alias cannot be used to activate a machine! Below is a raw, unformatted string–as if the output was copied-and-pasted into a plain text file:

<license>
XLM-456XII-PIA

Calling the API – Authorizing a License Alias

Remember that when checking for a license’s authenticity, you will use the stored license alias. Refer to the Application API for parameter requirements and return values.

$params = $parameters;
$params['call'] = 'auth';
$params['type'] = 'application';
// GetLicenseAlias() should grab the license alias from file or DB
$params['code'] = GetLicenseAlias();
$params['mach'] = MachineCode();
$license = LicenseAPI($params);

Leave a Reply

Your email address will not be published. Required fields are marked *

*

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=""> <strike> <strong> <pre lang="" line="" escaped="">

This site is using OpenAvatar based on