How can I listen to JavaScript events posted from embeds?

Malcolm! embeds fire events on user interactions such as when someone first reads an FAQ, completes a Workflow or performs a search. These events can be picked up on your web page for you to perform custom actions - for example creating an event for your Analytics.

How can I listen to these events?

The first event, mapiload, is fired on the window when the mapi.js library has loaded.

window.addEventListener('mapiload', function() {
  // mapi has loaded, waiting for embeds to render

  // ...
});

The embeds are then rendered followed by the mapi.onrender event.

To register a listener use the mapi.on function.

window.addEventListener('mapiload', function() {
  // mapi has loaded, waiting for embeds to render

  mapi.on('render', function() {
    // Embeds rendered

    // ...
  });
});

We recommend combining the window.addEventListener and mapi.on functions for maximum compatibility especially if your application uses JavaScript page transitions, however if your application reloads the page on each request you could combine these into one.

window.addEventListener('mapiready', function() {
  // Embeds rendered

  // ...
});

Once the embeds have rendered use the embed.on function to register listeners.

If you know the ID of the embed (can be found in MyMalcolm) use mapi.findEmbed function.

mapi.findEmbed('EMBED_ID').then(function(embed) {
  // Embed found

  embed.on('EVENT_NAME', function(data) {
    // Data returned from embed

    // ...
  });
});

Alternatively loop through the mapi.embeds array.

mapi.embeds.forEach(function(embed) {
  embed.on('EVENT_NAME', function(data) {
    // Data returned from embed

    // ...
  });
});

Putting it all together your code snippet could look something like this.

<script src="https://apis.malcolm.app/mapi.js?id=INSTANCE_ID" async defer></script>
<script>
  window.addEventListener('mapiload', function() {
    // mapi has loaded, waiting for embeds to render

    mapi.on('render', function() {
      // Embeds rendered

      mapi.findEmbed('EMBED_ID').then(function(embed) {
        // Embed found

        embed.on('EVENT_NAME', function(data) {
          // Data returned from embed

          // ...
        });
      });
    });
  });
</script>

What events are available?