Nitro Ads
Installing
Please refer to the setup guide for details on how to include the ad script on your site.
Creating Ad Placements
Call window.nitroAds.createAd to create an ad placement.
First Party Data
You can optionally supply first party user data for improved ad match rates.
Call window.nitroAds.addUserToken before createAd to pass user data.
Script global settings
Global settings may be controlled via the <script> tag's data attributes.
Demo
The when the data-demo attribute is set to true, all placements will load placeholder graphics instead of ads. This setting should only be used for testing.
Log level
You can override the default log level of info to show more or less information in the console using the data-log-level attribute. This setting only affects the NitroPay ads script, and not any output from other scripts.
Log levels are:
- silent
- error
- warn
- info
- debug
The debug level should not be used in production.
Events
Custom events are emitted on Document with detailed information related to ad serving.
nitroAds.loaded
Emits events.LoadedEvent when the ad script finishes loading.
nitroAds.createAd
Emits events.CreateAdEvent when createAd is called, after parsing options.
nitroAds.prepare
Emits events.PrepareEvent when an element is being prepared for ad targeting.
nitroAds.bidReceived
Emits events.BidReceivedEvent for each bid received.
nitroAds.rendered
Emits events.RenderedEvent when an ad is rendered. id and requestId match the lifecycle events below, and late is true when the ad rendered after its request already reported a non-filled result (e.g. timeout).
Prefer nitroAds.adResult for application logic: rendered does not fire when a request fails or is blocked.
nitroAds.adRequested
Emits events.AdRequestedEvent when a placement starts an ad request, including refreshes. Every adRequested is followed by exactly one nitroAds.adResult with the same requestId.
nitroAds.adDeferred
Emits events.AdDeferredEvent when a request is waiting, for example because the placement is hidden, the tab is in the background, the placement is waiting to scroll into view, or the ad server only starts ads once the placement is at least 50% in view. The result timer is paused while deferred.
nitroAds.adResult
Emits events.AdResultEvent exactly once per request with a terminal status: filled, unfilled, blocked, timeout, error, skipped or cancelled. A result is guaranteed within the placement's resultTimeout (default 5000ms, 15000ms for in-stream video, not counting time spent deferred), regardless of how the ad is served.
nitroAds.adBlock
Emits events.AdBlockEvent once per page load with the ad block verdict, also available afterwards as window.nitroAds.adBlock (undefined until detection finishes, usually within 3 seconds). Ad block detection is only enabled for selected sites; elsewhere this event does not fire and window.nitroAds.adBlock stays undefined.
nitroAds.anchorVisibility
Emits events.AnchorVisibilityEvent when an anchor ad is shown or hidden.
nitroAds.complete
Emits events.VideoCompleteEvent when a video ad finishes playing.
nitroAds.onNavigate
Call ad.onNavigate() in single-page applications to clear and refresh the placement when navigating to a different URL.
Ad request state
Events are not replayed, so listeners added after an ad request started can read the current state instead:
ad.getState()on the object returned bycreateAdwindow.nitroAds.getAdState(id)by placement id
Both return an events.AdState, or null if the placement has not started a request yet.
The resultTimeout placement option (milliseconds, minimum 1000) controls how long a request may stay pending before it is reported as timeout.