คู่มือแนะนำการใช้งาน ByteArk

# การเล่นโฆษณา

Note

ฟีเจอร์นี้ของ ByteArk Player รองรับเฉพาะผู้ใช้ ByteArk Video Cloud for Business หากท่านต้องการใช้งานกรุณาติดต่อ sales@byteark.com

ByteArk Player รองรับการแสดงผลโฆษณาโดยใช้ Google Interactive Media Ads SDK (Google IMA SDK for HTML5) (opens new window) ซึ่งเป็นการแสดงผลโฆษณาตามมาตรฐานของ Video Ad Serving Template (VAST) (opens new window)

ByteArk Player แสดงผลโฆษณาโดยการเรียกขอโฆษณาจาก Ads Server ต่างๆ เช่น

  • Google DoubleClick for Publishers (DFP)
  • Google AdSense network
  • Ad Server ตามโฆษณาตามมาตรฐานของ VAST (VAST-compliant ad server)

# รูปแบบโฆษณาที่รองรับ

เนื่องจาก ByteArk Player แสดงผลโฆษณาโดยใช้ Google IMA SDK for HTML5 จึงสามารถตรวจสอบรูปแบบโฆษณาที่รองรับได้จากเอกสาร Support and Compatibility (opens new window) ของ Google

# การแสดงผลโฆษณา


# การเปิดใช้งานการเล่นโฆษณา

การเปิดใช้งานการเล่นโฆษณาบน ByteArk Player สามารถทำได้โดยระบุ plugins.bytearkAds ใน options เมื่อทำการสร้าง video player โดยสามารถตั้งค่าพารามิเตอร์ต่างๆ ตามตาราง options ด้านล่าง

{
  fluid: true,
  poster: '/assets/samples/player/images/poster-big-buck-bunny.jpg',
  sources: [{
    title: 'Big Buck Bunny',
    src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
    type: 'application/x-mpegURL'
  }],
  plugins: {
    bytearkAds: {
      adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# การปรับตั้งค่า options

Name Type Required Description
adTagUrl String No URL ของ VAST, VMAP หรือ VPAID
integration String No Ad integration สำหรับแสดงผลโฆษณา สามารถมีค่าเป็น google-ima หรือ castoola
adTagParameters Object No Ad parameters ที่ต้องการส่งให้ Ad Server ในรูปแบบ key-value
adsResponse String No XML String ของ VAST, VMAP หรือ VPAID
showAdMarker Boolean No แสดงตำแหน่งของโฆษณาบน control bar
ads Array No ลิสของโฆษณาที่ต้องการให้แสดง
ads[].adTagUrl String No URL ของ VAST, VMAP หรือ VPAID
ads[].adsResponse String No XML String ของ VAST, VMAP หรือ VPAID
ads[].time Number|String Yes เวลาที่ต้องการให้แสดงโฆษณา สามารถมีค่าเป็น
pre : (string) แสดงโฆษณาแบบ preroll

post : (string) แสดงโฆษณาแบบ postroll

timecode : (string) แสดงโฆษณาแบบ midroll ตามเวลาที่ตั้ง โดยสามารถระบุเป็น format HH:MM:SS

0 : (number) แสดงโฆษณาแบบ preroll

-1 : (number) แสดงโฆษณาแบบ postroll

number : (number) แสดงโฆษณาแบบ midroll ตามเวลาที่ตั้ง โดยระบุค่าเป็นวินาทีที่ต้องการให้แสดงโฆษณา เช่น 10 คือแสดง midroll เมื่อเล่นวิดีโอไปถึงวินาทีที่ 10

percent: (string) แสดงโฆษณาแบบ midroll ตามเปอร์เซ็นต์ที่ตั้ง เช่น '10%', '50%' โดยระบุค่าเป็นเปอร์เซ็นต์จากความยาวของวิดีโอ (ใช้งานได้เฉพาะ VOD เคุณั้น)
ads[].integration String No Ad integration สำหรับแสดงผลโฆษณา สามารถมีค่าเป็น google-ima หรือ castoola
ads[].adTagParameters Object No Ad parameters ที่ต้องการส่งให้ Ad Server ในรูปแบบ key-value
showControlsForJSAds Boolean No แสดงหรือซ่อนแถบควบคุม เมื่อเล่นโฆษณา VPAID แบบ Javascript (ค่าเริ่มต้นคือ true)
contribAds Object No ตั้งค่าสำหรับ videojs-contrib-ads plugin (opens new window)
googleIma Object No ตั้งค่าสำหรับ Google IMA SDK.
googleIma.imaSdkSettings Object No ตั้งค่า properties ของ Google IMA SDK ImaSdkSettings (opens new window)
googleIma.adsRenderingSettings Object No ตั้งค่า properties ของ Google IMA SDK AdRenderingSettings (opens new window)
googleIma.adsRequestSettings Object No ตั้งค่า properties ของ Google IMA SDK AdRequest (opens new window)

Note

หากมีการตั้งค่า adTagUrl พร้อมกับ adsResponse player จะเลือกค่าของ adTagUrl ใช้งาน (override) เสมอ

# Methods

Name Parameters Return Description
player.getAdBlock() - Boolean มีค่าเป็น true เมื่อ plugin ตรวจเจอว่ามีการใช้งาน AdBlock อยู่
player.playAd(adTagUrl) adTagUrl - เล่นโฆษณาจาก adTagUrl ที่ส่งเข้ามาทันที
player.playAd(adTagUrl, playAdOptions) adTagUrl, playAdOptions - เล่นโฆษณาจาก adTagUrl ที่ส่งเข้ามาทันทีโดยใช้ข้อมูลจาก playAdOptions
player.pauseAd() - - หยุดเล่นโฆษณาชั่วคราว
player.skipAd() - - ข้ามการเล่นโฆษณา
player.getAdMetadata() - Object|null Return AdMetada object ของโฆษณาที่กำลังเล่น หรือ null

# PlayAdOptions Object

Name Type Required Description
integration String No Ad integration สำหรับแสดงผลโฆษณา สามารถมีค่าเป็น google-ima หรือ castoola
adTagParameters Object No Ad parameters ที่ต้องการส่งให้ Ad Server ในรูปแบบ key-value

# Events

Name Payload Description
ads-block - เกิดเมื่อมีการเปิดใช้งาน adBlock อยู่
ads-loader google.ima.AdsLoader (opens new window) เกิดเมื่อ AdsLoader initialized
ads-request google.ima.AdsRequest (opens new window) เกิดเมื่อมีการรีเควส AdsRequest
ads-manager google.ima.AdsManager (opens new window) เกิดเมื่อโหลด AdsManager เสร็จ
ads-load - เกิดเมื่อมีข้อมูลของโฆษณาหลังจากมีการรีเควสโฆษณา (ad request)
ads-error { code: '1000', errorDetailCode: '13000000', fullErrorCode: '1000-13000000', message: 'error message' } เกิดเมื่อมี ad error เกิดขึ้น
ads-click - เกิดเมื่อมีการคลิกบนโฆษณา
ads-impression - เกิดเมื่อโฆษณาถูกนับ impression.
ads-play - เกิดเมื่อมีการกลับมาเล่นโฆษณาอีกครั้งหลังจากหยุดเล่นชั่วคราว
ads-pause - เกิดเมื่อมีการหยุดเล่นโฆษณาชั่วคราว
ads-ad-started - เกิดเมื่อโฆษณาเริ่มเล่น
ads-first-quartile - เกิดเมื่อมีการเล่นโฆษณาเกิด 1 ใน 4 ของความยาวโฆษณา (crosses first quartile)
ads-midpoint - เกิดเมื่อมีการเล่นโฆษณาเกินครึ่งนึงของความยาวโฆษณา (crosses midpoint)
ads-third-quartile - เกิดเมื่อมีการเล่นโฆษณาเกิน 3 ใน 4 ของความยาวโฆษณา (crosses third quartile)
ads-ad-ended - เกิดเมื่อมีการเล่นโฆษณาจนจบ
ads-allpods-completed - เกิดเมื่อมีการเล่นโฆษณาแบบ LINEAR ads จบหมด
ads-skipped - เกิดเมื่อมีการกดข้ามโฆษณา (Skip Ad)
ads-mute - เกิดเมื่อมีการปิดเสียงโฆษณา

# ตัวอย่างซอร์สโค้ด

<!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,
        poster: '/assets/samples/player/images/poster-big-buck-bunny.jpg',
        sources: [{
          title: 'Big Buck Bunny',
          src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
          type: 'application/x-mpegURL'
        }],
        plugins: {
          bytearkAds: {
            ads: [{
              adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
              time: 'pre'
            }, {
              adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
              time: 10
            }]
          }
        }
      });
    </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
26
27
28
29
30
31
32

# การปรับตั้งค่า adTagParameters สำหรับส่งข้อมูลให้ Google Ad Manager

การตั้งค่าเพื่อส่งข้อมูล adTagParameters ให้กับ Google Ad Manager สามารถทำได้โดย

  1. เพิ่ม integration: 'google-ima' เข้าไปใน options ของ bytearkAds plugin
  2. เพิ่ม key adTagParameters เข้าไปใน options ของ bytearkAds plugin ข้อมูล key และ value ทั้งหมดที่สามารถใช้งานได้สามารถดูเพิ่มเติมได้ที่ เอกสาร VAST ad tag URL parameters ของ Google Ad Manager (opens new window)

Note

หากชื่อ key ที่ใส่ใน adTagParameters ซ้ำกับ key ใน query string ที่อยู่ใน adTagUrl ค่า key ที่อยู่ใน adTagUrl จะถูกแทนที่ด้วยค่าใน adTagParameters

# การใช้งาน Macros สำหรับส่งข้อมูลให้ Google Ad Manager

ByteArk Ads plugin รองรับการใช้งาน macro โดย player จะทำการแทนค่าให้หากมีการใส่ macro นั้นมา เช่น macro [url] player จะทำการแทนค่า [url] โดยใช้ url ของหน้าเว็บปัจจุบันที่มีการเล่นวิดีโออยู่ และส่งค่าให้ Google Ad Manager

{
  ...
  integration: 'google-ima',
  adTagParameters: {
    url: '[url]'
  }
}
1
2
3
4
5
6
7

รายชื่อ Macro ที่รองรับ

Macro Name Type Value Description
url String [url] url ของหน้าเว็บปัจจุบันที่มีการเล่นวิดีโออยู่

# ตัวอย่างซอร์สโค้ด

<!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,
        poster: '/assets/samples/player/images/poster-big-buck-bunny.jpg',
        sources: [{
          title: 'Big Buck Bunny',
          src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
          type: 'application/x-mpegURL'
        }],
        plugins: {
          bytearkAds: {
            adTagUrl: 'AD_SERVER_URL',
            integration: 'google-ima',
            adTagParameters: {
              url: '[url]'
              ppsj: {
                PublisherProvidedTaxonomySignals: [{
                  taxonomy: 'IAB_AUDIENCE_1_1',
                  values: [ '1', '284' ]
                }]
              },
              cust_params: {
                section: 'blog',
                anotherKey: [ 'value1', 'value2' ]
              }
            }
          }
        }
      });
    </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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# การปรับตั้งค่า adTagParameters สำหรับส่งข้อมูลให้ Castoola

การตั้งค่าเพื่อส่งข้อมูล adTagParameters ให้กับ Castoola Ad Server สามารถทำได้โดย

  1. เพิ่ม integration: 'castoola' เข้าไปใน options ของ bytearkAds plugin
  2. เพิ่ม key adTagParameters เข้าไปใน options ของ bytearkAds plugin ข้อมูล key และ value ทั้งหมดที่สามารถใช้งานได้สามารถดูเพิ่มเติมได้จากเอกสารที่ได้รับจากทาง Castoola

Note

หากชื่อ key ที่ใส่ใน adTagParameters ซ้ำกับ key ใน query string ที่อยู่ใน adTagUrl ค่า key ที่อยู่ใน adTagUrl จะถูกแทนที่ด้วยค่าใน adTagParameters

# การใช้งาน Macros สำหรับส่งข้อมูลให้ Castoola

ByteArk Ads plugin รองรับการใช้งาน macro โดย player จะทำการแทนค่าให้หากมีการใส่ macro นั้นมา เช่น macro [operating_system] player จะทำการแทนค่า [operating_system] โดย player จะทำการ detect ว่าปัจจุบันทำการเล่นวิดีโออยู่บน Operating System ใดอยู่ และส่งค่าให้ Castoola Ad Server

{
  ...
  integration: 'castoola',
  adTagParameters: {
    operating_system: '[operating_system]'
  }
}
1
2
3
4
5
6
7

รายชื่อ Macro ที่รองรับ

Macro Name Type Value Description
device_type String [device_type] player จะ detect ว่าเล่นวิดิโออยู่บน device ประเภทใดอยู่ สามารถมีค่าเป็น

- 1 is PC
- 2 is Smartphone
- 3 is Tablet
- 4 is STB
- 5 is Smart TV
dt String [dt] ตัวย่อของ device_type
operating_system String [operating_system] player จะ detect ว่าเล่นวิดีโออยู่บน operating system ในอยู่ สามารถมีค่าเป็น

- 1 is Windows
- 2 is MacOS
- 3 is Linux
- 4 is ChromeOS
- 5 is Android
- 6 is iOS
- 7 is Android TV
- 8 is Tizen TV
- 9 is WebOS
- 10 is tvOS
- 11 is VIDAA TV
- 12 is Roku TV
- 13 is Fire TV
- 0 is Other
os String [os] ตัวย่อยอง operating_system
content_id String [content_id] ค่าของ content_id โดย player จะใช้ค่าจาก videoId ของ Source Object
cid String [cid] ตัวย่อของ content_id
content_name String [content_name] ค่าของ content_name โดย player จะใช้ค่าจาก

- title ของ Source Object (หากมีการตั้งค่าไว้)
- videoTitle ของ lighthouse.video.videoTitle (หากมีการตั้งค่าไว้)
cnam String [cnam] ตัวย่อของ content_name
genre String [genre] ค่าของ genre โดย player จะใช้ค่าจาก lighthouse.video.genres (หากมีการตั้งค่าไว้)
gnr String [gnr] ตัวย่อของ genre

# ตัวอย่างซอร์สโค้ด

<!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,
        poster: '/assets/samples/player/images/poster-big-buck-bunny.jpg',
        sources: [{
          title: 'Big Buck Bunny',
          src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
          type: 'application/x-mpegURL'
        }],
        plugins: {
          bytearkAds: {
            adTagUrl: 'AD_SERVER_URL',
            integration: 'castoola',
            adTagParameters: {
              content_type: 'l',
              device_id: 'SOME_DEVICE_ID',
              device_type: '[device_type]',
              operating_system: '[operating_system]',
              publisher_id: 'SOME_PUBLISHER_ID'
            }
          }
        }
      });
    </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
26
27
28
29
30
31
32
33
34

← Context Menu →

Pricing Contact Terms of Service