# Client-Side Ad Insertion (CSAI)

Note

This feature is available only to ByteArk Video Cloud for Business customers. Please contact sales@byteark.com if you would like to use it.

ByteArk Player supports Client-Side Ad Insertion (CSAI), inserting ads into live-streaming sessions while viewers watch.

# Requirements

An HLS live-streaming URL with Ad Insertion enabled by ByteArk
An ad server that supports ad break duration requests

# Enable CSAI

Enable CSAI by setting plugins.bytearkCsai in options when creating the player. Configure parameters per the options table below.

{
  fluid: true,
  poster: '/assets/samples/player/images/poster-big-buck-bunny.jpg',
  sources: [{
    title: 'Live Stream',
    src: '<LIVE_STREAM_URL>',
    type: 'application/x-mpegURL'
  }],
  plugins: {
    bytearkCsai: {
      debug: true,
      adTagUrl: '<AD_SERVER_URL>',
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Options

Name	Type	Required	Description
debug	Boolean	No	Enable/disable debug mode
adTagUrl	String	Yes	Ad server URL that supports ad break duration requests
integration	String	No	Ad integration: `google-ima` or `castoola`
adTagParameters	Object	No	Key-value parameters to send to the ad server

# Example

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
  </head>
  <body>
    <div id="video-player"></div>
    <script src="https://byteark-sdk.cdn.byteark.com/player/v2/byteark-player.min.js"></script>
    <script>
      var player = bytearkPlayer('video-player', {
        fluid: true,
        sources: [{
          title: 'Live Stream',
          src: '<LIVE_STREAM_URL>',
          type: 'application/x-mpegURL'
        }],
        plugins: {
          bytearkCsai: {
            adTagUrl: '<AD_SERVER_URL>',
          }
        }
      });
    </script>
  </body>
</html>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Sending adTagParameters to Google Ad Manager

Add integration: 'google-ima' to the bytearkCsai plugin options.
Add adTagParameters with the keys and values you want to send. See the VAST ad tag URL parameters documentation (opens new window).

Note

If a key in adTagParameters matches one in the adTagUrl query string, the value from adTagParameters overrides it.

# Using macros for Google Ad Manager

{
  ...
  integration: 'google-ima',
  adTagParameters: {
    url: '[url]'
  }
}

1
2
3
4
5
6
7

Supported macros

Macro	Type	Value	Description
url	String	`[url]`	Current page URL where the video is playing

# Sending adTagParameters to Castoola

Add integration: 'castoola' to the bytearkCsai plugin options.
Add adTagParameters with the keys and values from the documentation provided by Castoola.

# Using macros for Castoola

ByteArk CSAI plugin supports macros that are substituted at runtime — for example, [operating_system] is replaced with the actual operating system before being sent to Castoola.

{
  ...
  integration: 'castoola',
  adTagParameters: {
    operating_system: '[operating_system]'
  }
}

1
2
3
4
5
6
7

Supported macros

Macro	Type	Value	Description
device_type	String	`[device_type]`	`1`=PC, `2`=Smartphone, `3`=Tablet, `4`=STB, `5`=Smart TV
dt	String	`[dt]`	Short form of `device_type`
operating_system	String	`[operating_system]`	`1`=Windows, `2`=macOS, `3`=Linux, `4`=ChromeOS, `5`=Android, `6`=iOS, `7`=Android TV, `8`=Tizen TV, `9`=WebOS, `10`=tvOS, `11`=VIDAA TV, `12`=Roku TV, `13`=Fire TV, `0`=Other
os	String	`[os]`	Short form of `operating_system`
content_id	String	`[content_id]`	From `videoId` in the Source Object
cid	String	`[cid]`	Short form of `content_id`
content_name	String	`[content_name]`	From `title` of the Source Object, or `lighthouse.video.videoTitle`
cnam	String	`[cnam]`	Short form of `content_name`
genre	String	`[genre]`	From `lighthouse.video.genres`
gnr	String	`[gnr]`	Short form of `genre`

← Advertisement HLS ClearKey →