Player-side ad insertion

With a few small pieces of custom Java and HTML code, you can extend Wowza Streaming Engine™ media server software to insert ad requests dynamically and enable a player to insert and display ads during playback of live Apple HLS streams.

The player-side ad insertion workflow uses an HTTP Provider to enable Wowza Streaming Engine to receive a request to insert an ad break into a live stream. Then it uses an event-listener module to convert the HTTP request to an ID3 tag that it sends with the transmuxed Apple HLS stream to supporting players. Finally, custom code on the player side detects the tag and makes a Video Ad Serving Template (VAST) call to retrieve and play the ad during playback.

Example code and a sample ad are provided to demonstrate how to extend the Wowza Streaming Engine server to support player-side ad insertion for Apple HLS playback on JW Player. The same workflow with different code can be used to insert ads using a player that supports RTMP playback.

Prerequisites

Wowza Streaming Engine 4.0.0 or later.

JW Player 7.0, cloud or self-hosted version.

Player-side ad insertion files (adDemo.zip) are also required. The compressed (zipped) folder contains the following files:

/java/HTTPProviderAdBreakInsertion.java - An HTTP Provider that allows Wowza Streaming Engine to accept an HTTP POST request to inject a data event into the ingested stream that's requesting the ad break.
/java/ModuleCupertinoLiveOnAdBreakToID3.java - A Wowza Streaming Engine module that listens for the data event in the stream during transmuxing. It converts the event to an ID3 tag in the Apple HLS stream that Wowza Streaming Engine sends to the player.
/html/live_ad.html - HTML code that contains the button to insert the ad break and plays the video. Includes the JW Player custom code that detects the ad break, makes the VAST call, and plays the ad.
/html/testVAST.xml - The VAST XML file that points to the sample ad. For this demo, it's deployed to a local web server.
/html/testAd.mp4 - The sample ad.
readme.html - A readme file.

Download adDemo.zip

Wowza Streaming Engine setup

Start by preparing your Wowza Streaming Engine instance to receive and process an ad break request using the live application that comes pre-configured with the Wowza Streaming Engine Manager.

On the Setup tab of the live application, under Playback Types, make sure Apple HLS is selected.
Click Sources (Live), select the encoder or camera you're using for your source, and make sure the Stream Name is myStream. For more information about configuring a live stream source, see How to connect a live source to Wowza Streaming Engine.
If you haven't done so already, download adDemo.zip and extract its contents.
Compile /java/HTTPProviderAdBreakInsertion.java and /java/ModuleCupertinoLiveOnAdBreakToID3.java into a .jar file and then copy the .jar file to the Wowza Streaming Engine [install-dir]/lib folder.

HTTP Provider configuration

The ad demo HTTP Provider allows Wowza Streaming Engine to accept an HTTP POST request to inject a data event into the ingested stream that's requesting the ad break.

Open [install-dir]/conf/VHost.xml in a text editor.
Add the following to the list of host port 8086 providers:

<HTTPProvider>
	<BaseClass>com.wowza.wms.plugin.addemo.HTTPProviderAdBreakInsertion</BaseClass>
	<RequestFilters>insertadmarker*</RequestFilters>
	<AuthenticationMethod>none</AuthenticationMethod>
</HTTPProvider>

Important: Be sure to add the ad demo provider immediately above the last provider in the 8086 list (http.HTTPServerVersion).

Custom module configuration

The custom ad demo module listens for the data event while Wowza Streaming Engine transmuxes the live stream. When the module detects the event, it converts the event to an ID3 tag in the Apple HLS stream that it sends to the player.

Open [install-dir]/conf/live/Application.xml in a text editor.
Add the following properties to the Modules section:

<Module>
	<Name>ModuleAdID3Tags</Name>
	<Description>Convert ad requests to ID3 tags</Description>
	<Class>com.wowza.wms.plugin.addemo.ModuleCupertinoLiveOnAdBreakToID3</Class>
</Module>

Alternatively, you can configure the ad demo event listener in the Modules tab of the live application in Wowza Streaming Engine Manager. Access to the Modules tab requires an administrator user with advanced permissions. See Configure modules for details.

Name	Description	Fully Qualified Class Name
ModuleAdID3Tags	Converts ad requests to ID3 tags.	com.wowza.wms.plugin.addemo.ModuleCupertinoLiveOnAdBreakToID3

Player configuration

Copy the contents of /html/ from the extracted adDemo.zip folder to a local web server, for example, to localhost/ads/.

Final configuration

Restart the Wowza Streaming Engine server.
In a web browser, load localhost/ads/live_ad.html.

Usage

Now you can make ad break requests in the live stream.

In Wowza Streaming Engine Manager, start the stream source for the live application to begin your live streaming broadcast.
When you want to insert an ad into the live stream, use a command-line tool such as Terminal to make an HTTP POST call to the Wowza Streaming Engine instance. The base resource for the request is the URL-encoded VAST ad URL. For example,

http://localhost:8086/insertadmarker?application=live&streamName=myStream&url=http://localhost/ads/testVAST.xml

Alternatively, click the Insert Ad button in live_ad.html to make the HTTP POST call for this demonstration.

The ad appears in the player when the ad break occurs in the stream.

More resources

How to enable player-side ad insertion using Wowza Streaming Engine (video tutorial)

How to extend Wowza Streaming Engine using the Wowza IDE

Wowza Media Systems™ provides developers with a platform to create streaming applications and solutions. See Wowza Developer Tools to learn more about our APIs and SDK.

Contact

Wowza Media Systems, LLC

License

This code is distributed under the Wowza Public License.

WowzaMediaSystems/wse-example-ad-insertion