How to Upgrade Siteimprove CMS Plugin to SDK V2

Overview

This guide is for CMS plugin developers - both vendors and community contributors - who want to upgrade their existing Siteimprove integration to the latest SDK (V2.x).

It includes:

• A step-by-step migration path from V1 to V2
• Script versioning and loading instructions
• Code examples for Prepublish, flatDOM, and highlighting
• Links to key developer resources

Why Upgrade to SDK V2.x?

The Siteimprove SDK V1 and legacy plugin UI will be deprecated. SDK V2 is faster, more accurate, and adds support for new features. The V2 UI is fully redesigned, making it easier to understand and more consistent across CMSs.

All plugin maintainers should migrate to ensure long-term compatibility.

Helpful links:

• New UI walkthrough

Script Versioning

The current SDK version is 2.x. Some breaking changes were introduced compared to 1.x:

• domain() – Removed. Site-wide info is no longer available.
• recrawl() – Removed. Full-site crawls are not supported via plugin.

Script Options:

Use overlay-latest.js to stay up-to-date and ensure compatibility with future features

Migration: From SDK V1 to SDK V2

1. Replace the SDK Script

Before (V1):

<script src="https://cdn.siteimprove.net/plugin/plugin.js"></script>

After (V2):

<script src="https://cdn.siteimprove.net/cms/overlay-latest.js"></script>

2. Replace Legacy HTML/ZIP Checks with flatDOM

Older implementations may use:

• contentcheck - accepts a raw HTML string (sometimes referred to as HTML check).
• zipupload - accepts a ZIP archive with HTML, CSS, and JS files (also called ZIP check).

Both are deprecated due to limitations in layout rendering, style awareness, and accessibility accuracy.

Recommended replacement: FlatDOM

contentcheckFlatDom(content, url, token, cmsCallback, contentCheckType);

Why flatDOM and how to use it?

                •             Includes real-time layout and applied styles

                •             Reduces configuration complexity (no zip packaging)

                •             Avoids missing accessibility issues caused by lack of CSS context

The contentcheckFlatDom function pushes a DOM reference to the plugin and triggers the Prepublish checks, allowing you to view and fix issues on a page before it is published.

• The url parameter is optional, but providing it gives better context for the checks.
• The DOM reference must point to the rendered page. This can be the document node of the current page, or a DOM from an <iframe> or new window.

Important requirements:

• The content must be fully rendered before calling this function, otherwise the checks may fail.
• The content must be accessible via JavaScript (same domain, to avoid cross-origin/XSS errors).

The contentCheckType defines the type of content to check. Possible values are:

• "fullPage" - for most use cases, where you want to scan a full page
• “fragment” - for cases where you want to scan a fragment of a page
• "email"- for cases where you want to scan an email

3. Register a prepublish callback

You can also use the SDK function registerPrepublishCallback(callback). It can be used to provide a way for the CMS plugin to ask for the DOM reference to run a prepublish content check on the current page. You can use this function instead of “contentcheckFlatDom”. In this case, instead of pushing a DOM reference, you will register a function to retrieve the DOM node when Siteimprove requests it. 

If you register a callback function for the prepublish, a button will be displayed inside the CMS plugin, on the prepublish tab, for you to start the content check. When you click that button, the CMS plugin will pull the DOM using the function you provided. 

If you want to remove the button, you only need to call that function passing “null” as the callback value. Below you have an entire example of how to inject the CMS plugin script in a page and use registerPrepublishCallback:
 
 <script>

    window.onload = function () {

       loadSmallBox();

    };

    function loadSmallbox() {

      console.log("Loading Siteimprove Content Assistant...");

      const script = document.createElement("script");

      script.src = "https://cdn.siteimprove.net/cms/overlay-latest.js";

      script.onload = function () {

        const si = window._si;

        if (!si) {

          console.log("Content Assistant did not load correctly.");

          return;

        }

si.push(["setSession", "null", “null", “<Name of the cms> <Version>”]);

        si.push(["input", "<pageUrl>"]);

        si.push(["registerPrepublishCallback", onPrepublish]);

        si.push(["onHighlight", onHighlight]);

      };

      document.body.appendChild(script);

    }

    function onPrepublish() {        

      return [

        document,

        () => console.log('FlatOM pull upload finished.'),

        "fullPage"

      ];

    }

    function onHighlight(highlightInfo) {

      const si = window._si;

      if (!si) {

        console.log("Content Assistant did not load correctly.");

        return;

      }

      si.push(["applyDefaultHighlighting", highlightInfo, document]);

    }

</script>

4. Enable and Trigger Prepublish

The Prepublish check is a powerful Siteimprove feature that allows users to scan content before it's published to catch accessibility, SEO, and policy issues early.

Requirements

Before implementing Prepublish in your plugin, ensure:

• The customer's Siteimprove account has the Prepublish feature enabled (usually part of Accessibility Next Gen).
• You have a Siteimprove API key from a user with Admin or Account Owner rights.
• The CMS has access to the DOM content of the page before it's published (e.g., from a preview frame or editor panel).

Steps to set up

Before you can trigger a Prepublish check, you must ensure content checking is active. You can do that:

1- via the API (using a Siteimprove API key from a user with Admin or Account Owner rights):

POST /settings/content_checking

If this call fails, the account either:

• Doesn’t have Prepublish enabled, or
• The API key is incorrect or lacks permissions.

2- or you can call the SDK function “getCapabilities”. The only param needed is the callback that will receive the capabilities object. The call will look like that:

si.push(["getCapabilities", (cap) => { console.log(“These are my capabilities: ”, cap) }]);

5. Token and session

Today, the usage of the token mentioned in section 4 is not needed anymore. Before, we used to call the token endpoint and pass it as a parameter to some of the functions (e.g. “input”, “clear”, “recheck” etc). Today, the only thing needed is to call the “setSession”, before all the other calls. 

Obs: It’s important to note that the “setSession” must ALWAYS be the very first call (like we show in the example code of the section 3), otherwise the other calls won’t work. 

You will need to make this call by passing the first 2 parameters as “null”, and the third one as a string related to the CMS you are using and its version. For example, if you are using Umbraco, in the version 1.0.0, the call will be like that:

si.push(["setSession", "null", “null", “Umbraco 1.0.0”]);

Note the space between the name of the CMS and the version.

6. API Keys

For the SDK V2 no API keys are needed. Before, we used the client API key to check inside some CMSs if content check was enabled for that account. Now, to check for your capabilities, you can use the “getCapabilities” function, like described in section 4.

7. Add In-CMS Highlighting Support

Register a callback function to visually highlight issues inside the CMS editor.

_si.push(['onHighlight', function(highlightInfo) {

  highlightInfo.highlights.forEach(h => {

    const el = document.querySelector(h.selector);

    if (el) el.style.outline = '2px solid red';

  });

}]);

Alternatively, you can also use our highlighting lib, by calling “applyDefaultHighlighting”, like we showed in the example code, on section 3: 

si.push(["onHighlight", function (highlightInfo) {

  const si = window._si;

  if (!si) {

    console.log("Content Assistant did not load correctly.");

    return;

  }

  si.push(["applyDefaultHighlighting", highlightInfo, document]);

}]);

In this case, the callback function will call "applyDefaultHighlighting", from our SDK, passing the received “highlightInfo” and “document”. Then,  "applyDefaultHighlighting" will create a style tag, with the necessary highlighting styles, and will call the “onHighlight” function, from our highlighting lib, passing both “highlightInfo” and “document” again. This is all that is needed to setup the highlighting functionality.

Resources

SDK Spec & Integration Guide

https://developer.siteimprove.com/siteimprove-cms-plugin-markdown.html

Integration Cookbook

https://developer.siteimprove.com/cms-plugin-integration-cookbook.html