How to Add a Video Submodule

Video submodules interact with the Video Module to integrate Prebid with Video Players, allowing Prebid to automatically:

• Overview
• Requirements
• Creating a Submodule
  • Step 1: Add a Markdown File Describing the Submodule
  • Step 2: Add a Vendor Code
  • Step 3: Build the Module
    • The Submodule factory
    • The Submodule object
    • Event Registration
      • onEvent
      • offEvent
    • Update .submodules.json
• Shared Resources for Developers

Overview

The Prebid Video Module simplifies the way Prebid integrates with video players by acting as a single point of contact for everything video. In order for the Video Module to connect to a video player, a submodule must be implemented. The submodule acts as a bridge between the Video Module and the video player. The Video Module will route commands and tasks to the appropriate submodule instance. A submodule is expected to work for a specific video player. i.e. the JW Player submodule is used to integrate Prebid with JW Player. The video.js submdule connects to video.js. Publishers who use players from different vendors on the same page can use multiple video submodules.

Requirements

The Video Module only supports integration with Video Players that meet the following requirements:

• Must support parsing and reproduction of VAST ads.
  • Input can be an ad tag URL or the actual Vast XML.
• Must expose an API that allows the procurement of Open RTB params for Video (section 3.2.7) and Content (section 3.2.16).
• Must emit javascript events for Ads and Media.
  • see Event Registration.

Creating a Submodule

Working with any Prebid project requires using Github. In general, we recommend the same basic workflow for any project:

1. Fork the appropriate Prebid repository (e.g. Prebid.js).
2. Create a branch in your fork for your proposed code change (e.g. feature/exampleVideoProvider).
3. Build and test your feature/bug fix in the branch.
4. Open a pull request to the appropriate repository’s master branch with a good description of the feature/bug fix.
5. If there’s something that needs to change on the prebid.org website, follow the above steps for the website repo.

Step 1: Add a Markdown File Describing the Submodule

Create a markdown file under modules with the name of the module suffixed with ‘VideoProvider’, i.e. exampleVideoProvider.md.

Example markdown file:

# Overview

Module Name: Example Video Provider
Module Type: Video Submodule
Video Player: Example player
Player website: example-player.com
Maintainer: someone@example.com

# Description

Video provider for Example Player. Contact someone@example.com for information.

# Requirements

Your page must link the Example Player build from our CDN. Alternatively you can use npm to load the build.

Step 2: Add a Vendor Code

Vendor codes are required to indicate which submodule type to instantiate. Add your vendor code constant to an export const in vendorCodes.js in Prebid.js under libraries/video/constants/vendorCodes.js. i.e. in vendorCodes.js:

export const EXAMPLE_PLAYER_VENDOR = 3;

Step 3: Build the Module

Now create a javascript file under modules with the name of the module suffixed with ‘VideoProvider’, e.g., exampleVideoProvider.js.

The Submodule factory

The Video Module will need a submodule instance for every player instance registered with Prebid. You will therefore need to implement a submodule factory which is called with a videoProviderConfig argument and returns a Video Provider instance. Your submodule should import your vendor code constant and set it to a vendorCode property on your submodule factory. Your submodule should also import the submodule function from src/hook.js and should use it to register as a submodule of 'video'.

Code Example

import { submodule } from '../src/hook.js';

function exampleSubmoduleFactory(videoProviderConfig) {
  const videoProvider = {
    // implementation
  };

  return videoProvider;
}

exampleSubmoduleFactory.vendorCode = EXAMPLE_VENDOR;
submodule('video', exampleSubmoduleFactory);

The Submodule object

The submodule object must adhere to the following interface:

For example:

const exampleSubmodule =  {
  init: init,
  getId: getId,
  getOrtbVideo: getOrtbVideo,
  getOrtbContent: getOrtbContent,
  setAdTagUrl: setAdTagUrl,
  onEvent: onEvent,
  offEvent: offEvent,
  destroy: destroy
};

Event Registration

Submodules must support attaching and detaching event listeners on the video player. The list of events and their respective params are defined in the Video Module docs’s Events section.

onEvent

offEvent

Update .submodules.json

In prebid.js, add your new submodule to .submodules.json under the videoModule as such:

{
  "parentModules": {
    "videoModule": [
      "exampleVideoProvider"
    ]
  }
}

Shared Resources for Developers

A video library containing reusable code and constants has been added to Prebid.js for your convenience. We encourage you to import from this library. Constants such as event names can be found in the libraries/video/constants/ folder.