@financial-times/ads-display 

This package provides functionality to display ads and track user behaviour for ft.com.

Table of Contents

1. Install

2. Ads Data

3. Display Ads

4. Permutive

5. Client Side API

6. Server Side API

7. Monitoring

8. Third Party Scripts

9. Develop

10. Releasing

Install

This package is available on npm.

``sh
npm install --save @financial-times/ads-display
`

Ads Data

If you need to get some metadata about the page or user, you can use getAdsData().

How to use

`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

Display Ads

Both client and server side components for displaying ads on a page.

$3

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)
})
`

Client side

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.

$3

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);
`

$3

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);
}
`

$3

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);
});
}
`

$3

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);
}
});
}
`

Options

These are all the options you can pass to displayAds.init() server side via AdsOptionsEmbed

- appName (required) - Name of the app
- adUnit: (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 demos
- abTestState (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)