This package provides functionality to display ads and track user behaviour for ft.com.
npm install @financial-times/ads-displayThis package provides functionality to display ads and track user behaviour for ft.com.
This package is available on npm.
``sh`
npm install --save @financial-times/ads-display
If you need to get some metadata about the page or user, you can use getAdsData().
`js`
import { getAdsData } from '@financial-times/ads-display'
getAdsData({
user: true, // fetch data about current user
page: { // fetch data about current article or stream page
type: 'article' // 'article' or 'stream'
id: 'id-of-the-page' // id of the stream or article page. Usually found in appContext
}
}).then(adsData => {
// Do stuff with the data.
})
Developer note: You can also override the host and version of the ads-api endpoints which this function fetches from by providing a host property. This is useful if you want to test locally.
`js`
getAdsData({
...,
host: 'http://local.ft.com:3002/v2'
})
The default host is https://ads-api.ft.com/v2
See Client-side API section for more details
Both client and server side components for displaying ads on a page.
You can define ad slots and pass data to the client for initialising the ads library
`jsx
import ReactDOM from 'react-dom/server'
import { Slot, AdsOptionsEmbed } from '@financial-times/ads-display'
app.use(appContextMiddleware)
app.get('/my-page-with-ads', (req, res, next) => {
const adOptions = {
appName: res.locals.appContext.appName,
adUnit: ['ft.com', articles/${req.articleId}],
// page level targeting, added to every ad request on the page
targeting: {
user: {},
article: {}, //or
stream: {}
},
...
}
const slotProps = {
name: 'leaderboard',
formatSmall: false,
formatsLarge: 'SuperLeaderboard,Leaderboard,Responsive',
formatsExtra: 'Billboard,SuperLeaderboard,Leaderboard,Responsive',
// slot level targeting, added only for this ad slot
targeting: {
specialAdTargeting: true,
pos: 'top'
}
}
const adHTML = ReactDOM.renderToStaticMarkup(
)
res.render(adHTML)
})
`
If you haven't defined your ad slots on the server, you will first need to define one or more ad slots on the page. You can learn more about this here
Once you have your ad slots defined in your HTML, you will need to initialise the ads library.
This is the minimum you need to get some ads.
`jsx
import { displayAds } from '@financial-times/ads-display'
import * as flags from '@financial-times/anvil-ui-ft-flags'
const flagsClient = flags.init()
const options = {
appName: 'my-app'
}
displayAds.init(options, flagsClient);
`
On ft.com, we will want to pass in a page rootID to each ad call. ads-display exports some utility functions, amongst which a method getRootId() which can be called when initialising the ads.
`jsx
import { displayAds, adsUtils } from '@financial-times/ads-display'
import * as flags from '@financial-times/anvil-ui-ft-flags'
const flagsClient = flags.init()
// For a pageKit app, we can get information from appContext
const { appName, abTestState } = appContext
const options = {
appName,
abTestState,
rootId: adsUtils.getRootID()
}
// On ft.com we only show ads if the flag is enabled
if(flags.get('ads')) {
displayAds.init(options, flagsClient);
}
`
In most use cases on ft.com and the FT app, we will want to get some data about the user and the page and append this to our ad requests to provide more targeted ads.
`js
import { getAdsData, displayAds } from '@financial-times/ads-display'
import * as flags from '@financial-times/anvil-ui-ft-flags'
const flagsClient = flags.init()
const { appName, contentId, abTestState } = appContext
if(flags.get('ads')) {
getAdsData({
user: true,
page: {
type: 'article',
id: contentId
}
}).then(adsData => {
const options = {
appName,
abTestState
targeting: adsData.metadata, // for all pages on ft.com
adUnit: adsData.adUnit, // for article or stream pages
};
displayAds.init(options, flagsClient);
});
}
`
Here is an example of using ads-display on the ft.com article page. This ties in all parts of ads-display, by first fetching some data, then enabling both the display ads and the behaviour tracking with permutive
`js
import {
getAdsData,
adsUtils,
displayAds,
adsPermutive
} from '@financial-times/ads-display'
import * as flags from '@financial-times/anvil-ui-ft-flags'
// Assume pagekit app where appContext is defined.
const flagsClient = flags.init()
if(flags.get('ads')) {
getAdsData({
user: true,
page: {
type: 'article', // or 'stream'
id: appContext.get('contentId')
}
}).then(adsData => {
// initialise ads
displayAds.init({
appName: appContext.get('appName'),
abTestState: appContext.get('abTestState'),
rootId: getRootId(),
targeting: adsData.metadata,
adUnit: adsData.adUnit,
}, flagsClient);
if (flags.get('AdsPermutive')) {
// Initialise permutive
adsPermutive.setup();
adsPermutive.loadPermutiveScript();
// Identify the user
adsPermutive.identifyUser({
uuid: adsData.metadata.user.uuid,
spoorId: adsData.metadata.user.spoorId
})
// Send a page view event
const pageView = adsPermutive.fromAdsDataToPageView({
...adsData.metadata,
rootId: getRootID(),
type: appContext.get('appName')
});
adsPermutive.trackPageView(pageView);
}
});
}
`
These are all the options you can pass to displayAds.init() server side via AdsOptionsEmbed
- appName (required) - Name of the appadUnit
- : (optional) - An array to use for the GPT ad unit. Each item in the array will be concatenated with a /. E.g. options.adUnit = ['ft.com', 'UK'] becomes ft.com/UK. If not provided, will default to unclassified.adsLayout
- : Used for setting the nLayout value in the ad call, useful for ad ops for targeting purposes, to test different types of ads formats and for setting up demosabTestState
- (optional) - The state of all the mvt tests running on the page. Usually found in appContext for pageKit apps.rootId
- (optional) - The root id of an ft.com page. You can get this using the getRootId() function.targeting
- (optional)
Permutive is a behaviour tracking tool that is used to segment people based on their activity on the site. See adsPermutive for more details. It is proxied here by ads-display for convenience. Here's an example:
`javascript
import { adsPermutive } from '@financial-times/ads-display';
adsPermutive.setup();
adsPermutive.loadPermutiveScript();
adsPermutive.identifyUser({
guid: '1234',
spoorId: '12345'
});
adsPermutive.trackPageView({
page: {
type: 'article',
rootId: '1234'
}
});
`
For ft.com, there is a helper function that calls all the functions, with some data about the page and user (usually fetched from getAdsData()), type and rootId.
`javascriptgetAdsData()
import { adsUtils } from '@financial-times/ads-display';
adsUtils.enablePermutiveFtCom({
metadata: { user: {...}, page: {...} }, // data from
type: 'article',
rootId: adsUtils.getRootID()
})
$3
This function initalises o-ads, loads the required third party scripts, and scans the page for ad slots to initialise
$3
Returns the root id of the current ft.com page
$3
A helper function to run all the necessary functions for loading and sending data to permutive on ft.com pages.
{#data-manager}import { getAdsData } from '@financial-times/ads-displayor to minimize bunle size (depending on your build config), you can import directly:
ES Module:
CommonJS: Returns a data object in the following format:
js
{
metadata: {
user: {
// key -> value user props
},
article: {
// key -> value article page props
}
stream: {
// key -> value stream page props
}
},
adUnit: [] // ad unit for stream or article pages,
}
`Format the user data as key => value pairs for use in ad requests. The keys are mapped from the ads-api /v2/user response to the equivalent keys that the ad ops server expects in the ad calls.
$3
or to minimize bunle size (depending on your build config), you can import directly:
ES Module:
CommonJS: $3
js
getAdsData({ user: true }).then(adsData => {
const keyValuePairs = formatUserData(adsData.metadata.user);
...
})`Format the article data as key => value pairs for use in ad requests. The keys are mapped from the ads-api /v2/user response to the equivalent keys that the ad ops server expects in the ad calls.
$3
or to minimize bunle size (depending on your build config), you can import directly:
ES Module:
CommonJS: $3
js
getAdsData({
page: {
type: 'article',
id: appContext.get('contentId')
}
}).then(adsData => {
const keyValuePairs = formatArticleData(adsData.metadata.article);
...
})`Exposes all the public functions from adsPermutive
Server-side API
is a JSX component that renders a script with the passed options embedded in a json blob, they are then retrieved automatically client side by ads-display$3
- options ads-display options
Slot is a JSX component that renders an Ad slot compatible with o-ads$3
-
name : Ad slot name
- formats : Available formats to use
- targeting