@financial-times/o-permutive v1.0.10

o-permutive

Note! this is a Work In Progress Component.

A component for adding the Permutive Data Management Platform to a website.

• Functionality Overview
• Deployment
• Use - Configure and Initialise - Programmatically - Declaratively - Configuration options
• API - oPermutive.init() - oPermutive.IdentifyUser(userIds) - oPermutive.setPageMetaData(dataObject)
• Troubleshooting
• Migration
• Contact
• Licence

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 (e.g. User GUIDs, SpoorIDs). 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.

Deployment

The o-permutive component can be deployed in the same way as all standard Origami components; either via the Build-service or as a Bower dependancy, (an NPM compatible version of the component is being worked on for a furture release). See the Origami tutorials for more details on how Origami components can be deployed or integrated into a build-pipeline.

Use

Configure and Initialise

There are two ways to configure o-permutive.

Programmatically

import oPermutive from "o-permutive"
const config = {
	projectId: "<Project ID>",
	publicApiKey: "<API KEY>",
	consent: true | false,
	consentFtCookie: true | false,
}
oPermutive.init(config)

Declaratively

You must provide a html element with the following attributes:

<div
	id="o-permutive"
	data-o-component="o-permutive"
	data-o-permutive-projectId="<Project ID>"
	data-o-permutive-publicApiKey="<API KEY>"
	data-o-permutive-consent="true"
></div>

o-permutive listens for a o.DOMContentLoaded event, on which it initialises.

If using the origami build service, o-permutive will initialise automatically.

Otherwise, you must trigger the event yourself:

document.addEventListener("DOMContentLoaded", function () {
	document.dispatchEvent(new CustomEvent("o.DOMContentLoaded"))
})

Or you can initialise it by manually calling the oPermutive.init() function with the HTML Element

oPermutive.init(null, "#o-permutive")

OR

const permutiveEl = document.getElementById("#o-permutive")
oPermutive.init(null, permutiveEl)

Configuration options

o-permutive takes the following configuration options. These can be specified either through a config opbject or as data attribues on an element (see above).

API

oPermutive.init()

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

Example:

oPermutive.init(config)

oPermutive.IdentifyUser(userIds)

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.

Example:

oPermutive.identifyUser([
	{
		id: "<userID>",
		tag: "SporeID",
	},
	{
		id: "<userID>",
		tag: "GUID",
	},
])

oPermutive.setPageMetaData(dataObject)

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.

Example:

oPermutive.setPageMetaData({
	page: {
		type: "<STRING>", // e.g. "home" or "article"
		article: {
			id: "<STRING>",
			title: "<STRING>",
			type: "<STRING>", // genre
			organisations: ["<LIST>", "<OF>", "<STRINGS>"],
			people: ["<LIST>", "<OF>", "<STRINGS>"],
			categories: ["<LIST>", "<OF>", "<STRINGS>"],
			authors: ["<LIST>", "<OF>", "<STRINGS>"],
			topics: ["LIST", "OF", "STRINGS"],
			admants: ["LIST", "OF", "STRINGS"],
		},
		user: {
			industry: "<STRING>",
			position: "<STRING>",
			responsibility: "<STRING>",
		},
	},
})

Troubleshooting

TODO

Migration

We use tables to represent our migration guides. Be sure to update it when there is a major release, and update MIGRATION.md, as well

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #advertising-dev or email FT Advertising-dev Support.

Licence

This software is published by the Financial Times under the MIT licence.