API Reference

This page documents all methods available on the n360ortb object.

Methods Overview

Method	Description
n360ortb.init()	Initialize the library with configuration
n360ortb.fetchBids()	Request bids for ad slots
n360ortb.setDisplayBids()	Set bid targeting on GPT slots
n360ortb.targetingKeys()	Get available targeting keys
n360ortb.onEvent()	Subscribe to an auction or render event
n360ortb.offEvent()	Remove an event listener
n360ortb.getEvents()	Get all events fired since page load

---

n360ortb.init()

Initializes the n360ortb library with your configuration. Must be called before fetchBids().

Syntax

n360ortb.init(config)

Parameters

config (required)

Property	Required	Type	Description
currency	Yes	'EUR' | 'USD' | 'GBP'	Currency for bid values
bidTimeout	No	number	Auction timeout in milliseconds. Default: 3000
gdpr	No	object	GDPR/TCF configuration
gpp	No	object	GPP (Global Privacy Platform) configuration
usPrivacy	No	object	US Privacy (CCPA) configuration
schain	No	object	Supply chain object

config.gdpr

Property	Required	Type	Description
cmpTimeout	No	number	Time to wait for CMP response in milliseconds. Default: 50
applies	No	boolean	Whether GDPR applies (bypasses CMP detection)
consent	No	string	TC consent string (bypasses CMP detection)

When applies and consent are provided directly, n360ortb skips CMP detection. This is useful when running inside a GAM creative iframe where the CMP is not accessible. See Integration in GAM as Creative for details on using GAM macros.

config.gpp

Property	Required	Type	Description
cmpTimeout	No	number	Time to wait for GPP CMP response in milliseconds. Default: 50

config.usPrivacy

Property	Required	Type	Description
cmpTimeout	No	number	Time to wait for USP CMP response in milliseconds. Default: 50

config.schain

Attached to every bid request at source.ext.schain (OpenRTB 2.5 placement). Invalid schain objects (missing nodes, malformed nodes, complete not 0/1) are silently dropped — enable debug: true to log the rejection.

Property	Required	Type	Description
complete	Yes	0 | 1	1 if the chain is complete, 0 if not
nodes	Yes	array	Array of supply chain nodes (must be non-empty)
ver	No	string	Schain version (e.g. '1.0')

Each node:

Property	Required	Type	Description
asi	Yes	string	Canonical domain of the ad system
sid	Yes	string	Seller/reseller account ID at the ad system
hp	Yes	0 | 1	1 if the seller has a direct relationship with the impression source
rid	No	string	Bid request ID at the ad system
name	No	string	Seller name (human-readable)
domain	No	string	Domain of the seller

Example

n360ortb.init({
  currency: 'EUR',
  bidTimeout: 2000,
  gdpr: {
    cmpTimeout: 1000
  },
  schain: {
    complete: 1,
    ver: '1.0',
    nodes: [
      {
        asi: 'publisher.com',
        sid: '123',
        hp: 1
      }
    ]
  }
});

TypeScript Definition

type Schain = {
  complete: 0 | 1;
  nodes: Array<{
    asi: string;
    sid: string;
    hp: 0 | 1;
    rid?: string;
    name?: string;
    domain?: string;
  }>;
  ver?: string;
};

type InitConfig = {
  currency: 'EUR' | 'USD' | 'GBP';
  bidTimeout?: number;
  gdpr?: {
    enabled?: boolean;
    cmpTimeout?: number;
    applies?: boolean;   // Direct consent passthrough
    consent?: string;    // Direct consent passthrough
  };
  gpp?: {
    cmpTimeout?: number;
  };
  usPrivacy?: {
    cmpTimeout?: number;
  };
  schain?: Schain;
};

function init(config: InitConfig): void;

---

n360ortb.fetchBids()

Requests bids from Nexx360's server-side auction for the specified ad slots.

Syntax

n360ortb.fetchBids(config, callback)

Parameters

config (required)

Property	Required	Type	Description
slots	Yes	array	Array of slot configurations
timeout	No	number	Override auction timeout for this request

config.slots[]

Each slot can be configured using either a tagId or a placement:

Property	Required	Type	Description
divId (or slotID)	Yes	string	The DOM element ID where the ad will render
sizes	Conditional	[number, number][]	Array of eligible banner sizes. Required for banner slots; optional for native-only slots
tagId	Conditional	string	Nexx360 tagId (use this OR placement)
placement	Conditional	string	Nexx360 placement code (use this OR tagId)
gpid	No	string	Global Placement ID forwarded as imp.ext.gpid in the OpenRTB request (e.g. /12345/homepage/box#div-gpt-ad-1)
mediaType	No	'display' | 'video' | 'native'	Declare the slot as native-only or video-only. Defaults to banner when sizes is present
native	No	object	Native configuration — see Native Ads
video	No	object	OpenRTB Video object for video slots

Use either tagId or placement to identify your ad unit, not both. The tagId is available in the Nexx360 console.

callback (required)

Function called when the auction completes. Receives the bids object as its argument.

Callback Response

The callback receives a bids object with the following structure:

type BidResponse = {
  [divId: string]: {
    cpm: number;           // Bid price in configured currency
    width: number;         // Creative width
    height: number;        // Creative height
    adm: string;           // Ad markup (HTML/JavaScript)
    creativeId: string;    // Creative identifier
    ssp: string;           // SSP that won the auction
    currency: string;      // Currency code
    dealId?: string;       // Deal ID if applicable
  };
};

Example

n360ortb.fetchBids({
  slots: [
    {
      tagId: 'homepage-leaderboard',
      divId: 'div-leaderboard',
      sizes: [[728, 90], [970, 250]]
    },
    {
      tagId: 'sidebar-mpu',
      divId: 'div-sidebar',
      sizes: [[300, 250], [300, 600]]
    }
  ]
}, function(bids) {
  console.log('Auction complete:', bids);

  // Example bid response:
  // {
  //   'div-leaderboard': {
  //     cpm: 2.50,
  //     width: 728,
  //     height: 90,
  //     adm: '<script>...</script>',
  //     creativeId: 'abc123',
  //     ssp: 'appnexus',
  //     currency: 'EUR'
  //   },
  //   'div-sidebar': {
  //     cpm: 1.80,
  //     width: 300,
  //     height: 250,
  //     adm: '<script>...</script>',
  //     creativeId: 'def456',
  //     ssp: 'rubicon',
  //     currency: 'EUR'
  //   }
  // }
});

TypeScript Definition

type Slot = {
  divId: string;
  sizes: [number, number][];
  tagId?: string;
  placement?: string;
};

type FetchBidsConfig = {
  slots: Slot[];
  timeout?: number;
};

type Bid = {
  cpm: number;
  width: number;
  height: number;
  adm: string;
  creativeId: string;
  ssp: string;
  currency: string;
  dealId?: string;
};

type BidResponse = {
  [divId: string]: Bid;
};

function fetchBids(config: FetchBidsConfig, callback: (bids: BidResponse) => void): void;

---

n360ortb.setDisplayBids()

Sets bid targeting values on Google Publisher Tag (GPT) ad slots. Call this method after fetchBids() completes and before calling googletag.pubads().refresh().

Syntax

n360ortb.setDisplayBids()

Parameters

None.

Behavior

This method:

1. Sets targeting key-value pairs on the corresponding GPT slots

2. Registers an event listener on slotRenderEnded to clear targeting after each slot renders

Targeting Keys Set

Key	Description
n360_bid	Unique bid identifier
n360_pb	Price bucket for line item targeting
n360_sz	Ad size (e.g., "300x250")
n360_crid	Creative ID
n360_ssp	SSP identifier
n360_mt	Media type: banner, video, or native

Native bids additionally set n360_native_title, n360_native_image, n360_native_icon, n360_native_brand, n360_native_body, n360_native_rating, n360_native_cta, and n360_native_linkurl. See Native Ads for details.

The n360_pb value uses medium granularity (same as Prebid.js). See Line Item Setup for full price bucket ranges and examples.

Example

n360ortb.fetchBids({
  slots: [
    { tagId: 'my-tag', divId: 'div-1', sizes: [[300, 250]] }
  ]
}, function(bids) {
  // Set targeting on GPT slots
  n360ortb.setDisplayBids();

  // Refresh the ads
  googletag.pubads().refresh();
});

---

n360ortb.targetingKeys()

Returns an array of all targeting keys used by n360ortb.

Syntax

n360ortb.targetingKeys()

Parameters

None.

Returns

string[] - Array of targeting key names.

Example

const keys = n360ortb.targetingKeys();
console.log(keys);
// ['n360_bid', 'n360_pb', 'n360_sz', 'n360_crid', 'n360_ssp', 'n360_mt',
//  'n360_native_title', 'n360_native_brand', 'n360_native_body',
//  'n360_native_cta', 'n360_native_image', 'n360_native_icon',
//  'n360_native_linkurl', 'n360_native_rating']

Use Case

Use this method to clear n360ortb targeting from slots if needed:

googletag.cmd.push(function() {
  var slot = googletag.pubads().getSlots()[0];
  n360ortb.targetingKeys().forEach(function(key) {
    slot.clearTargeting(key);
  });
});

---

Events

n360ortb emits events throughout the bid and render lifecycle, following the same model as Prebid.js events. Use onEvent() / offEvent() to subscribe and getEvents() to inspect history.

Event Types

Event	Fires when	Payload
requestBids	fetchBids() starts, after the OpenRTB request is built	{ slots, request }
bidResponse	Once for each bid received in the response	A StoredBid object
auctionEnd	Winning bids have been stored (also fires with an empty array when there are no bids)	{ bids }
bidTimeout	The bid request errors or times out	{ error }
setTargeting	Targeting has been applied to GPT slots	{ [slotID]: { key: value } }
bidWon	A creative pulls its markup (the bid is committed to render)	A StoredBid object
adRenderSucceeded	A creative reports a successful render	{ adId, bid }
adRenderFailed	A creative reports a failed render, or its bid could not be found	{ reason, message, adId, bid }

bidWon, adRenderSucceeded and adRenderFailed rely on the creative running the n360ortbDisplay library. Under SafeFrame and cross-domain rendering, the render result is reported back to the page via a postMessage signal — see the Display Library API Reference.

Events are not replayed to late subscribers. Register listeners before calling fetchBids(), or read past events with getEvents(). bidWon fires at most once per bid per auction.

---

n360ortb.onEvent()

Registers a listener for an event. Optionally filter by an id (slot ID for bidWon, ad/bid ID for adRenderSucceeded / adRenderFailed) so the handler only runs for that specific slot or ad.

Syntax

n360ortb.onEvent(eventType, handler, id)

Parameters

Parameter	Required	Type	Description
eventType	Yes	string	One of the event types above
handler	Yes	function	Callback invoked with the event payload
id	No	string	Only invoke the handler when the event's id (slot/ad ID) matches

Example

// Fire a tracker whenever any creative renders successfully
n360ortb.onEvent('adRenderSucceeded', function(data) {
  console.log('Rendered bid', data.adId, data.bid && data.bid.ssp);
});

// Listen only for a specific slot winning
n360ortb.onEvent('bidWon', function(bid) {
  console.log('Slot div-leaderboard won:', bid.price);
}, 'div-leaderboard');

---

n360ortb.offEvent()

Removes a previously registered listener. Pass the same eventType, handler reference, and id used with onEvent().

Syntax

n360ortb.offEvent(eventType, handler, id)

Example

function onRender(data) { /* ... */ }

n360ortb.onEvent('adRenderSucceeded', onRender);
// later
n360ortb.offEvent('adRenderSucceeded', onRender);

---

n360ortb.getEvents()

Returns a copy of every event fired since page load, in order. Useful for analytics or debugging — including for listeners registered after an auction already completed.

Syntax

n360ortb.getEvents()

Returns

An array of records:

type RecordedEvent = {
  eventType: string;   // e.g. 'bidWon'
  args: unknown;       // the event payload
  id?: string;         // slot/ad id, when the event carries one
  elapsedTime: number; // ms since page load (performance.now())
};

Example

const renders = n360ortb.getEvents()
  .filter(function(e) { return e.eventType === 'adRenderSucceeded'; });
console.log(renders.length + ' creatives rendered');

TypeScript Definition

type EventType =
  | 'requestBids'
  | 'bidResponse'
  | 'auctionEnd'
  | 'bidTimeout'
  | 'setTargeting'
  | 'bidWon'
  | 'adRenderSucceeded'
  | 'adRenderFailed';

function onEvent(eventType: EventType, handler: (payload: any) => void, id?: string): void;
function offEvent(eventType: EventType, handler: (payload: any) => void, id?: string): void;
function getEvents(): RecordedEvent[];