Integration with publisher CMS
Mantis documentation
This section details the process of a ‘CMS’ Integration with Mantis.
1. Article brand safety classification
When an article is published (or prior to publishing)
Call the Mantis ‘classifyArticle’ api endpoint for the publisher’s Mantis account (to be provided) e.g.
https://<publisher-mantis-url>/classifyArticle
– POST article data in the call to this URL, as a JSON object in the request body including:
- HTML content (just send the article body content itself, not a whole page with headers/footers/links and teasers for other articles/commercial and other embedded components) – or plain text of the article content.
- Public Page URL (currently live or what the URL will be for unpublished articles)
- CMS id (publisher specific unique article reference id)
- Author(s)
- Title
- Published/last modified timestamps
– Pass publisher authentication credentials (to be provided) using an HTTP Basic authentication header
The article will be processed and Brand Safety ratings will be generated – and returned from the Mantis API in the response body as JSON data.
The publisher could choose to store Brand Safety ratings in their CMS or own database. However, be aware any changes to the ratings models won’t be reflected in this locally stored data unless the publisher implements a process to refresh the stored data.
2. Article brand safety retrieval
When an article page is built in the publisher CMS backend
The results can be made available on page by either:
– Calling the publisher Mantis API endpoint with a GET request passing one of the following in a query parameter
- Publisher’s CMS article id (recommended)
- Public page URL
– Retrieving the locally stored ratings data, if available (note caveats above regarding out of date locally stored ratings data)
When calling the Mantis API endpoint, Brand Safety ratings will be retrieved from the Mantis data store and returned in the response body as JSON data. If the requested article has not yet been processed by Mantis, then the JSON response will indicate that the article ratings are not yet available.
For a backend integration, we would suggest adding a static script tag to the page which includes the ratings retrieved from the Mantis api as a global object on the page:
<script>
window.mantis = {ratings object from Mantis};
</script>
Publishers can, of course, customise to their own requirement and directly include the ratings data in any code delivered from their CMS backend.
If defined as in the above example, the ratings data from the global ‘mantis’ object can also be read in any frontend script integrations (e.g in Ad tags, where we recommend passing in a list of ratings values as a ‘mantis’ key/value pair in page level targeting).
3. Request and response JSON data formats
POST requests
classifyArticle POST requests should send article data in the request body, as a JSON object in the following example:
{
"html": "<title><h1>FA reveal bans for Port Vale's Mitch Clark and Tom Pope</h1></title><h2><p>Mitch Clark and Tom Pope were sent off in the closing stages of Port Vale's 3-2 win at Forest Green</p></h2><p>Port Vale duo Mitch Clark and Tom Pope face three and one game bans respectively.</p><p>The bans have been confirmed on the FA’s website this morning after both were sent off in last night’s 3-2 win at Forest Green Rovers.</p> ... <p><a data-content-type=\"section-topic\" data-link-tracking=\"InArticle|Link\" href=\"https://www.stokesentinel.co.uk/all-about/port-vale-fc\">For all your latest Port Vale news and analysis, click here</a></p>",
"cmsID": "stokesentinel-3838610",
"url": "www.stokesentinel.co.uk/sport/football/port-vale-pope-clark-bans-3838610",
"author": "Michael Baggaley",
"published": "2020-02-01T11:27:15.000Z",
"lastModified": "2020-02-01T11:27:15.000Z",
"title": "FA reveal bans for Port Vale's Mitch Clark and Tom Pope"
}
Request object details
GET requests
classifyArticle GET requests should pass the article URL or CMS id as a query parameters in the request, e.g.
https://<publisher-mantis-url>/classifyArticle?cmsID=stokesentinel-3838610
or
https://<publisher-mantis-url>/classifyArticle?url=www.stokesentinel.co.uk/s port/football/port-vale-pope-clark-bans-3838610
Response Data
Both POST and GET requests will return results in the response body as in the following examples:
Success:
Response object details
Other fields may be present with a more detailed breakdown of the rules that resulted in the brand safety rating – if this has been enabled in the Mantis API platform.
Failure:
The response will include an ‘error’ field in the JSON data, with a description of the error that occurred.
{
error: "Article id not found"
}
4. Ratings description
The Watson ML system and Mantis Brand Safety Engine work together to determine the Brand safety rating for an article, using a set of customisable Brand Safety rulesets.
When an article is analysed a variety of semantic data is extracted from the content and is correlated against thresholds defined in the rulesets.
If any individual element is found to exceed the Brand Safety threshold in the ruleset, then this will automatically trigger a “RED” rating (Content is NOT brand safe).
If none of the extracted data matched in the ruleset, then this automatically triggers a “GREEN” rating (Content IS brand safe).
Finally, if any of the extracted data is matched in the ruleset, but at less than the configured Brand Safety threshold, the article is given an “AMBER” rating (potentially brand unsafe). How this would be used depends on publisher and advertiser preferences. Ideally the ruleset would be tuned for a particular purpose, and use of the Amber rating can be used to balance between very conservative brand safety settings and availability of inventory for campaigns (while still ensuring that all unsafe content can be clearly identified).