caution

You are reading documentation for an outdated version. Here’s the latest one!

Kantar Focal Meter integration

This plugin provides integration with Focal Meter by Kantar. Focal Meter is a box that connects directly to the broadband router and collects viewing information for the devices on your network.

This integration enables measuring the audience of content through the Focal Meter router meter. The plugin has the ability to send the domain user ID to a Kantar Focal Meter endpoint. A request is made when the first event with a new user ID is tracked.

note

The plugin is available since version 3.16 of the tracker.

The Focal Meter integration is automatic once configured.

Install plugin

JavaScript (tag)

Tracker Distribution	Included
sp.js	❌
sp.lite.js	❌

Download:

Download from GitHub Releases (Recommended)	Github Releases (plugins.umd.zip)
Available on jsDelivr	jsDelivr (latest)
Available on unpkg	unpkg (latest)

Browser (npm)

• npm install @snowplow/browser-plugin-focalmeter@focalmeter_plugin@3
• yarn add @snowplow/browser-plugin-focalmeter@focalmeter_plugin@3
• pnpm add @snowplow/browser-plugin-focalmeter@focalmeter_plugin@3

Initialization

JavaScript (tag)

To integrate with the Kantar FocalMeter, use the snippet below after setting up your tracker:

window.snowplow(
    'addPlugin',
    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-focalmeter@3/dist/index.umd.min.js',
    ['snowplowFocalMeter', 'FocalMeterPlugin']
);

window.snowplow('enableFocalMeterIntegration', {
    kantarEndpoint: '{{kantar_url}}',
    useLocalStorage: false // optional, defaults to false
});

Browser (npm)

import { newTracker } from '@snowplow/browser-tracker';
import { FocalMeterPlugin, enableFocalMeterIntegration } from '@snowplow/browser-plugin-focalmeter';

newTracker('sp1', '{{collector_url}}', {
   appId: 'my-app-id',
   plugins: [ FocalMeterPlugin() ],
});

enableFocalMeterIntegration({
  kantarEndpoint: '{{kantar_url}}',
  useLocalStorage: false // optional, defaults to false
});

Enable integration

JavaScript (tag)

The enableFocalMeterIntegration function

The enableFocalMeterIntegration function takes the form:

window.snowplow('enableFocalMeterIntegration', { kantarEndpoint, useLocalStorage? });

Parameter	Type	Default	Description	Required
kantarEndpoint	string	-	URL of the Kantar endpoint to send the requests to (including protocol)	Yes
processUserId	(userId: string) => string	-	Callback to process user ID before sending it in a request. This may be used to apply hashing to the value.	Yes
useLocalStorage	boolean	false	Whether to store information about the last submitted user ID in local storage to prevent sending it again on next load (defaults not to use local storage)	No

Processing the user ID sent in requests to Kantar

By default, the plugin sends the domain user ID as a GET parameter in requests to Kantar without modifying it. In case you want to apply some transformation on the value, such as hashing, you can provide the processUserId callback in the enableFocalMeterIntegration call:

window.snowplow('enableFocalMeterIntegration', {
    kantarEndpoint: "https://kantar.example.com",
    processUserId: (userId) => md5(userId).toString(), // apply the custom hashing here
});

How does it work?

The plugin inspects the domain user ID property in tracked events. Whenever it changes from the previously recorded value, it makes an HTTP GET requested to the kantarEndpoint URL with the ID as a query parameter.

Optionally, the tracker may store the last published domain user ID value in local storage in order to prevent it from making the same request on the next page load. If local storage is not used, the request is made on each page load.

Browser (npm)

The enableFocalMeterIntegration function

The enableFocalMeterIntegration function takes the form:

enableFocalMeterIntegration({ kantarEndpoint, useLocalStorage? });

Parameter	Type	Default	Description	Required
kantarEndpoint	string	-	URL of the Kantar endpoint to send the requests to (including protocol)	Yes
processUserId	(userId: string) => string	-	Callback to process user ID before sending it in a request. This may be used to apply hashing to the value.	Yes
useLocalStorage	boolean	false	Whether to store information about the last submitted user ID in local storage to prevent sending it again on next load (defaults not to use local storage)	No

Processing the user ID sent in requests to Kantar

By default, the plugin sends the domain user ID as a GET parameter in requests to Kantar without modifying it. In case you want to apply some transformation on the value, such as hashing, you can provide the processUserId callback in the enableFocalMeterIntegration call:

import md5 from 'crypto-js/md5';
enableFocalMeterIntegration({
    kantarEndpoint: "https://kantar.example.com",
    processUserId: (userId) => md5(userId).toString(), // apply the custom hashing here
});

How does it work?

The plugin inspects the domain user ID property in tracked events. Whenever it changes from the previously recorded value, it makes an HTTP GET requested to the kantarEndpoint URL with the ID as a query parameter.

Optionally, the tracker may store the last published domain user ID value in local storage in order to prevent it from making the same request on the next page load. If local storage is not used, the request is made on each page load.