ads-permutive

A library to easily integrate Permutive functionality with FT-owned webpages.

Functionality Overview

This component will integrate Permutive's Data Management Platform functionality onto a website. Specifically the component will do the following:

• Runs the Permutive 'bootstrap' code, this code has been provided by Permutive and is intended to be run before any other Permutive code. A global variable, 'permutive' is added to the window object and a 'command-queue' array is defined under the window.permutive global object which holds functions which will be called when the Permutive main script is attached and ready. The bootstrap code also sets-up the Permutive-DFP integration (GPT).
• Checks for user-consent for behavioural profiling - no Permutive code (including the above mentioned bootstrap code) will be run if a user has not consented to behavioural profiling.
• Attaches the main Permutive JS file to the page DOM.
• Calls Permutive's api function to link Permutive's unique id assigned to a user/device with first-party ID's the user's GUID is used. This is configurable.
• Calls Permutives api function for passing meta-data associated with a page visit.
• Note; Permutive's code integrates with Google DFP for passing user segments into ad-server requests.

Resources

Permutive Event Schemas

FT.com specific documentation from Permutive

Getting started

This package is available on npm.

npm install --save @financial-times/ads-permutive

Notes

We're currently investigating the possibility to setup Permutive via GTM across FT.com. ads-permutive would still expose the setup() method for certain use cases.

Use

Configure and Initialise

import adsPermutive from '@financial-times/ads-permutive'
adsPermutive.identifyUser({ uuid })

API

adsPermutive.setup(configOptions)

Configure and initialise the permutive instance (see above for details).

Example:

adsPermutive.setup()

setup() takes an argument configOptions, where the only supported option is currently eventsCacheLimitBytes.

Example: limit the events cache to 12 kB.

adsPermutive.setup({
	eventsCacheLimitBytes: 12e3
}

See Limiting the events cache storage

adsPermutive.loadPermutiveScript()

It loads the Permutive script. This needs to be executed by any app that needs to be load the Permutive script programmatically. It can be run after setup has been executed.

Example:

adsPermutive.setup()
adsPermutive.loadPermutiveScript()

adsPermutive.identifyUser(userIdentity)

Use if you wish to make use of Permutive's User Identity Matching features whereby Permutive's unique user ID can be mapped to first-party User IDs. This would be needed for cross-device User matching for example. See UserIdentityV2 in adsapiv2_schema.

| Name | Data-structure | Required?| Notes | |-------------------|----------------------------|---------:|-------| | uuid | Object | yes, see notes | Required if cross device user matching is required |

Example:

adsPermutive.identifyUser({
	uuid,
})

adsPermutive.trackPageView(targeting, appName)

Send metadata about the current request to permutive. All data-points are optional; however the schema is fixed, meaning that any data passed that is not in the format specified below will be rejected.

Any data-point below may be omitted if it is not available or not relevant for the page request. See Schemas.

Example:

adsPermutive.trackPageView(targeting, options)

Example: transform data from n-ads Data Manager format. See n-ads Data Manager schema here

import { fetchAdsData } from '@financial-times/n-ads'

const adsData = await fetchAdsData({ user = true, page = true })

if (adsData && adsData.metadata) {
	adsPermutive.identifyUser(adsData.metadata.user)
}

where targeting accepts targeting data in the Permutive's PageView schema specified here. and options accepts the following optional parameters.

• mappingFunc, a function used to map the input targeting metadata to data matching the PageView's schema.

Alternatively the data can be formatted into a PageView event by using one of the exposed formatters: fromAdsApiV1ToPageView(), fromAdsApiV2ToPageView(), fromAdsDataToPageView(),

Using a formatter

Example: transform data from n-ads Data Manager format. See n-ads Data Manager schema here

import { fetchAdsData } from '@financial-times/n-ads'

const adsData = await fetchData({ user = true, page = true })
if (adsData && adsData.metadata) {
	const pageViewData = adsPermutive.fromAdsDataToPageView({
		...adsData.metadata,
		rootId: getRootID(),
		type: appContext.get('appName')
	})

	adsPermutive.trackPageView(pageViewData)
}

Example: transform data from Ads API V1 format. See Ads API V1 schema here

const pageView = adsPermutive.fromAdsApiV1ToPageView(adsApiV1Data)
adsPermutive.trackPageView(pageView)

Example: transform data from Ads API V2 format. See Ads API V2 schema here

const pageView = adsPermutive.fromAdsApiV2ToPageView(adsApiV2Data)
adsPermutive.trackPageView(pageView)

Using mapping functions

The mapping functions can be used as follows.

Example: transform data from custom format

adsPermutive.trackPageView(targeting, {
	mappingFunc: myMappingFunction
})

adsPermutive.trackEvent(eventName, trackingInfo)

Track an event in Permutive.

Example:

adsPermutive.trackEvent(eventName, trackingInfo)

Example: Tracking VideoEngagement

Send metadata about the video play progress to permutive. All data-points are optional; however the schema is fixed, meaning that any data passed that is not in the format specified below will be rejected. Any data-point below may be omitted if it is not available or not relevant for the page request.

where videoTracking currently accepts the following VideoEngagement schema.

| Name | Data-structure | Required?| Notes | |-------------------|----------------------------|---------:|-------| | campaign | String | no | ad campaign | | createdAt | String | no | created time | | duration | Integer | no | video duration in seconds | | title | String | no | video title | | videoId | String | no | video id | | progress | Float | no | video progress |

and client data points are added automatically by the Permutive SDK.

Example: tracking the VideoEngagement event

adsPermutive.trackEvent('VideoEngagement', {
	campaign: 'FT Rethink',
	createdAt: '2019-05-22T11:00:00+00:00',
	duration: 200,
	title: 'DYSFUNCTIONAL: exploring sustainability through design',
	videoId: 'WBtgMM3qLhg',
	progress: 0.5,
})

Schemas

PageView

The PageView events sent by ads-permutive to Permutive are conformant to the schema defined in Permutive Event Schemas - see the Events section on the Permutive Dashboard. ads-permutive stores locally the PageView schema.

Every time trackPageView(eventData, options) is called, ads-permutive checks the input eventData against the PageView schema stored locally and filters the data that conforms to the schema.

ads-permutive offers utilities to convert data from n-ads Data Manager, Ads API V1 User and Content or Ads API V2 User and Content into PageView events. See Using a formatter.

Limiting the events cache storage

Please be aware that limiting the size will decrease the lookback window on the data we can use for segmentation, i.e. how much historical data is available to determine the result for new segments.

How the events storage size gets used is by writing all events into the available space. As soon as this cache is filled it will push out the oldest events to replace with new events.

This will happen exactly the same in any deployments. The default eventsCacheLimitBytes is 2.5MB, therefore by reducing the eventsCacheLimitBytes to 1MB, the amount of available lookback window will be 3/5 smaller.

On average we store on average about 1000 events per 1 MB (1kB per event)

Example On average FT users over March 2020 saw this behavior:

Assumptions:

• An average event is about 1.2KB
• There are around 11 events per Pageview

So with limiting the localStorage to 1MB, we will be limiting the history to about 1000 events, or 90 pageviews. Given your last March 2020 history, on average a user has viewed 20 pageviews in a month.

So on average, your effective lookback will be 90/20 = 4.5 months.

Looking into this some more, we can see that the average is skewed by some highly engaged users so the lookback window on average should be even greater.

Given this, it shouldn't have a strong effect lowering the Permutive events cache limit.