Embedding¶

This documentation aims to provide a guide for embedding Spec Check Lite within a web page.

There are two type of Spec Check Lite embeds - machine levels embeds and top level embeds. Machine embeds are aimed at being placed a on a machine page, whilst top level embeds provide a more general view of the equipment available.

All embeds require the same setup code. The type of embed is determined by the extra configuration passed into the plugin.

<script src="https://lite.speccheck.com/js/plugin-ko-p.js"></script>
<script type="text/javascript">
  document.addEventListener("DOMContentLoaded", function () {
    new SpecCheckLite({
      promise: Promise,
      knockout: ko,
      container: document.getElementById("jsEmbed"),
      // ... embed specific configuration
    }).create();
  });
</script>
<div id="jsEmbed"></div>

All pages must hot link the plugin javascript file. There are three versions of the file available which pre-bundle different libraries:

plugin-ko-p.js - Contains the plugin, the knockout framework required, and a polyfill for Promise.
plugin-ko.js - Contains the plugin, and the knockout framework required.
plugin.js - Contains only the plugin.

Once the plugin file has been included the plugin object needs to be created. Like so:

new SpecCheckLite({
  /* .. Config */
}).create();

Three arguments need to be passed to every plugin:

promise - This needs to be the Promise object or polyfill.
knockout - This needs to be the ko function from the knockout.js framework - at the time of writing version 3.4.2 is bundled.
container - This needs to be an object from the page DOM. The element must exist at the time of calling the construction.

Default Content¶

The element passed to the plugin will have its contents cleared once the plugin has established a connection with the lite-api, as such it can be used to place content that you wish to show whilst the plugin is loading.

Machine Level Embeds¶

Machine level embeds are intended to be placed on a specific machine page. These embeds are focused on a single machine and can be setup to either show a list of competitive machines that a user can select from to compare, or can go straight to a prescribed comparison. Prescribed comparisons have to be setup using the admin interface.

There are three ways of embedding a machine level embed:

Using a Spec Check Variation Id - recommended
Using a Spec Check Legacy Machine Id
Using a Lite Embed Id
Using a PIM Machine Id

Using a Spec Check Variation Id¶

This is the recommended option for most sites

The best way of setting up a machine embed is using a Spec Check Variation Id. This method offers the most flexibility for changing between sites (for example when a new site is released) and with interoperating with the Spec Check APIs.

To do this you'll need to know the siteRef for your site is Spec Check Lite - this can be found via the admin interface by looking at the example code for a machine embed.

You'll also need to know the variationId for each piece of equipment.

These can then be passed into the embed like so:

const specCheck = new SpecCheckLite({
  // ...
  siteRef: "902a8791-93f8-44d7-aa3f-aba4377af8b6",
  variationId: 23456,
}).create();

Using a Spec Check Legacy Machine Id¶

Using a Spec Check Legacy Machine Id method offers flexibility for changing between sites (for example when a new site is released) and with interoperating with the Legacy Spec Check APIs.

To do this you'll need to know the siteRef for your site is Spec Check Lite - this can be found via the admin interface by looking at the example code for a machine embed.

You'll also need to know the machineId and regionId for each piece of equipment - these can also be found in the admin interface when looking at the machine embeds.

These can then be passed into the embed like so:

const specCheck = new SpecCheckLite({
  // ...
  siteRef: "902a8791-93f8-44d7-aa3f-aba4377af8b6",
  machineId: 2345,
  regionId: 1,
}).create();

Using a Embed Id¶

Using an embed id is the simplest way of adding a machine embed, however it's not recommended as the default method as embed ids are tied to a specific site - so can make migrating between websites more difficult in the long-term.

To do this you'll need to find the embedId for the machine you want to embed. This can be found in the admin interface on the Machines page in the Id column.

The embedId can then be passed into the embed like so:

const specCheck = new SpecCheckLite({
  // ...
  embedId: 1234,
}).create();

Using a PIM Machine Id¶

This option is not available for all brands

Where there is an existing relationship between Spec Check and your brands PIM system it may be possible to use identifiers from your PIM system to select the correct machine to compare against.

Within Spec Check PIM identifiers are termed external references, also abbreviated to external refs or ext refs.

To use an external reference the siteRef needs to be passed through to the embed in the same way as with using a Spec Check Machine Id, this is required to

const specCheck = new SpecCheckLite({
  // ...
  siteRef: "902a8791-93f8-44d7-aa3f-aba4377af8b6",
  referenceType: "my-pim",
  reference: "6f3f77c89152",
}).create();

Top Level Embeds¶

Top level embeds will only work if enabled by Spec Check

Top level embeds are more general-purpose than machine embeds and aim to provide a drill down of the available equipment; starting with the ranges, then the brand equipment available, before then showing competitive equipment to select for comparison.

There are two options for loading in a top-level embed; using either an embed id, or a site-ref.

Using a Site Ref¶

This is the recommended option for most sites

A top level embed can be added by simply passing a siteRef.

To do this you'll need to know the siteRef for your site is Spec Check Lite - this can be found via the admin interface by looking at the example code for a machine embed.

The Javascript code for loading in a top level embed using the siteRef is exactly the same as the code for a machine embed, except you omit any reference to the machine:

const specCheck = new SpecCheckLite({
  // ...
  siteRef: "902a8791-93f8-44d7-aa3f-aba4377af8b6",
}).create();

Using an Embed Id¶

Top levels embeds can be loaded in using an embedId. This can be found in the admin interface by looking at the embed(s) shown when the ranges drop down is changed to Top Level Index.

The Javascript code for loading in a top level embed using the embedId is exactly the same as the code for a machine embed using the embedId:

const specCheck = new SpecCheckLite({
  // ...
  embedId: 1234,
}).create();

Further Assistance¶

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