# API Reference

This page documents all methods available on the `n360ortb` object.

## Methods Overview

| Method                                                | Description                               |
| ----------------------------------------------------- | ----------------------------------------- |
| [n360ortb.init()](#n360ortb-init)                     | Initialize the library with configuration |
| [n360ortb.fetchBids()](#n360ortb-fetchbids)           | Request bids for ad slots                 |
| [n360ortb.setDisplayBids()](#n360ortb-setdisplaybids) | Set bid targeting on GPT slots            |
| [n360ortb.targetingKeys()](#n360ortb-targetingkeys)   | Get available targeting keys              |

***

## n360ortb.init()

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

### Syntax

```javascript
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)                 |

{% hint style="info" %}
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](/integration-methods/direct-integration-n360ortb/gam-integration/integration-in-gam-as-creative.md) for details on using GAM macros.
{% endhint %}

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

```javascript
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

```typescript
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

```javascript
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](/integration-methods/direct-integration-n360ortb/native-integration.md)  |
| video                 | No          | object                                 | OpenRTB Video object for video slots                                                                             |

{% hint style="info" %}
Use either `tagId` or `placement` to identify your ad unit, not both. The `tagId` is available in the Nexx360 console.
{% endhint %}

#### 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:

```typescript
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

```javascript
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

```typescript
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

```javascript
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](/integration-methods/direct-integration-n360ortb/native-integration.md) for details.

{% hint style="info" %}
The `n360_pb` value uses medium granularity (same as Prebid.js). See [Line Item Setup](/integration-methods/direct-integration-n360ortb/gam-integration/line-item-setup.md) for full price bucket ranges and examples.
{% endhint %}

### Example

```javascript
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

```javascript
n360ortb.targetingKeys()
```

### Parameters

None.

### Returns

`string[]` - Array of targeting key names.

### Example

```javascript
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:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.nexx360.io/integration-methods/direct-integration-n360ortb/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.