Integration Guide


  1. Overview
  2. Basic Integration
    1. User APIs
    2. Activities API
    3. Visualization Widgets
  3. Advanced Integration
    1. Advanced Activities API
    2. Custom Widgets - JavaScript SDK
    3. Mobile Interface
    4. Configuration APIs
    5. Behaviour Mapping


The Mambo Gamification Platform allows you to add gamification to any 3rd party software. The platform operates as a backend system providing gamification functionality to systems such as: learning management, project management, intranet portals, customer relationship management tools and any other software which allows integration.

Basic Integration

The basic integration involves 3 separate integration points listed below.

1. User APIs

The target system into which the Mambo Gamification Platform is being integrated must keep it's users in sync with the platform. This means that when users are created, updated or deleted in the target system, calls to the platform should be made to keep the users aligned.

    • LDAP: in an infrastructure which uses a centralised LDAP repository, it is possible to create a simple PHP script which keeps the LDAP in sync with the Mambo platform. This could be run as a cron job in out-office hours.

2. Activities API

This API is used to track the behaviours your users are performing in the target system. There are generally two scenarios to deal with here, one where the target system has an event system, and one where it doesn't:

  • Event System: some target software systems will have an internal event system which holds information about the events taking place. This can usually be tapped into and monitored for the behaviours which you wish to track. To add flexibility in terms of future configuration, this could also be built into an administration screen for the target system which presents the administrator with a list of events from the target software and a list of behaviours from the Mambo platform. These can then be mapped dynamically through this new administration screen saving us development time when we want to add new behaviours.
  • No Event System: in this scenario you will need to identify where the behaviours are taking place and make a call to track the behaviour when it takes place. An ideal solution here would be to add a light event system to send this information to a central handler.

3. Visualization Widgets

These are the widgets used by your end users to visualize their current progress and rewards. The simplest solution here is to use one of the 7 colour schemes available and integrate the SDK into all the pages of the target system. You will then enable specific widgets on specific pages:

  • SDK: the SDK is shared between all the widgets. You should load the JavaScript SDK on every page of the target system.
  • Core configuration: on every page you will need to provide the SDK with properties specific to the user currently viewing the screen. The exception to this is when a user is viewing a different users profile page. In this case we should override the userUuid in the profile widget.
  • Profile Widget: this widget should be placed on a standalone page which is where the user's profile will be accessible. The link to this page is used to configure the link to the profile page from other widgets so it will need to be stored in the target system and added to the widget configuration options when they are added to the page.
  • Header Widget: this widget should be placed in the header of every page in the target software. This widget contains a summary for the user and links to the page with the Profile Widget.
  • Notifications and Toaster Widgets: by adding the SDK to every page, these two widgets will automatically be present on each page and will be triggered when the users unlock rewards or earn points.
  • Leaderboard and Activities Widgets: these two widgets can be added in multiple locations of the target software. For example: an overall activity stream for all the users could be added on the target softwares dashboard, then for each sub-area of the software we could render an activity stream specific to the sub-area.

This will provide basic integration into the Mambo Gamification Platform. See the section below for Advanced scenarios, for example, you may want to render a custom front-end or integration with the points based Activities.


Advanced Integration

Below you will find some additional integration / configuration scenarios you may want to implement using the Mambo Gamification Platforms APIs and configuration options.

1. Advanced Activities APIs

These APIs are used to perform operations related directly to points / coupons and users. Specifically you can use these APIs to perform the following types of point / coupon operations:

  • Manual Point Changes: this type of activity allows you to increment / decrement / refund / redeem a specific number of points to / from a specific user.
  • Gift: this type of activity allows one user to gift another user with points. Points need to have the "Giftable" option enabled in order for this activity type to work. See the Points section of the Administration Panel for more information.
  • Bounty: this type of activity allows a user to set a point bounty on, for example, a question in a forum. Users can then post answers to the question. The original user can then select which answer is the best one and award the user of that answer with the bounty points. Points need to have the "Bountiable" option enabled in order for this activity type to work. See the Points section of the Administration Panel for more information.
  • Coupons: this type of activity allows users to redeem / refund coupons they have earned or wish to exchange for points.

2. Custom Widgets - JavaScript SDK

The widgets offered off-the-shelf come with the ability to change to one of our 7 colour schemes. However, sometimes this is not sufficient and you want to take this a step further. At this point there are two additional routes to creating a custom visualization experience, each with an increased difficulty and time to deliver:

  1. Custom Templates: the JavaScript widgets can have their look & feel completely customised. The widgets support a simple template markup which can be used to override the existing widget templates. The Documentation in the Administration Panel contains all the relevant templates that can be customised and details about how they work.
  2. Custom Build: this involves not using the JavaScript SDK but rather building out your own visualization on top of the JavaScript APIs the platform has. Alternatively this could also be fetching the data through the backend API, generating HTML in the target system and rendering this instead of a JavaScript Widget.

3. Mobile Interface

Interfaces for mobile devices are left in your hands as these will need to be custom fitted for each different use case.

4. Configuration APIs

The APIs used to configure the game mechanics are also available through the Mambo SDKs or through custom SDKs. This means that if you would like to integrate some configuration aspects into the target software's interface, you can do so.

5. Behaviour Mapping

In the case where target software systems have an internal Event System (see above), the Behaviour APIs can be used to retrieve the list of behaviours from the Mambo platform. These can then be displayed in the target system in a custom administration screen, allowing them to be mapped to events being raised in the target software. This makes adding new behaviours to the target software much simpler and removes the need to manually code the new behaviours into the target software.



Article is closed for comments.