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

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:

| 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