Errors and Events

There are two ways of tapping into events from the Lite embed; the error event handlers, and the generic event handler.

Error Handlers

The error event handlers allow calling code to register callback functions for the three most significant error events; the embed not being found, an error in the client-side code, or an error from the server.

To register callback functions to these events pass an additional events object into the SpecCheckLite constructor with functions as properties notFound, serverError, and/or clientError. Like so:

new SpecCheckLite({
  // ...
  events: {
    notFound: function () {
      console.log("Not found");
    },
    serverError: function () {
      console.log("Server Error");
    },
    clientError: function () {
      console.log("Client Error");
    },
  },
}).create();

If the notFound event handler is called then the embed will not load and the contents of the container element will not be changed. If however the serverError, or clientError event handlers are called then the embed may be left in an unknown state.

Event Handler

To tap into a more detailed stream of events happening within the embed you can instead pass an eventHandler callback function into the SpecCheckLite constructor, like so:

new SpecCheckLite({
  // ...
  eventsHandler: function (e) {
    console.log(JSON.stringify(e, null, 2));
  },
}).create();

This provides a tap into the event bus used to control the state of the embed, each event will have an event name and a copy of the state, for example the initial load may look something like:

{
  "event": "page-load",
  "state": {
    "page": "select-competitors",
    "subject": {
      "manufacturer": "MyBrandHere",
      "model": "ABC 123 X"
    }
  }
}

There are two primary uses for the events from the event handler; checking that the embed has been able to load, and logging analytics for user interaction within the embed.

Identifying first load

As mentioned above, one of the key uses for the event handler is to identify when the embed has been loaded. This can be used to either display your own loading indicators, or to keep the embed hidden in case it cannot be loaded for some reason.

To identify the first load simply wait for the first page-load event to be fired, if the embed cannot be loaded then this event will never be fired, otherwise it will be the first meaningful event (there may be other events fired before).

Here is an example of how this can be implemented:

<script src="https://lite.speccheck.com/js/plugin-ko-p.js"></script>
<script type="text/javascript">
  document.addEventListener("DOMContentLoaded", function () {
    const container = document.getElementById("jsEmbed");

    new SpecCheckLite({
      promise: Promise,
      knockout: ko,
      container,
      // ... embed specific configuration
      eventHandler: function (e) {
        if (e.event == "page-load" && container.classList.contains("hidden")) {
          container.classList.remove("hidden");
        }
      },
    }).create();
  });
</script>
<style>
  .hidden {
    display: none;
  }
</style>
<div id="jsEmbed" class="hidden"></div>

In this example the embed will be loaded into the jsEmbed div element, which is hidden by the hidden css class. Once the embed fires it's first page-load event then the hidden class is removed from the jsEmbed element, showing the loaded embed.

Further Assistance

If you have any questions at all then please contact our support team by emailing [email protected]