Ads / Campaign loading for Clients

Ads / Campaign loading for Clients

Introduction

This document describes what clients need to do in order to fetch active Campaigns using the Suite Campaign API and display ads on the video player (Radiant Media Player used as an example here) based on the response.

Fetching Active Campaigns

A list of active campaigns can be fetched using the /api/campaign/v5 endpoint. A successful call to this API will return a list of currently active Campaigns. The response contains data that can then be used to generate VAST URLs that can in turn be used by the video player in order to display ads to the end user.

Endpoint

Path

/api/campaign/v5

Parameters

Required Parameters

action: value must be getActiveCampaigns
organizationId: Suite Organization ID

Optional Parameters

campaignType:  A comma separated list of campaign types that the API should return. If provided, the API will only return Campaigns of the specified type(s). Possible values: 'banner', 'switchIn', 'inStreamVideo', 'inVideoOverlay', 'activead', 'videoswap'

contentType: If provided, the API will only return Campaigns whose contentType match the provided value. Possible values for contentType: 0 (VOD and LIVE), 1 (VOD), 2 (LIVE)

Example

Below is an example of a proper request for fetching all active campaigns of types inStreamVideo and inVideoOverlay for an Organization with a contentType of VOD:

/api/campaign/v5?action=getActiveCampaigns&organizationId=:org&contentType=1&campaignType=inStreamVideo,inVideoOverlay

Response

  1. {
  2.   "campaigns": [
  3.     {
  4.       "adProfileId": 7154101,
  5.       "campaignId": 7154701,
  6.       "campaignName": "Overlay 1",
  7.       "channels": [
  8.         {
  9.           "id": 2633044,
  10.           "name": "Tapahtumakanava"
  11.         }
  12.       ],
  13.       "contentType": 1,
  14.       "endTime": "2023-03-24T03:00:00Z",
  15.       "startTime": "2023-02-16T03:00:00Z",
  16.       "type": "invideooverlay"
  17.     },
  18.     {
  19.       "adProfile": {
  20.         "displayInterval": 60,
  21.         "profileType": 2,
  22.         "skipOffset": 5
  23.       },
  24.       "adProfileId": 10732501,
  25.       "campaignId": 10796301,
  26.       "campaignName": "In stream midroll",
  27.       "channels": [],
  28.       "contentType": 1,
  29.       "endTime": "2023-03-28T05:00:00Z",
  30.       "startTime": "2023-03-21T05:00:00Z",
  31.       "type": "instreamvideo"
  32.     },
  33.     {
  34.       "adProfile": {
  35.         "profileType": 3,
  36.         "skipOffset": 10
  37.       },
  38.       "adProfileId": 10127701,
  39.       "campaignId": 10998001,
  40.       "campaignName": "in stream postroll",
  41.       "channels": [],
  42.       "contentType": 1,
  43.       "endTime": "2023-03-31T00:00:00Z",
  44.       "startTime": "2023-03-24T00:00:00Z",
  45.       "type": "instreamvideo"
  46.     }
  47.   ]
  48. }

Displaying Ads on the Client

After you have fetched the list of active Campaigns using the API, you need to configure the player to display the ads. How this is done of course depends on the player being used. This document will give an example using Radiant Media Player, but be aware that other players most likely initiate ads differently.

Generating the VAST URL

Once you have received a list of campaigns from the API, you will need to generate a VAST URL for the advert.

How a VAST URL is configured differs slightly depending on whether you are generating a VAST URL to be used in a LIVE player or a VOD player:

VOD Player

/api/vast?type=vod&campaignIds=<COMMA SEPARETED LIST OF CAMPAIGN IDS>&assetId=<ID OF THE SUITE ASSET BEING WATCHED>&organizationId=<SUITE ORGANIZATION ID>&applicationId=1&applicationTypeId=1&deviceId=<DEVICE ID GENERATED FOR ANALYTICS>

LIVE Player

/api/vast?type=live&campaignIds=<COMMA SEPARATED LIST OF CAMPAIGN IDS>&channelId=<ID OF THE SUITE CHANNEL BEING WATCHED>&organizationId=<SUITE ORGANIZATION ID>&adProfileType=<AD PROFILE TYPE>&deviceId=<DEVICE ID GENERATED FOR ANALYTICS>

Understanding the API response

This document will focus on campaigns of type inStreamVideo and inVideoOverlay, as those are the types of Campaigns that are intended for web use.

inStreamVideo

Campaigns of type inStreamVideo are video ads that can include either preroll (0), midroll (2) or postroll (3) ad profiles.

These campaigns include an adProfile object, such as this:

  1. "adProfile": {
  2.     "displayInterval": 60,
  3.     "profileType": 2,
  4.     "skipOffset": 5
  5. },

From the adProfile object, you can see the type of the ad profile.

How you set them up in the player depends on the type of the ad profile:

Ad types and what to do with them

      Type 0: Preroll
  • Generate a VAST URL for either LIVE or VOD depending on what content is being watched.
  • Add the generated VAST URL to the video player as a preroll ad
      Type 2: Midroll
  • Generate a VAST URL for either LIVE or VOD depending on what content is being watched.
  • Midroll ads will include a displayInterval value inside the adProfile object. This value tells you that the midroll ad should be displayed every X seconds where X is the value of displayInterval. This needs to be configured on the player, how this is done depends on the player being used.
  • Add the generated VAST URL to the video player as a midroll ad taking into account the displayInterval value
      Type 3: Postroll

      POSTROLL ADS SHOULD ONLY BE USED WITH VOD CONTENT

  • Generate a VAST URL for VOD depending on what content is being watched.
  • Add the generated VAST URL to the video player as a postroll ad
Radiant Media Player example

In this example we will make the following assumptions: Suite organization ID is 2631609, ID of the asset being watched is 54321, and the generated device ID for analytics is this-is-just-an-example.

Say you have the following response from the Campaign API:

  1. {
  2.   "campaigns": [
  3.     {
  4.       "adProfile": {
  5.         "profileType": 0,
  6.         "skipOffset": 5
  7.       },
  8.       "adProfileId": 10111501,
  9.       "campaignId": 7154601,
  10.       "campaignName": "In stream preroll",
  11.       "channels": [],
  12.       "contentType": 0,
  13.       "endTime": "2023-03-30T04:00:00Z",
  14.       "startTime": "2023-02-16T04:00:00Z",
  15.       "type": "instreamvideo"
  16.     },
  17.     {
  18.       "adProfile": {
  19.         "displayInterval": 60,
  20.         "profileType": 2,
  21.         "skipOffset": 5
  22.       },
  23.       "adProfileId": 10732501,
  24.       "campaignId": 10796301,
  25.       "campaignName": "In stream midroll",
  26.       "channels": [],
  27.       "contentType": 1,
  28.       "endTime": "2023-03-28T05:00:00Z",
  29.       "startTime": "2023-03-21T05:00:00Z",
  30.       "type": "instreamvideo"
  31.     },
  32.     {
  33.       "adProfile": {
  34.         "profileType": 3,
  35.         "skipOffset": 10
  36.       },
  37.       "adProfileId": 10127701,
  38.       "campaignId": 10998001,
  39.       "campaignName": "in stream postroll",
  40.       "channels": [],
  41.       "contentType": 1,
  42.       "endTime": "2023-03-31T00:00:00Z",
  43.       "startTime": "2023-03-24T00:00:00Z",
  44.       "type": "instreamvideo"
  45.     }
  46.   ]
  47. }

The above response contains three different ad types: preroll, midroll and postroll.

First generate the VAST URLs for each campaign returned:

First campaign:

  1. {
  2.   "adProfile": {
  3.     "profileType": 0,
  4.     "skipOffset": 5
  5.   },
  6.   "adProfileId": 10111501,
  7.   "campaignId": 7154601,
  8.   "campaignName": "In stream preroll",
  9.   "channels": [],
  10.   "contentType": 0,
  11.   "endTime": "2023-03-30T04:00:00Z",
  12.   "startTime": "2023-02-16T04:00:00Z",
  13.   "type": "instreamvideo"
  14. }

Make sure to note that the profileType of the adProfile of this Campaign is 0, which means that it is a preroll ad

VAST URL for this campaign will look like this when we assume that the Suite Organization ID is 2631609 and the Suite asset ID is 54321: 

https://api.icareus.com/api/vast?type=vod&campaignIds=7154601&assetId=54321&organizationId=2631609&applicationId=1&applicationTypeId=1&deviceId=this-is-just-an-example

Second campaign

  1. {
  2.   "adProfile": {
  3.     "displayInterval": 60,
  4.     "profileType": 2,
  5.     "skipOffset": 5
  6.   },
  7.   "adProfileId": 10732501,
  8.   "campaignId": 10796301,
  9.   "campaignName": "In stream midroll",
  10.   "channels": [],
  11.   "contentType": 1,
  12.   "endTime": "2023-03-28T05:00:00Z",
  13.   "startTime": "2023-03-21T05:00:00Z",
  14.   "type": "instreamvideo"
  15. }

Make sure to note that the profileType of the adProfile of this Campaign is 2, which means that it is a midroll ad.

Also make sure to note that the displayInterval of this adProfile is 60 (seconds).

VAST URL for this campaign will look like this when we assume that the Suite Organization ID is 2631609 and the Suite asset ID is 54321: 

https://api.icareus.com/api/vast?type=vod&campaignIds=10796301&assetId=54321&organizationId=2631609&applicationId=1&applicationTypeId=1&deviceId=this-is-just-an-example

Third campaign

  1. {
  2.   "adProfile": {
  3.     "profileType": 3,
  4.     "skipOffset": 10
  5.   },
  6.   "adProfileId": 10127701,
  7.   "campaignId": 10998001,
  8.   "campaignName": "in stream postroll",
  9.   "channels": [],
  10.   "contentType": 1,
  11.   "endTime": "2023-03-31T00:00:00Z",
  12.   "startTime": "2023-03-24T00:00:00Z",
  13.   "type": "instreamvideo"
  14. }

Make sure to note that the profileType of the adProfile of this Campaign is 3, which means that it is a postroll ad.

VAST URL for this campaign will look like this when we assume that the Suite Organization ID is 2631609 and the Suite asset ID is 54321: 

https://api.icareus.com/api/vast?type=vod&campaignIds=10796301&assetId=54321&organizationId=2631609&applicationId=1&applicationTypeId=1&deviceId=this-is-just-an-example

Once you have generated the VAST URL for all the campaigns for which one needs to be generated, it is time to configure the AD SCHEDULE for Radiant Media Player.

Documentation for ad scheduling for Radiant Media Player can be found here: https://www.radiantmediaplayer.com/docs/latest/custom-ad-scheduling.html

You now have 3 different VAST URLS generated:

  1. // The three different VAST URLs generated from the 3 campaigns returned by the campaign API
  2. const VAST_PREROLL  = "https://api.icareus.com/api/vast?type=vod&campaignIds=7154601&assetId=54321&organizationId=2631609&applicationId=1&applicationTypeId=1&deviceId=this-is-just-an-example";
  3. const VAST_MIDROLL  = "https://api.icareus.com/api/vast?type=vod&campaignIds=10796301&assetId=54321&organizationId=2631609&applicationId=1&applicationTypeId=1&deviceId=this-is-just-an-example";
  4. const VAST_POSTROLL = "https://api.icareus.com/api/vast?type=vod&campaignIds=10796301&assetId=54321&organizationId=2631609&applicationId=1&applicationTypeId=1&deviceId=this-is-just-an-example";
  5. // The displayInterval value from the campaign that contained an ad where profileType was 2 (midroll)
  6. const MIDROLL_DISPLAY_INTERVAL = 60;
  7. // Define the ad schedule
  8. const SCHEDULE = {
  9.     preroll: VAST_PREROLL,
  10.     midrollRepeat: [MIDROLL_DISPLAY_INTERVAL, VAST_MIDROLL],
  11.     postroll: VAST_POSTROLL
  12. };
  13. // Finally add the ad schedule to the Radiant Media Player settings object:
  14. const settings = {
  15.     licenseKey: 'rmp-license-key',
  16.     // other rmp settings...
  17.     ads: true,
  18.     adSchedule: SCHEDULE
  19. };
  20. // Initialize the player:
  21. rmp.init( settings );
inVideoOverlay

Campaigns of type inVideoOverlay contain overlay ad profiles, meaning ads that display an image banner instead of video ads.

These campaigns only include an adProfileId:

  1. {
  2.   "adProfileId": 7154101,
  3.   "campaignId": 7154701,
  4.   "campaignName": "Overlay 1",
  5.   "channels": [
  6.     {
  7.       "id": 2633044,
  8.       "name": "Tapahtumakanava"
  9.     }
  10.   ],
  11.   "contentType": 1,
  12.   "endTime": "2023-03-24T03:00:00Z",
  13.   "startTime": "2023-02-16T03:00:00Z",
  14.   "type": "invideooverlay"
  15. }

Generate a VAST URL using the adProfileId and set up the ad in the player as a preroll ad


    • Related Articles

    • Managing the In-Stream Video Ads

      Introduction to In-Stream Video Ads In-stream video ads are: Pre-roll Mid-roll Post-roll Those can be configured to be used with both live and on-demand content on different Icareus Suite video players: Live video player VOD (video-on-demand) player ...

    • Campaign API (ENG)

      Introduction This API is used to manage Campaigns. You can create new Campaigns, edit existing Campaigns and create/edit Schedules for Campaigns. You can also get information about Campaigns. API PATH /api/campaign API CALLS Add/Edit Campaign Creates ...

    • Introduction to Addressable TV

      INTRODUCTION Icareus Suite enables broadcasters to maximise their revenue with Addressable TV formats. Icareus Suite in collaboration with Icareus Playout can be used to trigger and synchronise Display Ads and replace the broadcasted commercials with ...

    • Online Display Campaigns

      Online Display Campaign Introduction Online Display Campaigns are Campaigns that are meant to be used in order to display an overlay (image) on the target platform (web, mobile or smarttv). Each Online Display Campaign specifies its target platform ...

    • VideoSwap Format and Configuration

      Introduction VideoSwap format is Icareus' solution for Dynamic Ad insertion or substitution (DAS). It enables substitution of linear TV spots or pods with more personalised video ads. Supported platforms HbbTV OTT Browser based set-top box ...