npm package: @financial-times/ads-branded-content
Description: Fetch native ads for FT.com sites and FT app
Latest version: 0.0.1-beta.1
Deprecated: This package is no longer supported

# 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

```sh
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;
```js
[].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

```js
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](https://github.com/Financial-Times/next-front-page/blob/master/client/components/ads/native-ad.js)

[next-stream-page](https://github.com/Financial-Times/next-stream-page/blob/master/client/components/ads/native-ad.js)

[next-article-page](https://github.com/Financial-Times/next-article/blob/master/client/components/ads/native-ad-single.js)

[ft-app](https://github.com/Financial-Times/ft-app/blob/master/lib/javascript/advertising/index.js)