# 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](https://developer.nexx360.io/direct-integration-n360ortb/gam-integration/integration-in-gam-as-creative) 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

| Property | Required | Type    | Description                        |
| -------- | -------- | ------- | ---------------------------------- |
| complete | Yes      | `1`     | Indicates if the chain is complete |
| ver      | Yes      | `'1.0'` | Schain version                     |
| nodes    | Yes      | array   | Array of supply chain nodes        |

### 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: 1;
  ver: '1.0';
  nodes: Array<{
    asi: string;
    sid: string;
    hp: number;
    rid?: string;
    name?: string;
    domain?: 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     | Yes         | string               | The DOM element ID where the ad will render |
| sizes     | Yes         | `[number, number][]` | Array of eligible sizes (width, height)     |
| tagId     | Conditional | string               | Nexx360 tagId (use this OR placement)       |
| placement | Conditional | string               | Nexx360 placement code (use this OR tagId)  |

{% 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                       |

{% hint style="info" %}
The `n360_pb` value uses medium granularity (same as Prebid.js). See [Line Item Setup](https://developer.nexx360.io/direct-integration-n360ortb/gam-integration/line-item-setup) 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']
```

### 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);
  });
});
```