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.

Note

To keep the JavaScript key off the browser and avoid direct browser calls to Mambo, you can point the widgets at a backend proxy instead of at https://api.mambo.io. See Backend proxy.

Prerequisites

API key and site URL

To use the JavaScript SDK, you'll need:

Widgets API key — found on the API keys page in the administration panel
Site URL — found on the Sites page in 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 from the Approved URLs tab of an API key on the API keys 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'
    },
    users: {
      resolver: function( uuids, ctx ) {
        // Return the details of these users, or a promise of them
        return fetch( '/my/directory?ids=' + uuids.join(',') )
          .then( function( response ) { return response.json(); } );
      },
      search: function( query, ctx ) {
        // Return the users matching this query, or a promise of them
        return fetch( '/my/directory?q=' + query )
          .then( function( response ) { return response.json(); } );
      },
      data: null,
      timeout: 10000
    }
  });
});

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
users resolver	Function supplying the details of the users the widgets are about to display, so that they can be named and pictured from your own records rather than Mambo's	No	null	function(uuids, ctx) { return fetch(...); }
users search	Function searching your own users, used by the Gift widget in place of Mambo's search	No	null	function(query, ctx) { return fetch(...); }
users data	A map of uuid to user details, used in place of a resolver when the data is already on the page	No	null	{'0001': {firstName: 'Ana'}}
users timeout	Milliseconds to wait for the resolver before rendering with the data already to hand	No	10000	30000
debug	Whether to output debug messages to the console	No	false	true

Supplying your own user data

A user's name is optional in Mambo. Where a user has no first name, last name or display name, the widgets show them under the Anonymous label rather than leaving them out, so that they keep their place on a leaderboard and their activity still appears in the feed.

This lets you run Mambo without sharing your users' personal data with us. Give us a user uuid and nothing else, and supply the names and pictures yourself through the users options.

Naming the users on the page

Mambo tells you which users it is about to display, and you answer with their details. Whatever you supply takes precedence over what Mambo holds, field by field, so you can correct a name and still use the picture Mambo has.

JavaScript

Mambo.init({
  // ... your other options
  users: {
    resolver: function( uuids, ctx ) {
      // uuids  - the users Mambo is about to show, minus any it has asked about already
      // ctx    - { widget: 'leaderboard', users: [ the raw user objects ] }
      return fetch( '/my/directory?ids=' + uuids.join(',') )
        .then( function( response ) { return response.json(); } )
        .then( function( people ) {
          // Answer with a map of uuid to details. Every field is optional.
          return people.reduce( function( map, person ) {
            map[ person.mamboUuid ] = {
              firstName: person.givenName,
              lastName: person.familyName,
              displayName: person.nickname,
              pictureUrl: person.avatarUrl
            };
            return map;
          }, {} );
        } );
    }
  }
});

The resolver may answer with the map directly, or with a promise of one. A given user is only ever asked about once per page load, and the answer is shared by every widget, so paging through a leaderboard or switching its period costs nothing for the people already shown.

Note

The widgets wait for your resolver before they render, so that a name is never shown and then replaced. If it does not answer within users.timeout, they render with the data already to hand and ask again on the next render. If it fails, the widgets still render, using whatever names Mambo holds.

If your users' details are already on the page, supply them directly instead of writing a resolver:

JavaScript

Mambo.init({
  // ... your other options
  users: {
    data: {
      '0001': { firstName: 'Ana', lastName: 'Silva', pictureUrl: '/avatars/ana.png' },
      '0002': { displayName: 'marco_r' }
    }
  }
});

Finding someone to give a gift to

The Gift widget searches for a recipient by name. Mambo can only match on the names it holds, so if you have not shared them it finds nobody, and a gift cannot be given at all. Supply users.search and the widget asks you instead.

Return whatever users match, each carrying at least a uuid. That is what the gift is actually sent to, so you are free to name them however you like.

JavaScript

Mambo.init({
  // ... your other options
  users: {
    search: function( query, ctx ) {
      // ctx - { tags, tagsJoin } from the widget, should you wish to honour them
      return fetch( '/my/directory?q=' + encodeURIComponent( query ) )
        .then( function( response ) { return response.json(); } )
        .then( function( people ) {
          return people.map( function( person ) {
            return {
              uuid: person.mamboUuid,
              firstName: person.givenName,
              lastName: person.familyName,
              pictureUrl: person.avatarUrl
            };
          } );
        } );
    }
  }
});

Every widget that shows users also takes userResolver, userData and, for the Gift widget, userSearch as render options. These take precedence over the ones configured here, and are useful when one widget on the page draws its users from somewhere else.

Gifts you have received

The message naming who gave you a gift keeps a record of the giver taken at the moment of the gift, and that record does not carry the uuid your resolver is keyed on. A gift from a user who has no name in Mambo therefore shows as Anonymous, and cannot presently be corrected by supplying your own data.

Prerequisites​

API key and site URL​

Approved URLs​

Content Security Policy​

Loading and initialisation​

On-premise installation​

Initialisation options​

Options reference​

Supplying your own user data​

Naming the users on the page​

Finding someone to give a gift to​

Per widget​

Prerequisites

API key and site URL

Approved URLs

Content Security Policy

Loading and initialisation

On-premise installation

Initialisation options

Options reference

Supplying your own user data

Naming the users on the page

Finding someone to give a gift to

Per widget