@fnet/ima

This project, @fnet/ima, is designed to manage and display video advertisements on a web-based video player interface. It acts as a middleware layer that integrates Google's IMA (Interactive Media Ads) SDK to enable seamless advertisement playback in your web applications.

How It Works

The primary function of @fnet/ima is to load and manage video ad content using Google's IMA SDK. It initializes ad resources, requests ads using VAST (Video Ad Serving Template) providers, and handles ad playback events and errors. When integrated into a web application, it facilitates a smooth ad experience by managing the various states and operations of video advertisements.

Key Features

• Ad Display Management: Utilizes Google's IMA SDK to manage ad display containers and load ads effectively.
• Event Handling: Provides an event-driven architecture to manage ad-related events like load, start, complete, error, and more.
• Ad Interaction Controls: Offers controls to start, stop, pause, resume, and skip ads.
• Responsive Resizing: Automatically adjusts ad display size when the window is resized or the player goes fullscreen.
• Customizable VAST Providers: Supports integration with custom VAST providers for ad request configuration.

Conclusion

The @fnet/ima project provides a straightforward solution for integrating video advertisements using Google's IMA SDK in web applications. It simplifies ad management and enhances the user experience by efficiently handling ad lifecycle and playback events. Through its clear API and event-driven approach, it aids developers in creating interactive media environments with reliable ad support.

Developer Guide for @fnet/ima

Overview

The @fnet/ima library provides a streamlined integration with Google's Interactive Media Ads (IMA) SDK, allowing developers to easily manage video ads within their web applications. The main functionalities include initializing ad containers, loading and displaying ads, and controlling ad playback through a simple API. This guide will help you utilize the core components of the library to manage video advertisements effectively, ensuring a seamless ad experience in your applications.

Installation

To install the @fnet/ima library, you can use either npm or yarn. Here are the commands:

# Using npm
npm install @fnet/ima

# Using yarn
yarn add @fnet/ima

Usage

The following sections provide examples and explanations on how to implement the @fnet/ima library in your project.

Initialization

To start using the library, you first need to initialize it with the required configuration:

import imaLoader from '@fnet/ima';

async function setupIMA() {
  const config = {
    container: document.getElementById('ad-container'), // HTML container for ads
    player: document.getElementById('video-player'), // Video player element
    width: 640, // Optional: Ad container width
    height: 360, // Optional: Ad container height
    logger: console, // Optional: Logger for ad events
  };

  const imaHandler = await imaLoader(config);

  // Further interactions with imaHandler as shown in examples below
}

Requesting Ads

Once the imaHandler is initialized, you can request ads through the following method:

async function requestAd() {
  try {
    await imaHandler.requestAds();
    console.log('Ad requested successfully.');
  } catch (error) {
    console.error('Failed to request ad:', error);
  }
}

Controlling Ads

Use the following methods to control ad playback:

• Start Ads: Begin ad playback after ads have been loaded.

  imaHandler.start();

• Pause and Resume Ads:

  imaHandler.pause();
  imaHandler.resume();

• Skip Ads:

  imaHandler.skip();

• Stop Ads:

  imaHandler.stop();

Ad Event Handling

Listen to ad events to manage and respond to various ad lifecycle events:

imaHandler.on('adsManagerLoaded', () => {
  console.log('Ads Manager Loaded');
});

imaHandler.on('adStarted', () => {
  console.log('Ad Started');
});

imaHandler.on('adCompleted', () => {
  console.log('Ad Completed');
});

// Remove listeners when not needed
imaHandler.off('adStarted');

Examples

Below are some practical code examples to showcase using @fnet/ima.

Example: Basic Ad Integration

import imaLoader from '@fnet/ima';

async function setupIMA() {
  const config = { container: document.getElementById('ad-container'), player: document.getElementById('video-player') };
  const imaHandler = await imaLoader(config);

  imaHandler.on('adsManagerLoaded', () => console.log('Ads loaded'));

  try {
    await imaHandler.requestAds();
    imaHandler.start();
  } catch (error) {
    console.error('Ad request failed:', error);
  }
}

setupIMA();

Example: Advanced Ad Controls

async function advancedAdControl() {
  const config = { container: document.getElementById('ad-container'), player: document.getElementById('video-player') };
  const imaHandler = await imaLoader(config);
  
  await imaHandler.requestAds();

  if (await userWantsToSkip()) {
    imaHandler.skip();
  }

  window.addEventListener('resize', () => {
    imaHandler.resize(window.innerWidth, window.innerHeight);
  });
}

advancedAdControl();

Acknowledgement

This library utilizes Google's IMA SDK to manage and display video ads. Any contributions or collaborations from the broader developer community should be recognized per your project's specific guidelines.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  container:
    type: object
    description: The HTML container element for displaying ads.
  player:
    type: object
    description: The media player object used for playing ads.
  width:
    type: integer
    description: The width of the ad container.
  height:
    type: integer
    description: The height of the ad container.
  logger:
    type: object
    description: Logger object for handling log events.
required:
  - container
  - player