Skip to main content

The badge builder SDK

Overview

To facilitate development of third-party Credly integrations, the Credly badge builder is now available in a standalone embeddable format.

To ensure only Credly developers can embed the Credly badge builder, the Credly website allows you to exchange your Credly API access token for a badge builder token good for exactly one embedded instance of the Credly badge builder.

Once your users finish using the badge builder and save their image, your application can use the image and associated metadata to create a badge with Credly or any other badge platform.

Token exchange

To exchange your Credly API access token for a badge builder token, simply make a POST request to /badge-builder/code as follows:

					
						POST /badge-builder/code HTTP/1.1
						Host: credly.com
						Content-Length: 141

						access_token=(access_token)

						{
						"success": true,
						"temp_token": "604ca52b29e02299f9c5286f0f37ef1a"
						}
					
				

The badge builder can now be embedded exactly once with a GET request to /badge-builder/embed/:code as follows:

					
						<iframe
						frameborder="0"
						scrolling="no"
						width="960"
						height="540"
						src="https://credly.com/						badge-builder/embed/(temp_token)">
						</iframe>
					
				

Important: to ensure the security and integrity of your Credly application, be sure to conduct this token exchange as a backend request made by your web server or application server. Clear-text access tokens can be detected using any modern browser.

Capturing output

When badge image generation is complete, a Continue button will appear beneath the badge builder. Clicking this button will dispatch a MessageEvent using the window.postMessage JavaScript API on the parent element of the iframe (your page's window).

A MessageEvent enables safe cross-origin transporation of badge data, and avoids issues with the same-origin policy on modern browsers. The window.postMessage API is supported by all browsers the Credly badge builder is tested in.

Once you have correctly implemented a listener that intercepts messages from the domain https://credly.com, you should be able to capture the badge data in a script running on your web application's server. Here's a basic example:

					
						window.addEventListener("message", function(e) {
						if (
						e.origin ===
						"https://credly.com" &&
						typeof (data = e.data) === "object"
						) {
						var myBadge = document.getElementById("my-badge");

						// Copy data from the badge builder iframe into a local object
						myBadge.imageUrl = data.image;
						myBadge.iconInfo = data.iconMetadata;
						myBadge.extraParameters = data.packagedData;

						// Remove the badge builder
						document.getElementById("badge-builder").remove();
						}
						});
					
				

The JSON object passed to your page's credlyBadgeSuccess method will always contain the keys image and extraParameters, and will also contain the key iconMetadata unless your users choose to uplaod their own icon. Be sure to correctly attribute the author of the icon from The Noun Project in your web application.

If you're making a Credly badge and want your users to be able to modify it on credly.com, simply merge the "extra" parameters in with the API call to create the badge.

Here's a working example of the techniques described above:

Here it is:

Extra parameters: