# API Reference

This page documents all methods available on the `nexx360InstreamPlayer` object (exposed as `window.nexx360InstreamPlayer`).

## Methods Overview

| Method                          | Description                                                             |
| ------------------------------- | ----------------------------------------------------------------------- |
| [init()](#init)                 | Initialize the player with configuration and start viewport observation |
| [destroy()](#destroy)           | Tear down the player and clean up resources                             |
| [on()](#on)                     | Subscribe to a player event                                             |
| [off()](#off)                   | Unsubscribe from a player event                                         |
| [getVersion()](#getversion)     | Get the library version                                                 |
| [getBuildDate()](#getbuilddate) | Get the library build date                                              |

***

## init()

Initializes the instream player with your configuration. The player immediately starts observing the container element — when 50% of it enters the viewport, the ad request is sent and playback begins automatically.

### Syntax

```javascript
nexx360InstreamPlayer.init(config)
```

### Parameters

#### config (required)

| Property    | Required | Type                      | Default | Description                                 |
| ----------- | -------- | ------------------------- | ------- | ------------------------------------------- |
| tagId       | Yes      | `string`                  | —       | Nexx360 tagId for the ad unit               |
| container   | Yes      | `HTMLElement` \| `string` | —       | Container element or its DOM ID             |
| width       | No       | `number`                  | `640`   | Player width in pixels                      |
| height      | No       | `number`                  | `480`   | Player height in pixels                     |
| autoplay    | No       | `boolean`                 | `true`  | Auto-play when entering viewport            |
| mute        | No       | `boolean`                 | `true`  | Start muted (required for browser autoplay) |
| minDuration | No       | `number`                  | —       | Minimum ad duration in seconds              |
| maxDuration | No       | `number`                  | —       | Maximum ad duration in seconds              |
| startdelay  | No       | `number`                  | —       | OpenRTB start delay value                   |
| gdpr        | No       | `string`                  | —       | GDPR applies flag (`'1'` or `'0'`)          |
| gdprConsent | No       | `string`                  | —       | TCF v2 consent string                       |
| usPrivacy   | No       | `string`                  | —       | US Privacy string (e.g. `'1YNN'`)           |
| test        | No       | `boolean`                 | `false` | Enable test mode in bid requests            |
| bidTimeout  | No       | `number`                  | `3000`  | Auction timeout in milliseconds             |

{% hint style="info" %}
Most browsers block unmuted autoplay. When `autoplay` is `true` (default), the `mute` option should also be `true` to ensure reliable playback without user interaction.
{% endhint %}

### Autoplay & Mute — OpenRTB Mapping

The `autoplay` and `mute` parameters control the OpenRTB `playbackmethod` value sent in the bid request:

| autoplay         | mute             | playbackmethod | Description                                   |
| ---------------- | ---------------- | -------------- | --------------------------------------------- |
| `true` (default) | `true` (default) | `6`            | Initiates on Entering Viewport with Sound Off |
| `true`           | `false`          | `5`            | Initiates on Entering Viewport with Sound On  |
| `false`          | any              | `3`            | Initiates on Click with Sound On              |

### Example

```javascript
nexx360InstreamPlayer.init({
  tagId: 'my-instream-tag',
  container: 'video-ad',
  width: 640,
  height: 360,
  autoplay: true,
  mute: true,
  maxDuration: 30,
  bidTimeout: 2000
});
```

### TypeScript Definition

```typescript
type InstreamPlayerConfig = {
  tagId: string;
  container: HTMLElement | string;
  width?: number;       // default: 640
  height?: number;      // default: 480
  autoplay?: boolean;   // default: true
  mute?: boolean;       // default: true
  minDuration?: number;
  maxDuration?: number;
  startdelay?: number;
  gdpr?: string;
  gdprConsent?: string;
  usPrivacy?: string;
  test?: boolean;
  bidTimeout?: number;  // default: 3000
};

function init(config: InstreamPlayerConfig): void;
```

***

## destroy()

Tears down the player: stops viewport observation, destroys the IMA SDK instances, removes DOM elements, and emits the `destroyed` event.

### Syntax

```javascript
nexx360InstreamPlayer.destroy()
```

### Example

```javascript
// Clean up when navigating away or when done with the ad
nexx360InstreamPlayer.destroy();
```

***

## on()

Subscribes to a player event.

### Syntax

```javascript
nexx360InstreamPlayer.on(event, callback)
```

### Parameters

| Parameter | Type       | Description                                    |
| --------- | ---------- | ---------------------------------------------- |
| event     | `string`   | Event name (see [Events](#events) table)       |
| callback  | `function` | Handler function, receives optional event data |

### Example

```javascript
nexx360InstreamPlayer.on('started', function() {
  console.log('Video ad started playing');
});

nexx360InstreamPlayer.on('error', function(data) {
  console.error('Ad error:', data.message, 'code:', data.code);
});
```

***

## off()

Unsubscribes from a player event.

### Syntax

```javascript
nexx360InstreamPlayer.off(event, callback)
```

### Parameters

| Parameter | Type       | Description                                  |
| --------- | ---------- | -------------------------------------------- |
| event     | `string`   | Event name                                   |
| callback  | `function` | The same function reference passed to `on()` |

### Example

```javascript
function onStarted() {
  console.log('Ad started');
}

nexx360InstreamPlayer.on('started', onStarted);

// Later, remove the listener
nexx360InstreamPlayer.off('started', onStarted);
```

***

## getVersion()

Returns the library version string (set at build time from the release tag).

```javascript
nexx360InstreamPlayer.getVersion(); // e.g. '0.0.1'
```

***

## getBuildDate()

Returns the library build date as an ISO string.

```javascript
nexx360InstreamPlayer.getBuildDate(); // e.g. '2026-04-13T12:00:00.000Z'
```

***

## Events

All events can be subscribed to using `on()` and unsubscribed from using `off()`.

| Event             | Description                                       | Data                                |
| ----------------- | ------------------------------------------------- | ----------------------------------- |
| `loaded`          | Ad creative has been loaded by IMA                | —                                   |
| `started`         | Ad playback has started                           | —                                   |
| `firstQuartile`   | Ad reached 25% completion                         | —                                   |
| `midpoint`        | Ad reached 50% completion                         | —                                   |
| `thirdQuartile`   | Ad reached 75% completion                         | —                                   |
| `complete`        | Ad playback completed (100%)                      | —                                   |
| `allAdsCompleted` | All ads in the pod have completed                 | —                                   |
| `click`           | User clicked the ad                               | —                                   |
| `paused`          | Ad was paused (e.g. scrolled out of viewport)     | —                                   |
| `resumed`         | Ad was resumed (e.g. scrolled back into viewport) | —                                   |
| `skipped`         | User skipped the ad                               | —                                   |
| `error`           | An error occurred                                 | `{ message: string, code: number }` |
| `destroyed`       | Player was destroyed via `destroy()`              | —                                   |

### Example: Tracking All Events

```javascript
var events = [
  'loaded', 'started', 'firstQuartile', 'midpoint', 'thirdQuartile',
  'complete', 'allAdsCompleted', 'click', 'paused', 'resumed',
  'skipped', 'error', 'destroyed'
];

events.forEach(function(event) {
  nexx360InstreamPlayer.on(event, function(data) {
    console.log('[instream]', event, data || '');
  });
});
```

***

## Full Integration Example

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://lib.nexx360.io/nexx360instream/api.js"></script>
</head>
<body>
  <h1>Article Title</h1>
  <p>Article content goes here...</p>

  <!-- Ad container placed within article content -->
  <div id="instream-ad" style="width: 640px; height: 360px;"></div>

  <p>More article content...</p>

  <script>
    // Subscribe to events before init
    nexx360InstreamPlayer.on('started', function() {
      console.log('Ad started');
    });

    nexx360InstreamPlayer.on('complete', function() {
      console.log('Ad complete');
    });

    nexx360InstreamPlayer.on('error', function(data) {
      console.error('Ad error:', data);
    });

    // Initialize — auto-plays when user scrolls to the container
    nexx360InstreamPlayer.init({
      tagId: 'your-tag-id',
      container: 'instream-ad',
      width: 640,
      height: 360
    });
  </script>
</body>
</html>
```


---

# 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/instream-player/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.