SSAI Documentation

Veeplay Dynamic Ad Insertion Documentation

Overview

Server side ad insertion is a modern streaming technique that minimizes buffering times and helps with avoiding lost ad inventory to client-side ad blockers.

This is accomplished by leveraging popular adaptive streaming protocols like HLS or DASH, creating a unified streaming manifest that contains both ad as well as main content.

When a request for a SSAI enabled streaming URL is made, our backend systems will ping pre-configured VAST ad servers and a manifest is generated on the fly, leveraging all available targeting data. This ensures that only the most relevant ads are still delivered to users.

Whenever new ad creatives are returned by the downstream ad servers, these ads are transcoded on the fly so that they match the variants of the original content.

Since the ads are now part of the video stream, video players would need additional logic in order to determine whether an ad is currently rendered and adapt the UI accordingly. Our SSAI solution exposes an additional endpoint that can be polled during a session in order to determine whether the current content is an ad or original content.

Veeplay 3.x series SDKs for Android and iOS support this endpoint out of the box. The SDKs will handle all ad tracking and overlays automatically.

In case your use-case requires playing back SSAI streams without any player modifications, we also provide a fully server-side set of URLs. Our backend will automatically process ad-server tracking according to the VAST standard, making this integration scenario essentially a drop-in replacement.

Preparing your content

In order to be able to use existing content sources with SSAI, incoming content needs to follow a set of requirements:

• Formatted in HLS (Apple HTTP Live Streaming) or in DASH (MPEG Dynamic Adaptive Streaming over HTTP)
• Is live content, or video-on-demand (VOD)
• Is accessible on the public internet and has a public IP address
• Contains ad markers to delineate ad breaks in the content

In order to know where inside the stream ads should be injected, the system relies on either SCTE-35 markers or VMAP 1.0 responses from the downstream ad-server. If neither are provided, the ads will be injected as pre-rolls at the beginning of the stream.

The types of SCTE-35 markers that are supported are detailed in the annexes of this document.

Are you looking for help with transcoding your content, or for different ways for accessing the SSAI processor? We're here to help, please reach out to our support engineers either using the chat buttons on our website or by emailing andrei@veeplay.com.

Generating SSAI streaming URLs using the Veeplay Panel

Once your content is formatted in a compatible playlist the SSAI streaming URLs can be generated.

In order to do this, navigate to https://panel.veeplay.com and login using your Veeplay credentials. All SSAI settings are grouped inside the SSAI tab on the main menu.

Fill in the following inputs:

• VAST URL - this is the endpoint that will be polled whenever the stream is requested. Our backend will expect that the response at this URL will either be a VAST tag, or a VMAP tag in case you're looking to use VMAP in order to schedule ad breaks.
• HLS or DASH content URL - this is the base URL of your CDN where HLS or DASH manifests are stored. Do not point directly to one of your manifests, just to the folder where these are stored. The name of the manifest should be appended to the generated links.
• Fallback VAST URL - this is an optional VAST tag that can be called in case the main one does not return any inventory.

After clicking Save, a set of 3 base URLs will be generated. You can append the name of any manifest available at the original URL in order to get links to specific streams on your CDN.

• a server side only HLS endpoint, usable with any HLS enabled player
• a server side only DASH endpoint, usable with any DASH enabled player
• a client-side enabled endpoint that you can use in conjunction with Veeplay 3.x SDKs for the best user experience.

Client SDK configuration for SSAI

Configuring the front-end libraries to work with SSAI URLs only entails specifying a unit manager when defining the main content. Snippets for programatic as well as JSON configuration methods are outlined below.

Veeplay SDK JSON configuration

{
  "content": [
    {
      "manager": "veeplay-ssai-client",
      "url": "<SSAI-URL>",
      "autoplay": true,
      "controls": {
        "components": [
          "playback",
          "totalTime",
          "slider",
          "currentTime",
          "fullscreen"
        ]
      }
    }
  ]
}

Veeplay SDK for Android configuration

APSMediaUnit ssaiUnit = new APSMediaUnit();
ssaiUnit.url = "<SSAI_URL>";
ssaiUnit.manager = SsaiClient.managerIdentifier;
ArrayList<APSMediaEvent> mediaUnits = new ArrayList<>();
mediaUnits.add(ssaiUnit);
APSMediaPlayer.getInstance().playMediaUnits(mediaUnits);

Veeplay SDK for iOS configuration

APSMediaUnit *ssaiUnit = [[APSMediaUnit alloc] initWithURL:[NSURL URLWithString:@"<SSAI_URL>"]];
ssaiUnit.managerType = APSSSAIClientType;
[[APSMediaPlayer sharedInstance] playMediaUnits:@[ssaiUnit]];

Annex 1: SCTE-35 marker support

#EXT-X-CUE-OUT:DURATION=120
...
#EXT-X-CUE-IN


#EXT-X-CUE-OUT:30.000 
...
#EXT-X-CUE-IN


#EXT-X-CUE-OUT
...
#EXT-X-CUE-IN


#EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",DURATION=60.000,SCTE35-OUT=0xF


#EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",SCTE35-OUT=0xF
...
#EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",SCTE35-IN=0xF


#EXT-X-SPLICEPOINT-SCTE35:/DA9AAAAAAAAAP/wBQb+uYbZqwAnAiVDVUVJAAAKqX//AAEjW4AMEU1EU05CMDAxMTMyMjE5M19ONAAAmXz5JA==
...
#EXT-X-SPLICEPOINT-SCTE35:/DA4AAAAAAAAAP/wBQb+tTeaawAiAiBDVUVJAAAKqH+/DBFNRFNOQjAwMTEzMjIxOTJfTjUAAIiGK1s=