@financial-times/o-ads
Advanced tools
This package contains the core functionality used by the FT in providing ads across all of its sites. This includes ft.com, howtospendit.com, ftadviser.com and other specialist titles.
This package contains the core functionality used by the FT in providing ads across all of its sites. This includes ft.com, howtospendit.com, ftadviser.com and other specialist titles.
This doc is specific to the o-ads library. For more information about the ads ecosystem at the FT, visit the Ads wiki
Note: This package is over 5 years old and will soon be deprecated in favour of more modern tools. Please speak to the advertising team (Slack #advertising-dev) if you are thinking of using this.
1. Install 2. Setup & Configuration 3. Define Ad Slots 4. Targeting 5. Lazy Loading 6. Invalid Traffic 7. Styling 8. Events 9. Metrics & Monitoring 10. Misc 11. Developing 12. Migration
Step One. You need to include the o-ads library on your site. There are two ways:
The simple way. All you need to do is include the following in the <head> section of your site.
<href="https://www.ft.com/__origami/service/build/v2/bundles/css?modules=o-ads@^16.0.0" />
<script src="https://www.ft.com/__origami/service/build/v2/bundles/js?modules=o-ads@^16.0.0" async />
Note: At the time of writing, latest version of o-ads is v16.0.0. Check latest available version and replace in the script and link tags
If you're using a build system, you can include o-ads in your code through npm
npm install @financial-times/o-ads --save
And in your file
import oAds from '@financial-times/o-ads'
Step two. You'll need to initialise the o-ads library with some confirguration options in order for it to work. There are 2 ways of doing this:
If you've included o-ads directly on your site using the script provided above, you'll need to initialise it declaratively like so:
<script data-o-ads-config type="application/json">
{
"gpt": {
"network": 5887,
"site": "test.5887.origami"
}
}
</script>
Note: See below for all config options
If you've include o-ads in you code through npm, you will need to initialise it like so:
// your/app/ads.js
import oAds from '@financial-times/o-ads';
oAds.init({
gpt: {
network: 5887,
site: "test.5887.origami"
}
...other config options
});
Note: See below for all config options
These are all the valid configuration options that can be used to set up o-ads:
gpt (required) <Object> - GPT settings
gpt.network (required) <Number>gpt.site (required) <String>gpt.zone (optional) <String>behavioralMeta (deprecated) <Object> - Behavioural data set by the ads-api. DO NOT USEcanonical (deprecated) <String> - Overwrite the GPT page_url parameter DO NOT USEcollapseEmpty (optional) <String> "before" | "after" | "never" - How should the slot be collapsed if there is no ad to be shown
"before" - The ad slot will be collapsed before the ad request until an ad is found."after" - The ad slot will be collapsed if no ad is found after the ad request."never" - The ad slot never collapses, even if no ad is found.dfp_targeting (optional) <String> - Set targeting parameters for google ad managerdisableConsentCookie (optional) <Boolean> - o-ads looks for consent in the FTConsent cookie. Set to false to disable this.flags (deprecated) <Object> - Flags object. DO NOT USEformats (optional) <Object> - Define custom formats for ad slotslazyLoad (optional) <Object|Boolean> - Lazy load ads as they scroll into view
lazyload.viewportMargin (required) <String> - The rootMargin setting of the intersection observer. E.g. "0% 0% 100% 0%"lazyload.threshold (required) <Array> - How much of the ad space should be in view before it's loaded. Number between 0 - 1. E.g. [0.5]passOAdsVersion (optional) <Boolean> - Include the version of o-ads in the ad callsresponsive (optional) <Object> - Overwrite the default breakpoints. See breakpointsrefresh (deprecated) <Boolean> - DO NOT USE. This is an old flag that is not used any more.slots (deprecated) <Object> - Old way of defining slots. See Defining an Ad SlotstargetingApi (optional) <Object> - API to call for targeting information
targetingApi.user (optional) <String> - API endpoint for user related datatargetingApi.page (optional) <String> - API endpoint for page related datatargetingApi.usePageZone (optional) <Boolean> - Overwrite the gpt.zone config setting with a response from the targeting APIvalidateAdsTraffic (optional) <Boolean> - Validate the user is not a bot before making ad calls. This uses the Moat service.Step three. Create some ad slots. Once you've included and configured o-ads onto your website, you'll want to create some placeholders for your ads. These are the HTML elements where the ad will render. These can be defined declarately within a HTML page.
This is the minimum required for an ad slot to be defined. We set some options via html attributes on the slot element. We are naming the ad slot exampleAdSlot and tell it to only return ads of the format MediumRectangle. This will be processed by o-ads and an ad will be rendered inside the <div> if the ad request is successful.
<div
data-o-ads-name="exampleAdSlot"
data-o-ads-formats-default="MediumRectangle"
aria-hidden="true">
</div>
See Ad Formats and Breakpoints
These are all the options that an ad slot can have, declared as attributes on the html element (see example above)
data-o-ads-name="example" - Name of the ad slotdata-o-ads-formats-default="<Format Name>" - The default ad format served at any breakpoint. For full list of format see Ad Formatsdata-o-ads-formats-small="<Format Name>" - The ad format served at the small breakpoint. See Formats and Breakpointsdata-o-ads-formats-medium="<Format Name>" - The ad format served at the medium breakpoint. See Formats and Breakpointsdata-o-ads-formats-large="<Format Name>" - The ad format served at the large breakpoint. See Formats and Breakpointsdata-o-ads-formats-extra="<Format Name>" - The ad format served at the extra large breakpoint. See Formats and Breakpointsdata-o-ads-collapse-empty="before|after|never" - Set how the ad slot will collapse if there is no ad. (See collapseEmpty configuration option)data-o-ads-collapse-empty="before|after|never" - Set how the ad slot will collapse if there is no ad. (See collapseEmpty configuration option)data-o-ads-loaded="<Format Name> - This is set automatically by o-ads to the format of the ad that was loaded in this ad slot. See Formats and Changing behaviour based on ads loadeddata-o-ads-targeting="key=value;key2=value2;" - Ad targeting info specific to the ad slot. See Targetingdata-o-ads-out-of-page="true" - Serve an ad that pops out of its iframe
Formats are predetermiend ad sizes that you can request for your ad. You can specify one format as in the above example, or you can specify multiple formats for different breakpoints. The following example loads a MediumRectangle ad at the small breakpoint, a Leaderboard ad at the medium breakpoint a SuperLeader ad at the large breakpoint and no ad at the extra large breakpoint.
<div
class="o-ads"
data-o-ads-name="example"
data-o-ads-formats-small="MediumRectangle"
data-o-ads-formats-medium="Leaderboard"
data-o-ads-formats-large="SuperLeaderboard"
data-o-ads-formats-extra="false"
aria-hidden="true">
</div>
The default breakpoints provided in o-ads are as follows:
Note: You can change the breakpoint definitions with the responsive config property:
oAds.init({
...
responsive : {
extra : [1400, 0],
someOther: [1200, 0],
large : [1000, 0],
medium : [600, 0],
small : [0, 0]
}
// where each array is in the format [width, height]
...
});
Here are all the available ad formats and their corresponding ad sizes:
| Format Name | Size |
|---|---|
| MediumRectangle (MPU) | 300x250 |
| Rectangle | 180x50 |
| Leaderboard | 728x90 |
| SuperLeaderboard | 970x90 |
| Billboard | 970x250 |
| Responsive | 2x2 |
| WideSkyscraper | 160x600 |
| HalfPage | 300x600 |
| Portrait | 300x1050 |
| AdhesionBanner | 320x50 |
| MicroBar | 88x31 |
| Button2 | 120x60 |
Note: You can ad extra formats with the formats config option when initialising o-ads:
oAds.init({
formats: {
testFormat: {sizes: [[970, 90], [970, 66], [180, 50]]}
}
});
Ads can contain extra information about a user, page, or any other useful info that could be used in Google Ad Manager. There are three ways of adding targeting information to an ad request.
The ads-api is an api that aggregates information from various sources and returns it in a format that o-ads can use and append to every ad call. This can be configured when initialising o-ads like so:
oAds.init({
...
targetingApi: {
user: "https://ads-api.ft.com/v1/user",
page: "https://ads-api.ft.com/v1/content/<content-id>"
},
...
});
When configuring o-ads, you can specificy a string of targeting parameters seperated by a semicolon. These will be added to every ad call.
oAds.init({
...
dfp_targeting: "pos=top;version=1;test=yes"
...
});
You can also specify targeting parameters for any particular ad slot, by using the data-o-ads-targeting attribute when defining the ad slot:
<div
class="o-ads"
data-o-ads-name="example"
data-o-ads-targeting="pos=top;version=1;test=yes"
data-o-ads-formats-default="MediumRectangle"
aria-hidden="true">
</div>
o-ads can be configured to lazy-load ads (i.e. only trigger the ad call when the ad is in view, or close to being in view). It is disabled by default
Lazy Loading uses Intersection Observer under the hood.
oAds.config({
lazyLoad: true
});
// or
oAds.config({
lazyLoad: {
viewportMargin: '0% 0% 100% 0%',
threshold: [0.5]
}
});
viewportMargin - Sets a new margin within the viewport that determines at what point the advert is in view. We suggest setting this option when you want to request and display the advert just before it comes into view. This works as regular margin definitions. Make sure you always specify the dimensions with either px or %, e.g. 100% 0%, or 100px 0px. Default is 0%.
threshold - An array of values that determine at what point a callback will be triggered. In this case, the threshold is a percentage of the intersection area in relation to the area of the target’s bounding box (where the target is a DOM element relative to a containing element or to the top-level viewport). Intersection Observer. Thresholds can be any value between 0.0 and 1.0, inclusive. Default is 0, meaning that as soon as the first pixel comes into view, the advert will be loaded.
There is one exception to lazy loading, which is Master/Companion. Based on the way that this pair of creatives are related in DFP, the companion is loaded soon after the master, which overrides lazy loading.
The library provide the option to check for invalid traffic before serving an ad. This relies on a third party script from Moat which you must include on your page, preferrably in the section on your page
<script async id="moat-ivt" src="https://sejs.moatads.com/financialtimesprebidheader859796398452/yi.js"></script>
This script will append the m_data parameter to the ad call, with a value of 0 or 1. DFP will then use this parameter to decide whether to serve an ad or not.
To enable this feature make sure you have the script above on your page and enable the following config setting when initialising o-ads:
oAds.init({
...
validateAdsTraffic: true,
...
});
o-ads provides some classes to add some basic branded styling to the ad slot.
.o-ads--reserve-90 This is a placeholder for an area of height 90px (with padding) in the slot. This is used to prevent the page jumping when an ad loads (at least when a Leaderboard/SuperLeaderboard height ad is served).
.o-ads--reserve-250 As above - but should only really be used if only a 250px height ad will be used in that slot (as other ads would have empty space around as a result).
.o-ads--background This adds a shaded background in the slot. In principle, this is only really used when an ad is at the top of the page above a header, in order to give some indication that the empty space is intentional.
.o-ads--slate-background This is the same as .o-ads--background except that the background is slate (almost black).
.o-ads--placeholder This displays a backgound image (currently an ellipsis) to give the user a clear indication that something will be loaded in this place.
.o-ads--transition Adds an animation to the container to ease the UX when an ad loads.
.o-ads--center Horizontally centres the ad.
.o-ads--label-left Adds a label above the ad indicating that it is an advertisement. This is required for when the ad sits in between content (e.g. in the middle of an article).
oAds.initialisingTriggered when the library starts the initialisation process. At this point in time, if targetingApi has been defined in the configuration, two separate calls are made to the targeting api in order to get ‘user’ and ‘page’ targeting parameters.
Also at this point, if validateAdsTraffic is set to true, o-ads will check if the traffic validation script (currently moat.js) is available and use it to check if the traffic source is a valid one.
oAds.adsAPICompleteIf targeting has been configured, this event is triggered when both requests to the targeting api (‘user’ and ‘page’) have been fullfilled (whether successfully or not).
oAds.IVTCompleteIf validateAdsTraffic is set to true, this event is triggered as soon as the traffic has been validated or, if the traffic validation script can’t been found, when the associated timeout period expires.
oAds.initialisedTriggered when the library has been initialised and the config has been set. (Note: the GPT library may not have been loaded by this point).
oAds.serverScriptLoadedTriggered when both the GPT library is loaded and oAds.initialised has happened. This marks the completion of the page-level tasks required to enable requests to the ad server.
oAds.adServerLoadErrorTriggered if the library fails to load the external JS GPT library, meaning no advertising will work. Can be used if you wish to have a fallback when you know the adverts will not display.
oAds.slotReadySlot has been inited in the oAds library and is about to be requested from the ad server (deferred if lazy loading is on).
oAds.slotRenderStartTriggered once the ad has been rendered on the page.
oAds.slotExpandIf and when a creative has been returned, this event announces it has now been initialised in oAds, requested from the ad server and displayed. Triggered after oAds.slotRenderStart.
oAds.slotCanRenderLazy loaded advert has been requested.
oAds.refreshA refresh event has been triggered on an advert, prompting a new request to the ad server.
oAds.breakpointIf the oAds is configured to use responsive adverts with set breakpoints, it will trigger the event on each of the breakpoints that was specified in the config. Note that the breakpoint triggering does not take the scrollbar into consideration. For more information read about DFP - Build responsive ads.
oAds.collapseEvent is emitted when the slot is collapsed. The event detail contains oAds slot instance.
As of version 12, o-ads includes some built-in functionality to help monitor the ads loading flow.
Firstly, o-ads saves a performance mark every time it dispatches one of the many events that indicate a milestone in the ads loading process. The Performance API used for this is native browser functionality that provides high resolution time measurements.
oAds.utils.setupMetrics()o-ads is now exposing a new method, oAds.utils.setupMetrics() which enables setting up all ads-related metrics in one step.
setupMetrics(eventDefArray, callback, disableSampling):
eventDefArray (required) <Array>- An array of configuration objects, each of which corresponds to one group of o-ads events. Each config object must have these fields:
spoorAction (required) <String> - A string indicating the name of the group.marks (required) <Array> - An array of strings indicating the name of the o-ads events whose metrics we want to include in the group. Notice that the oAds. preffix must be omitted.triggers (required) <Array> - An array of strings including all the o-ads events that cause the callback to be invoked.multiple (optional) <Boolean> - Can the callback be called multiple times for the group? Default: falsesampleSize (optional) <Number> - Number between 0 and 1 indicating the probability the callback is actually called. If it’s omitted, the callback will be called every time one of the triggering events is dispatched.callback (required) <Function> - A function that will be invoked for each of those groups, possibly multiple times for each. When invoked, the callback will receive an object with information about the timings associated to the events in the group.disableSampling (optional) <Boolean> - A boolean indicating if the sampling specified in the eventDefArray should be ignored. That is, when set to true, no sampling will be applied. Default: falsesetupMetrics() ExampleIt’s easier to understand how to configure o-ads with an example:
const metricsDefinitions = [
{
spoorAction: 'page-initialised',
triggers: ['serverScriptLoaded'],
marks: [
'initialising',
'IVTComplete',
'adsAPIComplete',
'initialised',
'serverScriptLoaded',
'consentBehavioral',
'consentProgrammatic',
]
},
{
spoorAction: 'slot-requested',
triggers: ['slotGoRender'],
marks: [
'slotReady',
'slotCanRender',
'slotGoRender',
],
multiple: true
},
{
sampleSize: 0.1,
spoorAction: 'slot-rendered',
triggers: ['slotRenderEnded'],
marks: [
'slotRenderStart',
'slotExpand',
'slotRenderEnded',
],
multiple: true
}
];
function callback(eventPayload) {
nUIFoundations.broadcast('oTracking.event', eventPayload);
}
oAds.utils.setupMetrics(metricsDefinitions, sendMetrics);
}
In this example there are four different metrics groups. The first one will invoke the callback whenever the trigger (oAds.serverScripLoaded) is dispatched. The callback will receive an object including any available information about several potential time marks (initialising, IVTComplete, adsAPIComplete, initialised, serverScriptLoaded, …). If there is no information about any of those marks, the callback will still be called without it. Since the multiple parameter is missing, its default value of false is assumed which means that, once called, the callback will not be called again for the same page view even if, somehow, oAds.serverScriptLoaded was dispatched again.
slot-rendered and slot-requested config is similar to page-initialised. However, the multiple: true parameter allows the callback to be called as many times as their respective triggering events are dispatched during the same page view. Which, in this case, is the right thing to do since we expect a page to contain, potentially, multiple ad slots.
Finally, the sampleSize: 0.1 parameter on the slot-rendered group randomizes the possibility that the callback is actually called when the oAds.slotRenderEnded event is dispatched, giving it only a 10% chance. This can be used to reduce the number of total “monitoring” events that get fired across the user base.
oAds.utils.clearPerfMarks()Clear entire groups of performance marks created during previous ad loading cycles by some setupMetrics() configuration. This is specially useful in websites that behave like single-page applications and don’t automatically clear the browser’s performance entry buffer very often.
oAds.utils.clearPerfMarks(eventDefArray, groupsToClear)
eventDefArray (required) <Array> - An array of metrics groups expected to have the same structure as defined in setupMetrics().groupsToClear (required) <Array> - An array of metrics groups whose associated performance marks we want to remove.clearPerMarks() Example:const metricsDefinitions = ... // as per the 'setupMetrics' example
// Clear all existing performance marks defined in the 'slot-rendered' and 'slot-rendered' groups
oAds.utils.clearPerfMarks(metricsDefinitions, ['slot-requested', 'slot-rendered']);
With the previously defined metricsDefinitions array, this code will remove all slotReady, slotCanRender, slotGoRender, slotRenderStart, slotExpand and slotRenderEnded existing marks
All ads get an attribute added called data-o-ads-loaded, which contains the format of the ad that loaded. For example, data-o-ads-loaded="Billboard".
A product can use this to change the styles based on which ad has loaded (for example, to increase the height of a reserved slot if a larger ad loads).
obt install.obt demo.npm run demo-serverSee the test documentation
You will need a GITHUB_TOKEN environment variable with access to the repository in your .env file
Get a github token with "repo" access and make it accessible as an environment variable.
Run npm run release (patch|minor|major|x.y.z) in master then follow the interactive steps.
This will bump version numbers in the source and commit them, push to github and create a new release.
The command uses release-it under the hood as well as genversion to automatically bump version numbers in the source.
See the migration guide
FAQs
This package contains the core functionality used by the FT in providing ads across all of its sites. This includes ft.com, howtospendit.com, ftadviser.com and other specialist titles.
The npm package @financial-times/o-ads receives a total of 38 weekly downloads. As such, @financial-times/o-ads popularity was classified as not popular.
We found that @financial-times/o-ads demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 18 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.