playmobjs v0.5.0

Playmob Platform JavaScript Helper Library

API wrapper library into the Playmob Platform.

Setup and Initialisation

Run npm install followed by npm run build to build a minified version of the library suitable to be loaded from the browser.

Copy dist/playmob.min.js into your project, and load up the library at the top of your page (adjust path as needed):

<script src="playmob.min.js" charset="utf-8"></script>

Call the setConfig method and pass in an object with your developer credentials and campaign ID:

Playmob.setConfig({ developerAccessID: "19b902c8f46f5389bc19645a0964f031",
                    developerAPIKey: "e2a61c51a153b5edae976a713496c1e5",
                    campaignID: "172fd2e0145cb992c54ac7401e0f96a6" });

Here, you may also set a test key, and all subsequent API calls will be tagged as such (most notably, this will register test events when reporting them).

Set a debug key to true, and updates will be posted to the browser's console log as the API wrapper is invoked.

You can call setConfig multiple times, and any new config settings will be merged in with the current ones (and overwritten with a new value if the same field already existed). Pass in 'true' as the second parameter to setConfig and all previous settings will be wiped and only the new settings provided will remain.

Player Keys

We use a player_key field to aggregate multiple events coming from a single game session. Any string can be a player key. It could be an internal GUID, a username from a profile system, or just a random string, if your game doesn't have a logged in user.

You can set a default player_key parameter to uniquely identify the player for any later API call made that takes a player key, by adding it in via setConfig.

The default player key can be set separately at a later point via setPlayerKey:

Playmob.setPlayerKey("Bob");

Setting the player key to null, either in setConfig or setPlayerKey will use a randomized string instead, useful for grouping multiple event reports from the same session for analytics purposes:

Playmob.setPlayerKey(null);

Omitting any player key will simply not pass a player_key parameter in API calls at all.

Action ID aliases

After initialisation, you can optionally set up a list of more humanly readable aliases for the User Action GUIDs that the API takes, by passing in an object of alias strings mapped to User Action IDs. Aliases can then be passed into registerEvent in place of the User Action UID ID.

Playmob.setActionAliases({ 'START_GAME': 'ddd344518273bb5f5dbcbf850eb3969f',
                           'REPORT_SCORE': '091e745e346c5525039d4c4c97108149' });

Tracking Events

To register a User Event (signifying that an instance of a previously defined User Action for your campaign has taken place), call the registerEvent method and pass in the User Action ID (or a valid alias from setActionAliases):

Playmob.registerEvent('ddd344518273bb5f5dbcbf850eb3969f');
Playmob.registerEvent('START_GAME');

A callback function can be fed into this method too, to capture the response of the API call:

Playmob.registerEvent('ddd344518273bb5f5dbcbf850eb3969f', function(response, status) {
  console.log(JSON.stringify(response));
});

A successfully registered event will return a user_event_id value, and the test parameter will likely be 'true' during the development phase, if events are registered before a campaign start date has been hit:

{"test":true,"user_event_id":"729433d43ae28914dcc2ee81530100a5"}

Getting Campaign Details and Status

To obtain a JSON document with campaign details, call the campaignDetails method and pass in a callback that will receive a JSON object response back:

Playmob.campaignDetails(function (response, status) {
   console.log(JSON.stringify(response));
});

Among other campaign data, you get back an aggregated list of the User Actions reported back for this campaign, with user_events_created being a count of the number of registered events and actions_taken being the sum of the quantity data sent in for an event (an event's default quantity is 1):

"user_actions": [{
  "name": "Game started",
  "id": "9b36133f908e56f756a66aab16a3560b",
  "actions_taken": 83,
  "user_events_created": 83
}, {
  "name": "Game purchase",
  "id": "90d33db940073242fd4f23b70d20857b",
  "actions_taken": 0,
  "user_events_created": 0
}]

Instead of getting the full campaign details, you can also make a more lightweight call to campaignStatus, which will tell you whether a campaign's budget has been depleted, based on the number of events registered, their individual value and the total budget of the campaign. This allows for a real time change in the game functionality or messaging, if a game can no longer guarantee that an action will result in a contribution towards a social impact e.g..

Optional Parameters

All methods take in a optional object of additional options, which can be used to pass through a player_key ID (if no default was set during setConfig or with setPlayerKey), quantity count or test state for an event where applicable e.g.:

Playmob.registerEvent('ddd344518273bb5f5dbcbf850eb3969f', { quantity: 10, player_key: "Bob", test: true });

In the event that both an options array and a callback function is passed in, pass in the options first, then the callback:

Playmob.registerEvent('ddd344518273bb5f5dbcbf850eb3969f', { quantity: 10 }, function (response, status) {
  console.log(JSON.stringify(response));
});

Debugging

Beyond setting debug to true during setConfig, debug logging to the browser's console is also enabled when a cookie value for PlaymobAPIDebug is set. Thus you could enable debug logging on a production build, by simply running this from the Chrome developer console, assuming your game/app is served via a web server and not from a file:// URL:

document.cookie="PlaymobAPIDebug=1"

Alternatively, you can also add PlaymobAPIDebug=1 to your page URL's query string for the same effect. This works for both file and web served URLs and is a little easier to set up and distribute.

Sample Implementation

Putting all the pieces together, a simple implementation, reporting a few events and then using some of the campaign data in an end screen could look something like this:

// Set your campaign credentials at the beginning, plus use a random player_key
Playmob.setConfig({ developerAccessID: "19b902c8f46f5389bc19645a0964f031",
                    developerAPIKey: "e2a61c51a153b5edae976a713496c1e5",
                    campaignID: "172fd2e0145cb992c54ac7401e0f96a6" },
                    player_key: null);
// Define User Action aliases for legibility and convenience later
Playmob.setActionAliases({ 'START_GAME': 'ddd344518273bb5f5dbcbf850eb3969f',
                           'REPORT_SCORE': '091e745e346c5525039d4c4c97108149' });

// Log an event at the start of the game
Playmob.registerEvent('START_GAME');

// Later, log another event with the current session's score
Playmob.registerEvent('REPORT_SCORE', { quantity: 1063 });

// Show how the player's score compares to the game's average score at the end
Playmob.campaignDetails(function (response, status) {
  // Use the data in the response.user_actions array to calculate the game's
  // average score e.g., via actions_taken / user_events_created for REPORT_SCORE.
});

Further Support

To obtain your developer credentials or for technical integration questions, email support@playmob.com

If, during development, you run into any CORS/Allow Origin related errors calling the API, you may find this Chrome extension helpful.