Embedded Badge Designer

Include Accredible's badge design tool within your own platform to give your users the ability to create and edit their own badge designs.

As an OEM provider or reseller of digital badges, it's easy to embed our design tool within your own platform. In this guide, we'll walk through the workflow for including the tool inside your platform and its usage.

You'll need to consume our API via a back-end server and consume this response within your front-end to embed the designer.

Workflow

The embedded badge designer workflow is:

  1. Token exchange.
  2. Instantiate iFrame.
  3. User interaction.
  4. Capture output.

Token Exchange

The first step is to make an API request to get an authentication token for the badge designer.

https://accrediblecredentialapi.docs.apiary.io/#reference/designs/badge-designer/initialize-embedded-badge-designer

You may include a design ID if you'd like to edit an existing design in this request. Omitting it will result in a new design. You may also include a department ID if you'd like the design to reside within a particular department (if you have multiple departments set up).

Once you've made the request, you'll receive a response like this:

{
"token": "abc123...xyz456",
"design_id": 12345
}

Once instantiated, a token is valid for 4 hours unless in use or re-instantiated.

Instantiate iFrame

The badge designer can now be embedded within your platform. 

<iframe src="https://embed.badge.design/?authorization={Bearer TOKEN}&id={DESIGN_ID}

Replace the variables as indicated in this example to build a URL for creating a badge design that appears as so, specifically prepending Bearer and a space before the token:

<iframe src="https://embed.badge.design/?authorization=Bearer%20abc123xyz456

And for editing a badge design as so:

<iframe src="https://embed.badge.design/?authorization=Bearer%20abc123xyz456&id=12345

We recommend instantiating the iFrame using Javascript to make the badge designer full screen easily and so that you can show and hide it as required.

Full list of parameters that can be passed to the URL in the frame:

Parameter Required? Value Notes
authorization Yes authentication token Provides session authentication for the badge design user. Must begin with "Bearer "
id No design ID Indicates that the designer should edit an existing design, rather than create a new one.
disable_name_edit No true | false Prevents the user from editing the name of the given design.
my_designs No Comma-separated design IDs, with no spaces Limits the available existing badge designs shown in the 'My Designs' section of the badge designer.

User Interaction

Once the iFrame has been instantiated and is shown, the end-user can work with the designer to create or edit their badge design.

Screenshot 2019-08-28 at 15.17.27

Capture Output

Once the user clicks 'Save,' then the iFrame will dispatch a MessageEvent using the window.postMessage JavaScript API on the parent element of the iFrame (your page window).

This JSON message contains the following properties:

  • id - The ID of the design that has been created or updated.
  • rasterized_content_url - A link to generate an image of the design.
  • encoded_content - A string representing the content of the design. This may be stored and used to instantiate or edit designs via the API at a future time.

To consume this data, you need to implement a listener that intercepts messages from the domain https://embed.badge.design. This listener can then be used to capture the badge design data for use within your platform.

Here's an example listener:

window.addEventListener('message', function(e) {
if (e.origin === "https://embed.badge.design" && typeof (data = e.data) === 'object') {
console.log('Completed:', data.completed);
console.log('Status:', data.status);
console.log('Id:', data.design.id);
console.log('Rasterized Content Url:', data.design.rasterized_content_url);
console.log('Encoded Content:', data.design.encoded_content);
}
});

Example

Accredible has prepared an example JSFiddle with HTML and Javascript to get you started. Visit the link below and enter the response information from the token exchange in Step 1.

https://jsfiddle.net/accredible/k70ghdtv/ 

Alternatively, you can find the example here: https://cdn.accredible.com/remote-demo.html

Has this article helped you? Let us know!

If you would like to tell us about any improvements you feel could be made to this page, you can email us at support@accredible.com.