API initialization

How to initialize the API and use the return values.


API class instantiation

In it's simplest form, all that's necessary is the single AppSpice class file. The class can be instanced in application and network modes.

$appSpice = new AppSpice([apiKey], $networkMode = false);

In application mode (default), the API will only recognize the account directly associated with the API key provided. Use this mode to define the project and optionally develop a network of participating accounts.

In network mode (optional), the API will only recognize the accounts created while in this mode. Use this mode to distribute versions of the project across defined account type hierarchies that share the same project interests.

API initialization

The API should be initiated on every page load to return the current environment. You can determine the best use method based upon your framework or other page logic.

$appSpice->initialize();

This single method will remotely authenticate users and provide the current environment.

Method Description
initialize()* Minimum required method. This method alone will remotely log in a user and return the current environment back to the calling script.
initSigninReturnURL($url) By default, a remotely authenticated user will be returned back to the page where the AppSpice class was initialized. To alter this process, provide a specific $url to return the signed in user once the remote sign in process is completed.
initAllowNewAccountSignup(
$parentID*, $typeFilter = null)

Network accounts are typically added by the parent account via their user interface. This option will allow new $parentID accounts to be created at the signin pages.

$parentID (required) - The parent account ID for the new account being created.

$typeFilter - A null|string|array of network account types to select from at the sign up page.
  • null (default) - Only types that are direct children of the $parentID. Useful for identifying the top tiers of the accounts network.
  • string (parent type code) - Only the child types of the type code provided. Useful for identifying specific branches of the $parentID network.
  • array (type code(s)) - Only the specific type(s) identified in the array. Useful for identifying one or more of the $parentID types.
  • asterisk(*) symbol - All types related to the $parentID.
// Tip: Use an incoming URL to set method arguments.

// http://site.com/net/?pid=acc_xxx&typ=typeCode123

$appSpice
  ->initAllowNewAccountSignup($_GET['pid'], $_GET['typ'])
  ->initialize();

// or ...

// http://site.com/net/?signup=1

switch($_GET['signup']){
  case 1: $id = 'acc_xxx'; $filter = 'code123'; break;
  // ...
}

$appSpice
  ->initAllowNewAccountSignup($id, $filter)
  ->initialize();

The create new account option will not be offered if either the $parentID or $typeFilter is invalid.

initNewAccountProposedFee($percent) If you allow creation of new accounts at the signup pages, this option will set the initial gainsharing fee to collect from their revenue earned through the system. Enter a whole number (e.g. 5.25) without the percent sign. This fee will have to be accepted by the new account before implementation.
initNewAccountFunction($functionName) If provided, $functionName will be called upon returning to the API after a new account has been created. The API uses the PHP call_user_func function to achieve this. Learn more about the PHP call_user_func here
initDeveloperEmailAddress($emailAddress) Error alerts that would not be displayed on a form page (invalid system parameters, etc) will be emailed to this address if provided.
initEnforceUserAgreement() If provided in your account settings, the system will enforce your User Agreement at the sign in pages. Users are automatically required to update their acceptance each time you update the agreement.