@financial-times/ads-permutive

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.

$3

[Permutive Event Schemas][permutive_events]

FT.com specific documentation from Permutive

$3

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

$3

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

API

$3

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

Example:
`javascript
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

$3

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:
`javascript
adsPermutive.setup()
adsPermutive.loadPermutiveScript()
`

$3

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:
`javascript
adsPermutive.identifyUser({
uuid,
})
`

$3

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:
`javascript
adsPermutive.trackPageView(targeting, options)
`

Example: transform data from n-ads Data Manager format. See n-ads Data Manager schema [here][n-adsdatamanager_schema]
`javascript
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][pageview_schema].
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][n-adsdatamanager_schema]
`javascript
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][adsapiv1_schema]
`javascript
const pageView = adsPermutive.fromAdsApiV1ToPageView(adsApiV1Data)
adsPermutive.trackPageView(pageView)
`

Example: transform data from Ads API V2 format. See Ads API V2 schema [here][adsapiv2_schema]
`javascript
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
`javascript
adsPermutive.trackPageView(targeting, {
mappingFunc: myMappingFunction
})
`

$3

Track an event in Permutive.

Example:
`javascript
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
`javascript
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

$3


The PageView events sent by _ads-permutive_ to _Permutive_ are conformant to the schema defined in [Permutive Event Schemas][permutive_events] - see the Events section on the Permutive Dashboard.
_ads-permutive_ stores locally the [PageView][pageview_schema] 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][n-adsdatamanager_schema], [Ads API V1 User and Content][adsapiv1_schema] or [Ads API V2 User and Content][adsapiv2_schema] into [PageView][pageview_schema] events. See Using a formatter.

[permutive_events]: https://dash.permutive.com/events/
[pageview_schema]: src/schemas/PageView.js
[adsapiv1_schema]: src/schemas/AdsAPIV1.js
[adsapiv2_schema]: src/schemas/AdsAPIV2.js
[n-adsdatamanager_schema]: src/schemas/AdsDataManager.js

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.