@financial-times/ads-partner-content

ads-branded-content

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/ads-branded-content

init(options)

This is the preferred way to initialise one or more ad slots on the page. This is also the only way to lazyload ad slots. Call init(options) with the following options:

Options

• oAds [ Required ]: Initialised oAds instance
• adSlots [ Required ]: An array representing the ad slots on the page. Each array item should be an object with the following signature:

{
  el: document.querySelector('.native-ad-container'),	// The dom element where the native ad will be rendered 
  cb: (response, el) => {} ,	// A function to be executed once the native ad JSON has loaded. The function takes the formatted JSON response for the native ad and the element where it is to be rendered. This is where you would typically render the ad.
  options: {...}	// Options to be passed to the `get()` function. See below for details.
}

• lazyload [ Optional ]: Should the ads be lazyloaded. Possible values include: true, false or an object specifying the viewport widths (keys) at which to apply the margins (values). Defaults to false

{
  760: '15%',	// At viewport widths lower than 760px, load the ads 15% (of the viewport height) sooner than usual.
  980: '5%'	// At viewport widths between 760px and 980, load the ads 5% (of the viewport height) sooner than usual.
}

get(oAds, options)

Returns a promise that resolves the ad's data for display in an x-teaser compatible format. Only use this when you need more granular control over displaying a single native ad.

• 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:

Attribute	Description	Type
type	Type of native ad, possible values: paid-post promoted content special-report	string
id	Ad creative's ID	Integer
impressionURL	List of impression urls that will need to be dropped into the page to confirm to ad network that the native ad was loaded	array
lineItemId	An ID representing a targeting grouping	integer
url	Url for where the ad should link to	string
title	Main title for the native Ad	string
standfirst	Subheading for native ad content	string
advertiser	Name of the advertiser	String
image	contains a url property, with the image's source	object { url: String }
modifiers	contains a list of descriptors that can be useful as classNames to style the ad	string[]

Special report only

Attribute	Description	Type
metaPrefixText	"Special Report" text used to identify a special report	String
firstPublishedDate	Date when the content was first published	Date
publishedDate	when content was most recently published	Date

Paid post / Promoted content only

Attribute	Description	Type
promotedPrefixText	Text containing the name of the native ad type either "Promoted Content" or "Paid Post"	string
promotedSuffixText	suffix text for promoted-content and paid-posts above the headline. typically "by {advertisername}".	String

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

Argument	Description	Type
'full'	100% of the ad's content is visible on the viewport for at least 1sec	string
'partial'	50% of the ad's content is visible on the viewport for at least 1sec	String

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/ads-branded-content');
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

Demos

To run the demos, simply open any file in the demos/ folder in the latest version of Chrome. Simples.