Client Side Tag Integration

Mantis documentation

Product usage workflow Batch integration Integration with publisher CMS Service Mantis Carousel Client Side Tag Integration Display Advertising Specs

Prepared By: Callum Mcadam
Version: 1.2 (Draft)
Last Updated: 26/08/2024
Disclaimer: This is a draft document. While the core process is expected to remain consistent, refinements may be made to enhance the system. Consequently, this document is subject to change as updates are implemented to improve performance and functionality.

1. Overview of the Mantis Client Side Loader

The Mantis Client Side Loader is a bundled JavaScript file designed to provision different
configurations for customers and output the required modules. This service optimises the
inclusion of only the products and services needed, such as Mantis Brand Safety, Contextual,
and Mantis Recommender. Key benefits include:

Efficient Integration: Simplifies the process of integrating multiple Mantis services
with a single script.
Optimised Performance: Ensures only necessary components are loaded, improving
site speed and performance.
Customisable: Easily configured to match the specific needs and look and feel of your
site.
Easy Maintenance: Reduces complexity and makes it easier to manage updates and
changes.

This guide provides step-by-step instructions for setting up the Client Side Loader.

2. Mantis Client Side Loader - Products Suite

The Mantis Client Side Loader is optimised for speed and efficiency, including only the selected products. If you wish to include additional products not currently in your loader, please contact your Mantis account manager. Only the products you choose will be included in your loader.

Mantis Brand Safety and Contextual

Mantis Brand Safety and Contextual uses advanced AI technology to ensure content aligns with brand safety guidelines and provides precise contextual targeting, ensuring your ads are displayed in the most relevant content.

Key Benefits:

Enhanced Brand Safety: Safeguards your brand by preventing association with unsafe content.
Contextual Targeting: Improves ad performance by displaying ads in contextually relevant content.
Granular Insights: Offers detailed data on content categories, emotional tone, and sentiment.
Real-Time Analysis: Continuously monitors and evaluates content.
Customisable Rules: Allows setting specific brand safety rules to meet your needs.

Mantis Content Recommender (Coming Soon)

The Mantis Content Recommender utilises Mantis TAG verified AI technology to showcase relevant and recent content through an on-page widget.

Key Benefits:

Increase Traffic: Keeps users on the site longer, improving page navigation.
Incremental Impressions: Integrates ad units within the widget to boost ad impressions.
Material Impact on Revenue: Significantly increases traffic and revenue potential.
Cookie-Free Operation: Ensures user privacy by operating without requiring personal data.
Customisable: Easily matches the look and feel of your site.

For more detailed information or customised configurations, please contact your Mantis account manager.

3. Basic Integration

3.1. Site Header

Step-by-Step Guide

1. Insert the Script

Place the following script within the <head> section of your article pages.

Note: The script includes the async attribute, which ensures that the script loads asynchronously without blocking the rest of the page. Please be aware that the client tag will not scan home or section pages.

JavaScript

<script async
src="https://loader.mantis-intelligence.com/<publisher-mantis-path>/loader.js"></script>

2. Verify Integration

Ensure the script is loaded correctly.
Confirm that the window.mantis object is present to verify the loader is active.

Note: window.mantis is the default global object used by Mantis. This can be customised if required—please speak to your account manager for more details.

3.2. Google Tag Manager Integration

To deliver the Mantis Loader using Google Tag Manager (GTM), follow these steps:

1. Create a New Tag

Go to your GTM account and create a new tag.
Select "Tag Configuration" and choose "Custom HTML".
Copy and paste the script from the Basic Integration (see 3.1) section into the HTML field.

Note: Ensure that the async attribute is included in the script to allow it to load asynchronously. This helps in optimising the loading performance of your page.

2. Set Up a Trigger

Click on "Triggering" and choose "New".
Name your trigger (e.g., "Mantis Loader Trigger").
Choose "Page View" as the trigger type.
Configure the trigger to fire on article pages only. You can do this by specifying a condition that matches the URL pattern of your article pages (e.g., Page Path contains /article/). Alternatively, you can use any existing mechanism your site already employs to identify article pages.

3. Publish the Container

Save your tag and trigger.
Submit and publish your GTM container to make the changes live.

4. Mantis Client Side Loader - Products Suite

To allow Mantis to effectively crawl your site, it may be necessary to whitelist specific IP addresses and user agents. Additionally, if your site is protected by a paywall, you should either whitelist the same IP addresses or consult with your account manager to discuss potential options or solutions.

UK/EEA Production Environment:

IP Addresses:

○ 34.240.134.77

○ 54.170.2.16

○ 54.217.151.63

UK/EEA Development Environment:

IP Addresses:

○ 34.247.109.254
○ 52.51.234.82
○ 34.246.26.24

AU/APAC Production Environment:

IP Addresses:

○ 54.253.149.197
○ 54.252.110.150
○ 13.239.164.163

AU/APAC Development Environment:

IP Addresses:

○ 3.104.26.13
○ 52.63.215.31
○ 54.253.20.45

User-Agent:

'Mantisbot/1.0 (+http://www.mantis-intelligence.com/)'

Important Notes:

Ensure that the above IP addresses are whitelisted in your firewall or any other security mechanisms to allow Mantis to crawl your site.
If your site has a paywall, you may need to whitelist these IPs or consult with your Mantis account manager to discuss alternative solutions for crawling paywalled content.

5. Environments

The following environments are used for various stages of the deployment and testing process for the Mantis Client Side Loader:

Production: This is the live environment where the Mantis Client Side Loader operates on your site as it is accessed by end-users. It is the final, fully tested version that is used in the real-world application. Ensure that all configurations and integrations are thoroughly tested here before going live.

○ URL: https://loader.mantis-intelligence.com/<publisher-mantis-path>/loader.js

Stable: This environment is used to test the stability and performance of the Mantis Client Side Loader in a pre-production setting. It is intended to ensure that all features function reliably and are ready for deployment to the production environment.

○ URL: https://stable-mantisloader.mantis-dev-awx.com/<publisher-mantis-path>/loader.js

Dev: This environment is used for specific testing and validation scenarios that might involve experimental features or configurations not available in the standard production or development environments. It allows for controlled testing before changes are moved to the stable environment.

○ URL: https://bertha-mantisloader.mantis-dev-awx.com/<publisher-mantis-path>/loader.js

Each environment serves a specific purpose to ensure that the Mantis Client Side Loader is robust, functional, and ready for production deployment. Please select the appropriate environment based on your testing and deployment needs.

6. Mantis Global Object

The global object typically used by Mantis is called window.mantis (although this can be customised if required—speak to your account manager). Below is an overview of what window.mantis contains and what each property does:

Properties of window.mantis

mantis.data: Contains data fetched from the Mantis API, including ratings, emotion,
sentiment, and categories.
mantis.error: Stores error messages encountered during initialisation or data fetching.
mantis.cmd: A command queue that holds functions to be executed once the Mantis
object is ready.
mantis.init: Function to initialise the Mantis script with a configuration object.
mantis.setMantisTargeting: Function to set Mantis targeting parameters for ad
services. The configuration for this function is managed by Mantis.

Example Usage of window.mantis

1. Checking for Errors: You can check if any errors occurred during initialisation by inspecting window.mantis.error.

JavaScript

if (window.mantis.error) {
console.error("Mantis encountered an error:", window.mantis.error);
}

2. Accessing Data: The data fetched from the Mantis API can be accessed via window.mantis.data. Additionally, a JavaScript event, mantis.data.ready, is fired when the data is retrieved.

JavaScript

const mantisData = window.mantis.data;
console.log("Mantis data:", mantisData);

3. Executing Commands: Commands can be pushed to the window.mantis.cmd queue to be executed when the Mantis object is ready.

JavaScript

window.mantis.cmd.push(() => {
console.log("Mantis is ready");
// Add your custom logic here
});

4. Initialising Mantis: Use window.mantis.init to initialise the Mantis script. The script will auto-execute with a client-specific configuration that Mantis controls. Clients can opt to manually control this in specific scenarios . The example below demonstrates a client manual execution.

JavaScript

const config = {
customerId: "exampleCustomer",
enabled: true,
apiTimeout: 1000,
setMantisTargeting: true,
useGranularTargeting: false,
objectName: "mantis",
dataObject: "mantis.data",
cmdObject: "mantis"
};

window.mantis.init(config);

5. Setting Mantis Targeting: Use window.mantis.setMantisTargeting to set Mantis targeting parameters for Google Ad Manager. You do not need to pass any targeting parameters; simply call the function and it will automatically add the relevant targeting to the page.

JavaScript

window.mantis.setMantisTargeting();

There are two options for Mantis Ad Targeting: Granular and Standard. This can be customised by speaking to your Mantis account manager. Granular targeting requires more Key-Value pairs in Google Ad Manager.

6. Using Mantis Data with Google Analytics

JavaScript

For more detailed information or customised configurations, please contact your Mantis account manager.

7. KPV Mantis Standard and Granular Targeting

The setMantisTargeting function is available for use in cases where the publisher opts to manually apply the Mantis values. The setMantisTargeting function processes data from a Mantis API response, transforming it into a format suitable for targeting parameters. It handles ratings, sentiment, and emotion data, supporting both standard and granular targeting options.

How It Works:

Standard Targeting (Default):

Combined String: Includes ratings, sentiment, and emotions combined into a single string.
○ mantis: The combined string for ratings, sentiment, and emotions.
○ Example: mantis=Default-GREEN, Tesco-GREEN,
AgencyMasterBS-RED, sentiment-veryPositive, joy-medium,
sadness-low, disgust-low, anger-low, fear-low

- Ratings: Includes valid ratings in the format "customer-rating". Invalid ratings ('N/A') are skipped. If no valid ratings are found, it defaults to "unknown".

- Sentiment: Processed into the format "sentiment-sentimentValue". If sentiment is undefined or empty, defaults to "sentiment-unknown".

- Emotions: Processed into a comma-separated string in the format "emotion-level". If no emotions are found, it defaults to "emotions-unknown".

- Context Categories: Includes mantis_context and iab_context even if granular targeting is disabled.

Mantis Context: Processes categories with scores above 0.6. If no categories meet this threshold, it defaults to "unknown".
IAB Context: Processes categories with scores above 0.6. If no categories meet this
threshold, it defaults to "unknown".
Example: iab_context:
664,511,150,188,505,552,230,197,676,210,52,90, mantis_context:
travel,transports,sea_travel,sports,fishing,saltwater_fishing,
freshwater_fishing

Granular Targeting:

Separated Data: Data is separated into specific subsets for more detailed targeting.

- Ratings Subsets:

○ mantis_green: Customers with "GREEN" rating.
○ mantis_amber: Customers with "AMBER" rating.
○ mantis_red: Customers with "RED" rating.
○ If no customers match a rating subset, it defaults to "unknown".

- Context Categories:

○ mantis_context: Processes categories with scores above 0.6.
○ iab_context: Processes categories with scores above 0.6.
○ If no categories meet this threshold, each context category defaults to "unknown".

- Sentiment and Emotions: Separates sentiment and emotions into distinct parameters.

○ mantis_sentiment: If undefined or empty, represented as "sentiment-unknown".
○ mantis_emotions: If no emotions are found, represented as "emotions-unknown".

Use Cases:

Standard Targeting:

Ideal for Google Ad Manager KPV or GA events where a single, concise targeting parameter is needed.
Simplifies the data to ensure compatibility with systems that might have limitations in handling multiple parameters.

Granular Targeting:

Suitable for advanced targeting scenarios requiring detailed insights into ratings, sentiment, and emotion.
Provides a richer dataset for precise targeting strategies, offering more control over how each aspect is used in targeting.

By default, standard targeting is applied. For granular targeting, please contact your account manager. The setMantisTargeting function is available for use in cases where the publisher opts to manually apply the Mantis values.

8. Contact Information

General Inquiries
Email: hello@mantissolutions.com
Please use this email for general questions or if you are unsure who to contact. Our team is ready to help redirect your inquiry to the appropriate department.

Mantis Partnerships
Ben Pheloung, Head of Mantis
Email: ben.pheloung@mantissolutions.com
For strategic partnerships and high-level management inquiries.

We value your feedback and are dedicated to ensuring your experience with Mantis meets your expectations. Please do not hesitate to reach out with any concerns or feedback you may have.