Setup and configuration

This section covers everything you need to get started with the JavaScript SDK, from obtaining your API credentials to initializing the SDK on your website.

Prerequisites

API key and site URL

To use the JavaScript SDK, you'll need:

Widgets API Key - Found in the API Keys area of the administration panel
Site URL - Found in the Sites area of the administration panel (the content of the URL column)

These credentials authenticate your website with the Mambo platform and determine which gamification site configuration to use.

Approved URLs

The most frequent troubleshooting issue with the JavaScript SDK is not configuring the allowed domains correctly. Access must be specifically granted to each domain/website that will use the SDK.

Define these URLs in the Approved URLs area of the API keys management page.

Note

The Approved URLs feature accepts the wildcard character (*) for matching subdomains and directory paths. This avoids having to define each individual URL. For example, to include all subdomains, use: _.domain.com/\*

Content Security Policy

The JavaScript widgets, along with required fonts and images, are loaded dynamically from Mambo's servers. To allow this, you must modify your site's Content Security Policy to include Mambo's servers as trusted sources.

Add https://versions.mambo.io to the following CSP fetch directives:

script-src
img-src
font-src

Example CSP header:

HTTP

Content-Security-Policy: default-src 'self'; script-src 'self'
https://versions.mambo.io; img-src 'self' https://versions.mambo.io; font-src
'self' https://versions.mambo.io;

Loading and initialisation

The following code should be placed directly after the <body> tag of your HTML page:

JavaScript

// Initialise the Mambo JavaScript SDK
var mamboCallbacks = window.mamboCallbacks || [];
mamboCallbacks.unshift(function() {
  Mambo.init({
    apiRoot: 'YOUR_DOMAIN_URL', // Insert here your Domain URL
    key: 'YOUR_JAVASCRIPT_KEY', // Insert here your JavaScript API key
    site: 'YOUR_SITE_URL', // Insert here the Site URL to use
    userUuid: '0001', // This is the Unique Identifier for the current user
    lang: 'en' // Localisation settings. Currently supported: pt (Portuguese) and en (English)
  });
});

// Load the Mambo JavaScript SDK Asynchronously
// Note: the default script is bundled with jQuery. If jQuery is
// already available, then set the function flag to false.
(function( jqueryVersion ) {
  var script = document.createElement('script');
  var entry = document.getElementsByTagName('script')[0];
  script.async = true;
  script.src = 'https://versions.mambo.io/docs/YOUR_MAMBO_VERSION/widgets/mambo' + (jqueryVersion ? '.jquery' : '') + '.min.js';
  entry.parentNode.insertBefore(script, entry);
}( true ));

The mamboCallbacks array is also used to load widgets at any point on the page by adding functions to the array. For example, to load the Activities widget:

JavaScript

// Load the Activities widget
var mamboCallbacks = window.mamboCallbacks || [];
mamboCallbacks.push(function() {
  Mambo('.activities').activities();
});

Note

Make sure Mambo.init() is the first function added to the mamboCallbacks array; otherwise, the SDK will not load properly.

Note

The userUuid parameter should be set to the unique identifier of the currently logged-in user. This UUID is set when you create the user.

On-premise installation

If you:

Cannot link to an external domain
Prefer to always use the latest widgets version, and
Have an on-premise Mambo licence

You can access a local copy of the latest version of the widgets:

Copy the widgets folder from webapp/ROOT/docs/widgets to webapp/ROOT/static/widgets
Before initializing the Mambo Widgets, set the Mambo.Static.versionRoot variable:

JavaScript

var mamboCallbacks = window.mamboCallbacks || [];
mamboCallbacks.unshift(function() {
  Mambo.Static.versionRoot = "http://YOUR_HOSTNAME:YOUR_PORT/static"; // THIS IS THE LINE TO ADD
  Mambo.init({
    apiRoot: 'YOUR_DOMAIN_URL', // Insert here your Domain URL
    key: 'YOUR_JAVASCRIPT_KEY', // Insert here your JavaScript API key
    site: 'YOUR_SITE_URL', // Insert here the Site URL to use
    userUuid: '0001', // This is the Unique Identifier for the current user
    lang: 'en' // Localisation settings. Currently supported: pt (Portuguese) and en (English)
  });
});

Initialisation options

The Mambo.init() function accepts numerous configuration options. Here's a complete example showing all available options:

JavaScript

// Initialise the Mambo JavaScript SDK
var mamboCallbacks = window.mamboCallbacks || [];
mamboCallbacks.unshift(function() {
  Mambo.init({
    apiRoot: 'YOUR_DOMAIN_URL',
    key: 'YOUR_JAVASCRIPT_KEY',
    site: 'YOUR_SITE_URL',
    userUuid: '0001',
    lang: 'en',
    importFB: true,
    fbAppId: 'YOUR_FACEBOOK_APP_ID',
    importTwitter: true,
    twitterVia: 'mambo_',
    socialUrl: 'http://mambo.io',
    profileUrl: 'http://domain.com/profile.page',
    theme: 'blue',
    rewardCounter: true,
    hideMissionRewards: {
      achievements: false,
      levels: false,
      gifts: false,
      missions: true
    },
    levelGroups: [{
      label: 'Overall Experience',
      tags: ['primary_level'],
      isPrimary: true,
      noLabels: false
    }, {
      label: 'Wiki Mastery',
      tags: ['wiki_level']
    }],
    authentication: {
      redirectToLogin: true,
      overrideLoginUrl: null,
      useCurrentPageAsRedirectUrl: true,
      overrideRedirectUrl: null
    },
    tags: {
      show: false,
      withPersonalization: false
    },
    notifications: {
      withShowMore: false,
      withActivities: false,
      withPrizesOnly: true,
      clearOnUnload: false,
      autoCloseTimeout: 5000,
      position: 'bottomright'
    }
  });
});

Note

There should only be a single call to the Mambo.init() function on the page, and it must be the first function supplied to the mamboCallbacks array.

Options reference

Option	Description	Required	Default Value	Sample Value
apiRoot	Root URL where the API can be found	Yes	N/A	https://domain.com
key	JavaScript API Key from the API Keys panel	Yes	N/A	88342e5c41d748359a6
site	Site URL from the Sites panel	Yes	N/A	acmeinc
userUuid	Unique identifier for the current user	Yes	N/A	0001
lang	Language for the widgets (pt, en, or custom)	No	pt	en
importFB	Whether to load the Facebook SDK if not already present	No	false	true
fbAppId	Facebook App ID (required if importFB is true)	No	N/A	123456789900123
importTwitter	Whether to load the Twitter Widgets SDK	No	false	true
twitterVia	Twitter handle to associate with shared tweets	No	N/A	mambo_
socialUrl	Custom URL for social sharing (overrides default site URL)	No	N/A	http://mambo.io
profileUrl	URL for the user's profile page	No	null	http://domain.com/profile
theme	Colour theme for widgets (grey, blue, orange, yellow, red, green)	No	blue	grey
rewardCounter	Whether to display the number of times rewards have been unlocked	No	true	false
hideMissionRewards	Controls visibility of rewards that are part of missions	No	{achievements: false, levels: false, gifts: false, missions: true}	{achievements: true, levels: true, gifts: false, missions: true}
levelGroups	Configures which levels should be used as primary levels	Yes	null	[{label:'Overall',tags:['primary'],isPrimary:true}]
levelGroups label	Label for a group of related levels	Yes	null	Overall Experience Levels
levelGroups tags	Tags to identify levels belonging to this group	Yes	null	marketing
levelGroups isPrimary	Whether this is the primary level group	Yes	null	true
levelGroups noLabels	Whether to render levels as a single list without group labels	Yes	null	true
authentication redirectToLogin	Whether to redirect to login page when authentication is required	No	true	false
authentication overrideLoginUrl	Custom login page URL	No	null	https://mysite.com/my-login-page
authentication useCurrentPageAsRedirectUrl	Whether to redirect back to current page after login	No	true	false
authentication overrideRedirectUrl	Custom redirect URL after successful login	No	null	https://mysite.com/go-here
tags show	Whether to display tags associated with rewards	No	false	true
tags withPersonalization	Whether to retrieve data with personalization	No	false	true
notifications withShowMore	Whether notification prizes should be hidden behind a Show More link	No	true	false
notifications withActivities	Whether notifications created by activities should include the activity	No	false	true
notifications withPrizesOnly	Whether to only show notifications with prizes	No	true	false
notifications clearOnUnload	Whether to mark notifications as read when user leaves the page	No	false	true
notifications autoCloseTimeout	Milliseconds before notifications auto-close (null = never)	No	null	5000
notifications position	Position for notifications (bottomright, bottomleft, topright, topleft)	No	bottomright	topleft
debug	Whether to output debug messages to the console	No	false	true

Prerequisites​

API key and site URL​

Approved URLs​

Content Security Policy​

Loading and initialisation​

On-premise installation​

Initialisation options​

Options reference​

Prerequisites

API key and site URL

Approved URLs

Content Security Policy

Loading and initialisation

On-premise installation

Initialisation options

Options reference