API Reference

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

Methods Overview

Method	Description
init()	Initialize the player with configuration and start viewport observation
destroy()	Tear down the player and clean up resources
on()	Subscribe to a player event
off()	Unsubscribe from a player event
getVersion()	Get the library version
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

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

Most browsers block unmuted autoplay. When autoplay is true (default), the mute option should also be true to ensure reliable playback without user interaction.

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

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

TypeScript Definition

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

nexx360InstreamPlayer.destroy()

Example

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

---

on()

Subscribes to a player event.

Syntax

nexx360InstreamPlayer.on(event, callback)

Parameters

Parameter	Type	Description
event	string	Event name (see Events table)
callback	function	Handler function, receives optional event data

Example

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

nexx360InstreamPlayer.off(event, callback)

Parameters

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

Example

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).

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

---

getBuildDate()

Returns the library build date as an ISO string.

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

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

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