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 = null, $types = null, $signupURL = null)

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

$parentID (optional) - The parent account ID of the new child account created. If blank, the account ID of the application will be used.

$types (optional) - A null|string|array of tha parents direct child types to select from at the sign up page.
  • null (default) - All child types of the parent account.
  • string (type code) - One specific child type.
  • array (type codes) - Multiple specific child types.
// Tip: Use an incoming URL to set method arguments.

// http://site.com/net/?p=acc_xxx&t=foo

$appSpice
  ->initAllowNewAccountSignup($_GET['p'], $_GET['t'])
  ->initialize();

// or ...

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

switch($_GET['signup']){
  case 1: $p = null; $t = null; break;
  case 2: $p = 'acc_xxx'; $t = 'foo'; break;
  case 3: $p = 'acc_xxx'; $t = array('foo','bar'); break;
  default: $p = 'invalidValue'; $t = 'invalidValue'; break;
  // ...
}

$appSpice
  ->initAllowNewAccountSignup($p, $t)
  ->initialize();

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

$signupURL (optional) - A string value for an external link that can be used for creating accounts via the sign in pages. Replacement tokens (%%accountID%%) can be used for including environment values. This value will be included in the environment array for use elsewhere in your project.
$appSpice
  ->initAllowNewAccountSignup(null, null, 'https://mysite.com/?p=%%accountID%%')
  ->initialize();

// later...

Allow accounts to sign up using this link <?= $appSpice->env['account']['signupURL'] ?>!
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.