@financial-times/n-native-ads v7.0.0

n-native-ads

This is a client side library to get Native Ads from DFP as JSON, you're responsible for rendering and loading the tracking pixel after the ad has been rendered.

Installation

npm install --S @financial-times/n-native-ads

get(oAds, options)

Returns a promise that resolves the ad's data for display in an x-teaser compatible format

• oAds: Initialised oAds instance

Options

• skipSmartmatch Optional : for creating DFP url, the default is false. When Promoted Contents (Smartmatches) don't include as a your page's ads, set this true.
• pageUrl: Current page's url for targeting purpose with smartmatch, needs to be set when smartmatch is on
• pos Optional : defaults to 'native'. Sets the pos targeting parameter for targeting the ad. Added to the scp parameter in the ad request
• allowableFormats Optional : sets the type of ads allowed on your page, the default is [], all ads are allowed. Options can be combined between paid-post special-report smartmatch promoted-content
• useNewPaidPostDesign Optional: defaults to false. Affects only Paid Posts. It replaces the value of promotedPrefixText with Partner Content and also adds ppost-twenty-twenty-design to modifiers.

It is important to note that due to a current limitation with targeting, we can't filter the type of ads on server side. Hence it acts like a frontend filter, rejecting when the ad is not within the allowed formats and returning an empty reponse instead, without attempting another ad call.

Response properties:

Special report only

Paid post / Promoted content only

After getting the response back, you will need to make tracking pixel requests as follows;

[].concat(response.impressionURL).forEach(url => {
	//trigger all the impression tracking pixels
	const trackingPixelImage = document.createElement('IMG');
	trackingPixelImage.src = url;
});

track(adElement, callback(viewState))

Tracks a rendered element and trigger a callback according to google's viewability rules for ads When the element is within the viewport after a certain time

The callback is invoked with a viewState arguemnt:

viewState

NB: Once the ad has been viewed fully, track will stop observing changes and invoking further callbacks, 'partial' callbacks can be invoked multiple times if the ad gets in and out of view quickly

Example of use

Simple example on a page where you would request an ad and append it to the document

const { get, track } = require('@financial-times/n-native-ads');
const { h, render } = require('preact');
const { Teaser, presets } = require('@financial-times/x-teaser');

const pageUrl = `ft.com/stream/${dataTaxonomy}Id/${dataContentId}`;
const skipSmartmatch = true;
allowableFormats = ['paid-post', 'special-report'];


get(window.oAds, {
	pageUrl,
	allowableFormats,
	skipSmartmatch
})
	.then(response => {
		const props = {
			...response,
			...presets.SmallHeavy,
			modifiers: response.type,
		};
		// render a teaser
		const teaserHTML = render(<Teaser { ...props } />);

		// append it to the dom
		document.querySelector("#native-ad-slot")
			.appendChild(teaserHTML);

		// trigger all the impression tracking pixels
		[].concat(response.impressionURL).forEach(url => {
			const trackingPixelImage = document.createElement('IMG');
			trackingPixelImage.src = url;
		});

		// track viewability and send events to spoor
		track(nativeAdHTML, (viewstate) => {
			broadcast('oTracking.event', {
				action: `native-viewed-${viewstate}`,
				category: 'ads',
				native_ad_type: response.type,
			});
		});
	})

Example of use on FT sites

next-front-page

next-stream-page

next-article-page

ft-app