Skip to content
Browser-side, event-driven JavaScript library for communicating with clopenbadger servers.
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

This is a tiny, event-driven interface to the Clopenbadger API that can be used from Webmaker Applications to display earned & available badges for users, as well as credit user behaviors.


All prerequisites are contained in the vendor directory.

Currently this library needs requirejs, jquery, and a special module called backbone-events, which simply contains the Backbone.Events implementation. If your project already uses Backbone, you can use a much smaller version of the library, or you can create your own shim that uses your own eventing library as an implementation.

Optionally, this library supports the postmessage-proxied-xhr (PPX) library to allow browsers without CORS support to communicate with a Clopenbadger server on a different origin.


For any details not specified by the following documentation, see the test suite at test/all-tests.js for more information.


Create a Clopenbadger instance like this:

var badger = Clopenbadger(options);

options is an object with the following keys:

  • server - The URL to the server that hosts a Clopenbadger API, e.g. It should not have a / at the end.

  • token: The JSON Web Token to authenticate with the Clopenbadger server. Construction of this token is explained in the Clopenbadger API documentation.

  • email: The email address of the user that badge operations will be for.


A Clopenbadger instance emits the following events:

  • ready - Emitted once the Clopenbadger server has been contacted and initial metadata about available badges and earned badges has been retrieved. Mutually exclusive with the error event.

  • error - Emitted when an initialization error occurs. Mutually exclusive with the ready event.

  • change:availableBadges - Emitted when metadata about available badges has changed.

  • change:earnedBadges - Emitted when metadata about the current user's earned badges has changed.

  • change:unreadBadgeCount - Emitted when the number of new badges a user hasn't seen yet has changed.

  • award - Emitted when one or more badges have been awarded to the user. The single argument passed is an array of shortnames of the badges that have been awarded.


A Clopenbadger instance has the following methods:

  • credit(shortname) - Credits the behavior with the given shortname to the user. If a badge is awarded as a result of the credit, an award event is triggered.

  • markAllBadgesAsRead() - Marks all the user's badges as read (i.e., seen by the user). If the number of unread badges has changed as a result of this call, a change:unreadBadgeCount event is triggered.

  • getBadges() - Returns an array of objects containing combined metadata about badge types and issuance (if any) for the current user.


All of the following properties are read-only.

  • unreadBadgeCount - The number of unread badges that the user has.

  • availableBadges - An object mapping badge shortnames to their metadata. Information about issuance is not contained here.

  • earnedBadges - An object mapping earned badge shortnames to their issuance metadata.


The module at test/fake-clopenbadger-server.js provides a class that uses jQuery Ajax Transport middleware to run a fake Clopenbadger "server" in the embedding webpage and return fake responses. This is used by Clopenbadger's test suite, but may also be useful for testing your own code.

Something went wrong with that request. Please try again.