Implementation INFOnline Measurement Manager¶
Requirements¶
- TCF 2.x compliant Consent Management Platform (CMP)
- Relay client container (hosted by INFOnline or self-hosted)
- Registered domain service name as CNAME (hosted by INFOnline), AAA(A) (self-hosted) DNS record
- Site ID (provided by INFOnline GmbH)
Important information hybrid app measurement
Before integrating Measurement Manager, please check if these web pages are accessed hybrid. For correct app traffic capture, the integration of the Census SDK in your app must occur simultaneously with the activation of the Measurement Manager. This may result in an overcount of the webview's stored offer identifier (MEW).
If the pseudonymous measurement (webview) is played out directly via the Measurement Manager, it is imperative to implement and initialize the Census Library (IOMb, from version 1.0.1) as well. In case of a different implementation, hybrid requests cannot be captured from the pseudonymous webview.
Furthermore, make sure that your new app version - with integrated Census Library - has a high update rate among your users before activating pseudonymous measurement in the Measurement Manager on your website.
Bootstrapping¶
With preload and bundle loader¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | |
Attention
If you use a CMP that supports automatic blocking of 3rd-party scripts, you must adjust the code line 12 accordingly. Otherwise the census measurement will be blocked by your CMP. This adjustment is currently necessary, for example, when using the ConsentManager CMP. Please check your used CMP accordingly.
<script type='text/javascript' src="//<domain service name>/iomm/latest/bootstrap/loader.js" data-cmp-ab="2" crossorigin></script>
Info
The <domain service name> should be replaced by the AAA(A) or CNAME DNS record of the service platform (relay client).
Without preload and bundle loader¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
Attention
When integrating the INFOnline Measurement Manager without preload it is essential to submit all necessary commands before loading manually the INFOnline Measurement Manager JavaScript bundle. See example above. Any change to the order can lead to an unexpected behaviour.
Attention
Any change of the html attributes of the preload <links> as well as any change of the paths to the bundle or stub will inevitably cause the measurement to fail. Only the <domain service name> should be replaced by the AAA(A) or CNAME DNS entry of the service platform (relay client).
Attention
The publisher must keep in mind that without a bundle loader they must determine the ECMAScript version themselves or they ignore IE11 support and only switch to ECMAScript 6 support.
Configuration¶
To configure the INFOnline Measurement Manager, the publisher must insert a script snippet in the <body> of the HTML content. The snippet itself contains the following statement:
1 2 3 | |
configure command:
| abbreviationname typedefault lengthpattern mandatorydescription
|-----------------|---------------------|---------|---------------|--------|----------------------------------------|-----------|-------------------------------------------------------------------------------------|
| st | site | String | - | 15 | ^[a-zA-Z0-9_]*$ | yes | Site identifier |
| dn | domainServiceName | String | - | - | INFOnline CNAME convention1 | yes | Domain Service Name (CNAME or AAA(A) Host)2 | | Site identifier |
| cn | country | Enum | de | - | no | INFOnline country (de or at) |
| dc | distributionChannel | Enum | web | - | - | no | Distribution channel can be web, hyb, app, ctv |
| dg | debug | Boolean | false | - | no | Debug flag |
1 INFOnline CNAME convention: /^(data-)([a-f0-9]{10})\.([a-zA-Z0-9][a-zA-Z0-9-_]{0,61})(?:\.([a-z]{2,62}))?\.([a-z]{2,62})$/
2 If the notation of dn / domainServiceName does not match the INFOnline CNAME convention, no measurement will take place.
Attention
Before any events (e.g. page impressions) can be measured, the INFOnline Measurement Manager must be configured with the command configure!
Attention
The following applies to parameters:
- Not set and the parameter is optional -> default value is used!
- Not set and the parameter is mandatory -> processing is aborted and a message is logged on the browser console in debug mode!
- Each parameter is queried before processing!
Pageview¶
To measure a pageview (the digital content is viewed by the receiver), the publisher must send the pageview command to the INFOnline Measurement Manager via the global function IOMm(). To send a pageview event to the INFOnline Measurement Manager, the publisher must place a script snippet in the <body> of the HTML content. The snippet itself contains the following statement:
1 2 3 | |
The following parameters can be passed using the pageview command:
| abbreviation | name | type | default | length | pattern | mandatory | description |
|---|---|---|---|---|---|---|---|
| cp | code | String | page_code_non-assignable |
256 | [^a-zA-Z0-9,_/\-?#.] |
no | page code for the IVW Kat 2.0 association |
| co | comment | String | - | 256 | /[ -~]/ |
no | Optional comment |
| pt | pixelType | Enum | cp | - | no | One of cp, sp, xp |
Attention
The contents of the parameters cp and co will be truncated if the maximum length is exceeded. Furthermore, the contents of the cp parameter will be cleaned up and all characters which violate the above pattern will be replaced by a .'.
Advanced settings¶
Script loading variants¶
Asynchronous vs Deferred¶
JavaScript bundles which are loaded by the browser when parsing the HTML content of a website have an critical effect on the critical rendering path of the website content.
Info
JavaScript is considered a "parser blocking resource". This means that the parsing of the HTML document itself is blocked by JavaScript. When the parser reaches a <script> tag, whether that be internal or external, it stops to fetch (if it is external) and run it.
This behaviour can be problematic if we are loading several JavaScript files on a page, as this will interfere with the time to first paint even if the document is not actually dependent on those files.
Fortunately, the <script> element has two attributes, async and defer, that can give us more control over how and when external files are fetched and executed.
Normal execution¶
Before looking into the effect of the two attributes, we must first look at what occurs in their absence. By default, as mentioned above, JavaScript files will interrupt the parsing of the HTML document in order for them to be fetched (if not inline) and executed. Take, for example, this script element located somewhere in the middle of the page:
1 | |
As the document parser goes through the page, this is what occurs:
The HTML parsing is paused for the script to be fetched and executed, thereby extending the amount of time it takes to get to first paint.
The async attribute¶
The async attribute is used to indicate to the browser that the script file can be executed asynchronously. The HTML parser does not need to pause at the point it reaches the script tag to fetch and execute, the execution can happen whenever the script becomes ready after being fetched in parallel with the document parsing.
1 | |
This attribute is only available for externally located script files. When an external script has this attribute, the file can be downloaded while the HTML document is still parsing. Once it has been downloaded, the parsing is paused for the script to be executed.
The defer attribute¶
The defer attribute tells the browser to only execute the script file once the HTML document has been fully parsed.
1 | |
Like an asynchronously loaded script, the file can be downloaded while the HTML document is still parsing. However, even if the file is fully downloaded long before the document is finished parsing, the script is not executed until the parsing is complete.
Possible drawbacks¶
When measuring the performance of digital content presented by a website and consumed by a recipient in a browser, the timing of the measurement is critical for seamless overall performance measurement. However, the way digital content is navigated and consumed differs between recipients. There are users who take their time consuming the digital content. But there are also users who switch between content very quickly. If a seamless overall performance measurement is required, the concurrent loading of JavaScript bundles is critical, because especially in the latter usage variant, the user has already left the content before the measurement is triggered.
Therefore, it is important to weigh up between a fast build/load of the digital content or a measurement that is as seamless as possible. Each publisher must make this decision for themselves. INFOnline's Browser SDK for measuring the performance of digital content provides various options for this purpose.
Version loading¶
General version loading & versioning¶
The modules and in consequence JavaScript bundles which are loaded for each module are by default loaded with the latest version. This means all bundles are loaded with the latests possible version, so that users can automatically benefit from updates, bugfixes and new features.
Since the modules and the INFOnline Measurement Manager (web) itself are published and versioned by using Semantic Versioning, these versions can also be used to load specific versions of modules.
Semantic versioning is a widely-adopted version scheme, that uses a three-part version number MAJOR.MINOR.PATCH. Each new update, feature or bugfix increments the version number. Major versions indicate breaking changes (not backwards compatible). Minor version indicate new functionalities, that are backwards compatible. Patch versions indicate backwards compatible bug fixes. There can be also additional labels for alpha, beta and pre-releases.
Version loading for sensors¶
It is possible to load sensors in a specific version by inserting a meta tag into the head of the website, with details about which sensor to load and which version to use.
Use the following code for this and replace the variables as needed.
<meta name='iomm_config_version_sensor_{sensor}' content='{version}'>
| Variable | Description |
|---|---|
| sensor | Sensor type, e.g. iomb or iomp |
| version | Semantic version, e.g. 1.1.2 or 5.0.0-beta.3 |
Version loading for extensions¶
Extensions are separate bundles which enrich the client side measurement with optional features like audio and video stream event measurement and so on.
It is possible to load extensions in a specific version by inserting a meta tag into the head of the website, with details about which extension to load and which version to use.
Use the following code for this and replace the variables as needed.
<meta name='iomm_config_version_ext_{module}' content='{version}'>
| Variable | Description |
|---|---|
| module | Extension type |
| version | Semantic version, e.g. 1.1.2 or 5.0.0-beta.3 |
Version loading for INFOnline Measurement Manager (web)¶
The INFOnline Measurement Manager (web) can also be loaded with a specific version, but this works differently than for the rest of the modules.
Instead of using meta tags, the version can directly be specified when loading the INFOnline Measurement Manager (web) JavaScript bundle or in the preload.
1 | |
1 | |
latest needs to be replaced with the version that should be loaded, so for example //<domain service name>/iomm/1.6.0/manager/base/es5/bundle.js.
JavaScript version used¶
Per default the INFOnline Measurement Manager automatically checks the compatible JavaScript (ECMAScript) version the browser used is capable of and loads the associated JavaScript bundles with this version.
The INFOnline Measurement Manager differentiates between JavaScript (ECMAScript) version ES5 and version ES6. Most modern browsers support the ES6 syntax, but not all (including Internet Explorer) and so we need check which version to load and load the associated bundles with the compatible version.
Generally speaking loading the more modern ES6 version of the bundles is always preferable, because this version of JavaScript is more powerful, executes faster and the bundles are smaller, so the impact of the IOM Measurement on the website is smaller overall.
The check for the JavaScript (ECMAScript) version works by checking if the browser provides the nomodule property in a script tag, because it is only available in ES6, but not ES5. Due to compatability reasons the old Edge browser (EdgeHTML engine, pre-chromium) is also only allowed to use ES5 (checked by user agent string).
But it is also possible to instruct the INFOnline Measurement Manager to load the ES5 version of the bundles, even though the browser is capable of ES6. This can be helpful for compatability reasons and if the check the INFOnline Measurement Manager conducts is not accurate enough.
To do this place the following meta tag inside of the <head> block of your code.
1 | |
This will always load the ES5 version of the bundles, even if the browser is capable of running the ES6 version.
Info
The JavaScript (ECMAScript) version ES5 was introduced in 2009 and is generally seen as the standard JavaScript version every newer and older browser should be capable of running.
The JavaScript (ECMAScript) version ES6 was released in 2015 and introduced significant changes to the JavaScript (ECMAScript) language. All modern browsers are capable of running this version.
This will make sure no 1st party credentials for modules loaded from the service platform will be exchanged with destinations that are not same origin.
Info
The IOMb sensor will always be loaded with this setting on, so it will never exchange 1st party credentials with non-same-origin destinations whatsoever.