@financial-times/n-native-ads

Fetch native ads for FT.com sites and app

Stats

StarsIssuesVersionUpdatedCreatedSize
@financial-times/n-native-ads
7.0.0a year ago4 years agoMinified + gzip package size for @financial-times/n-native-ads in KB

Readme

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:

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/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

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.