Siteimprove CMS Plugin Markdown

# General
 
Token endpoint: https://my2.siteimprove.com/auth/token?cms=nameOfCMS
* Authentication is not needed to reach this endpoint.
* Returns a json payload with one key `token`.
* The token should be persisted in the CMS.
* The url paramater "cms" is the name and version of the CMS, e.g. Drupal 8.
 
Script: https://cdn.siteimprove.net/cms/overlay.js
 
# Script
 
The script's functionality is available globally under the name `_si`. 
* It has 5 core functions
 * `input(url, token, callback)` takes two parameters and an optional callback which will be called when data has been succesfully fetched. It should only be used when in a page specific context in the CMS. The url grabbed from the integration and the token grabbed from the token endpoint. This will request our system to get data for the specific url. In case the Siteimprove Plugin should be shown but we cannot find an url or other scenarios where it makes sense to have it shown but no url, an empty url can be given to input and it will show the Siteimprove Plugin but without any data.
 * `domain(url, token, callback)` takes two parameters - the url of the domain, the token grabbed from the token endpoint and an optional callback. This should be used when in a context of a site or no site at all. The url should be the indexurl of the site if the integration is able to find a specific site. Otherwise it should send an empty url and little box will be shown and it can be opened to view all sites currently in Siteimprove.
 * `clear(callback)` takes an optional callback. In case the Siteimprove Plugin should be shown but we cannot find an url or other scenarios where it makes sense to have it shown, this function can be called and it will show the Siteimprove Plugin but without any data.
 * `recheck(url, token, callback)` takes two parameters - the url to recheck, the token grabbed from the token endpoint and an optional callback which will be called when a recheck has been succesfully ordered. This will request a recheck of the url in our system. This is meant to be the publish hook.
 * `recrawl(url, token, callback)` takes two parameters - the url of the page currently viewed (it can also be the domain of the site currently viewed - we will strip it down to the domain either way), the token grabbed from the endpoint and an optional callback which will be called when a recrawl of the site has been succesfully ordered. This will request a recrawl of the entire site in our system. This is meant to be the publish hook for a batch of _many_ pages, e.g. an entire site.
* It has 1 utility function
 * `showlog()` with no parameters. This will show an internal log for the script. This way it is possible to see what is going on inside the script.
 
## Using the functions
In order to handle the script being loaded asynchronously, the script functionality is used in a different way than just a function call in the variable. But it means a little bit extra work when calling function in `_ si`
* Input function
```javascript
var _si = window._si || [];
_si.push(['input', 'url', 'token', function() { console.log('Inputted page specific url to Siteimprove'); }])
```
* Domain function
```javascript
var _si = window._si || [];
_si.push(['domain', 'url', 'token', function() { console.log('Inputted domain to Siteimprove'); }])
```
* Recheck function
```javascript
var _si = window._si || [];
_si.push(['recheck', 'url','token', function() { console.log('Recheck ordered'); }])
```
* Clear function
```javascript
var _si = window._si || [];
_si.push(['clear', function() { console.log('Cleared'); }])
```
* Recrawl function
```javascript
var _si = window._si || [];
_si.push(['recrawl', 'url','token', function() { console.log('Recrawl ordered'); }])
```
This means that the CMS App / integration can input an url, and even order a recheck, before the script is actually loaded.
It can be an advantage to have an easy way to access the log of the script. This can be done by creating a bookmark with the following.
 `javascript:if(window._si !== undefined){window._si.push(['showlog','']);}`
 
# Server-side recheck or recrawl
If it's not possible to use the javascript for rechecks and recrawls due to some CMS limitations then it's possible to use another endpoint. It should be done by a HTTP POST to this endpoint: https://api-gateway.siteimprove.com/cms-recheck
The endpoint will receive a json payload describing the url, token and type of check.
## Recheck page
```json
{
 "url": "url",
 "token": "token",
 "type": "recheck"
}
```
## Recrawl site
```json
{
 "url": "url",
 "token": "token",
 "type": "recrawl"
}
```