IMA SDK ช่วยให้การผสานรวมโฆษณามัลติมีเดียในเว็บไซต์และแอปของคุณทำได้โดยง่าย IMA SDK สามารถ ส่งคำขอโฆษณาจาก เซิร์ฟเวอร์โฆษณาที่ปฏิบัติตามข้อกำหนดของ VAST และจัดการการเล่นโฆษณาในแอปของคุณ ด้วย IMA DAI SDK แอปจะสร้าง คำขอสตรีมสำหรับโฆษณาและวิดีโอเนื้อหา ไม่ว่าจะเป็น VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงผลลัพธ์ สตรีมวิดีโอแบบรวม คุณจึงไม่ต้องคอยจัดการสลับเปลี่ยนระหว่างโฆษณากับเนื้อหาวิดีโอ ภายในแอป
เลือกโซลูชัน DAI ที่คุณสนใจ
DAI ที่แสดงในพ็อด
คู่มือนี้แสดงวิธีเล่นสตรีมการแสดงพ็อด DAI สำหรับการถ่ายทอดสดหรือ VOD เนื้อหา โดยใช้ IMA DAI SDK สำหรับ HTML5 กับโปรแกรมเล่นวิดีโอที่ใช้ hls.js สำหรับการเล่น หากคุณต้องการดูหรือติดตามไปพร้อมกับตัวอย่างที่สมบูรณ์ ด้วยการรองรับทั้ง HLS.js และ Safari Playback ตัวอย่างการแสดงพ็อด HLS สำหรับการรองรับ DASH.js โปรดดูตัวอย่างการแสดงพ็อด DASH คุณดาวน์โหลดแอปตัวอย่างเหล่านี้ได้จากรุ่น HTML5 DAI GitHub
ภาพรวมการแสดงพ็อด DAI
การใช้การแสดงพ็อดโดยใช้ IMA DAI SDK มีส่วนประกอบหลัก 2 ส่วน ได้แก่ ดังที่ระบุไว้ในคู่มือนี้
PodStreamRequest
/PodVodStreamRequest
: ออบเจ็กต์ที่กำหนดคำขอสตรีมให้กับ เซิร์ฟเวอร์โฆษณาของ Google คำขอจะระบุรหัสเครือข่าย และPodStreamRequest
ยังต้องใช้คีย์เนื้อหาที่กำหนดเอง รวมทั้งตัวเลือก คีย์ API พารามิเตอร์ทั้ง 2 รายการมีพารามิเตอร์ที่ไม่บังคับอื่นๆStreamManager
: ออบเจ็กต์ที่จัดการการสื่อสารระหว่าง สตรีมวิดีโอและ IMA DAI SDK เช่น การเริ่มใช้คำสั่ง ping การติดตาม การส่งต่อเหตุการณ์สตรีมไปยังผู้เผยแพร่โฆษณา
ข้อกำหนดเบื้องต้น
ก่อนที่จะเริ่มต้น คุณต้องมีสิ่งต่อไปนี้
ไฟล์ว่าง 3 ไฟล์:
- dai.html
- dai.css
- dai.js
Python ที่ติดตั้งในคอมพิวเตอร์ของคุณ หรือเว็บเซิร์ฟเวอร์ หรือการพัฒนาที่โฮสต์อื่นๆ สภาพแวดล้อมที่จะใช้สำหรับการทดสอบ
กำหนดค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์
เนื่องจาก SDK โหลดทรัพยากร Dependency โดยใช้โปรโตคอลเดียวกับหน้าเว็บจาก คุณจำเป็นต้องใช้เว็บเซิร์ฟเวอร์เพื่อทดสอบแอปของคุณ ด่วน วิธีเริ่มต้นเซิร์ฟเวอร์การพัฒนาภายในคือการใช้เซิร์ฟเวอร์ในตัวของ Python
ใช้บรรทัดคำสั่งจากไดเรกทอรีที่มี
index.html
ของคุณ เรียกใช้:python -m http.server 8000
ไปที่
http://localhost:8000/
ในเว็บเบราว์เซอร์นอกจากนี้ คุณยังสามารถใช้สภาพแวดล้อมในการพัฒนาซอฟต์แวร์หรือเว็บเซิร์ฟเวอร์อื่นๆ ที่โฮสต์ไว้ เป็นเซิร์ฟเวอร์ Apache HTTP
สร้างวิดีโอเพลเยอร์ง่ายๆ
ขั้นแรก ให้แก้ไข dai.html เพื่อสร้างเอลิเมนต์วิดีโอ HTML5 อย่างง่ายและ div สำหรับ
ใช้สำหรับองค์ประกอบ UI โฆษณา และเพิ่มแท็กที่จําเป็นเพื่อโหลด dai.css
และ dai.js รวมทั้งนำเข้าโปรแกรมเล่นวิดีโอ hls.js
จากนั้นแก้ไข dai.css เพื่อระบุขนาดและตำแหน่งขององค์ประกอบหน้า
สุดท้ายใน dai.js ให้กำหนดตัวแปรเพื่อเก็บข้อมูลคำขอสตรีม
และฟังก์ชัน initPlayer()
ที่จะเรียกใช้เมื่อโหลดหน้าเว็บ
ค่าคงที่คำขอสตรีมมีดังนี้
BACKUP_STREAM
: URL สำหรับสตรีมสำรองที่เล่นในกรณีที่กระบวนการโฆษณา พบข้อผิดพลาดร้ายแรงSTREAM_URL
: ใช้สำหรับสตรีมแบบสดเท่านั้น URL ของสตรีมวิดีโอระบุโดย เครื่องมือจัดการไฟล์ Manifest หรือพาร์ทเนอร์บุคคลที่สามที่ใช้การแสดงพ็อด ควร คุณต้องแทรกรหัสสตรีมที่ได้รับจาก IMA DAI SDK ก่อน ส่งคำขอ ในกรณีนี้ URL ของสตรีมจะมีตัวยึดตำแหน่ง[[STREAMID]]
ซึ่งแทนที่ด้วยรหัสสตรีมก่อนส่งคำขอNETWORK_CODE
: รหัสเครือข่ายสำหรับบัญชี Ad Manager 360CUSTOM_ASSET_KEY
: ใช้สำหรับสตรีมแบบสดเท่านั้น คีย์เนื้อหาที่กำหนดเองที่ ระบุเหตุการณ์การแสดงพ็อดใน Ad Manager 360 แพลตฟอร์มนี้สามารถสร้างขึ้นได้โดย เครื่องมือจัดการไฟล์ Manifest หรือพาร์ทเนอร์ที่ให้บริการพ็อดบุคคลที่สามAPI_KEY
: ใช้สำหรับสตรีมแบบสดเท่านั้น คีย์ API ที่ไม่บังคับซึ่งสามารถ เพื่อเรียกข้อมูลรหัสสตรีมจาก IMA DAI SDK
dai.html
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script src="dai.js"></script>
<link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
<h2>IMA DAI SDK Demo (HLS.JS)</h2>
<video id="video"></video>
<div id="ad-ui"></div>
</body>
</html>
dai.css
#video,
#ad-ui {
width: 640px;
height: 360px;
position: absolute;
top: 35px;
left: 0;
}
#ad-ui {
cursor: pointer;
}
dai.js
var BACKUP_STREAM =
'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'
// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";
var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
}
โหลด IMA DAI SDK
ถัดไป ให้เพิ่มเฟรมเวิร์ก DAI โดยใช้แท็กสคริปต์ใน dai.html ก่อนแท็ก สำหรับ dai.js
dai.html
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
<script src="dai.js"></script>
<link rel="stylesheet" href="dai.css" type="text/css">
</head>
...
เริ่มต้น StreamManager และส่งคำขอสตรีมถ่ายทอดสดหรือ VOD
การแสดงพ็อดสตรีมแบบสด
หากต้องการขอชุดโฆษณา ให้สร้าง ima.dai.api.StreamManager
มีหน้าที่ในการขอและจัดการสตรีม DAI เครื่องมือสร้างใช้เวลา
องค์ประกอบวิดีโอและอินสแตนซ์ที่ได้จะนำองค์ประกอบ UI โฆษณามาจัดการกับโฆษณา
การโต้ตอบ
จากนั้นกำหนดฟังก์ชันเพื่อขอให้พ็อดที่แสดงสตรีมแบบสด ฟังก์ชันนี้
สร้าง PodStreamRequest
ก่อน จากนั้นกำหนดค่าด้วย StreamRequest
พารามิเตอร์ที่ให้ไว้ในขั้นตอนที่ 2 แล้วจึงเรียกใช้ streamManager.requestStream()
ด้วยออบเจ็กต์คำขอนั้น
dai.js
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)
requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}
function requestLivePodStream(networkCode, customAssetKey, apiKey) {
// clear HLS.js instance, if in use
if (hls) {
hls.destroy();
}
// Generate a Pod Serving live Stream Request
const streamRequest = new google.ima.dai.api.PodStreamRequest();
streamRequest.networkCode = networkCode;
streamRequest.customAssetKey = customAssetKey;
streamRequest.apiKey = apiKey;
streamRequest.format = 'hls';
streamManager.requestStream(streamRequest);
}
การแสดงพ็อด VOD
หากต้องการขอชุดโฆษณา ให้สร้าง ima.dai.api.StreamManager
มีหน้าที่ในการขอและจัดการสตรีม DAI เครื่องมือสร้างใช้เวลา
องค์ประกอบวิดีโอและอินสแตนซ์ที่ได้จะนำองค์ประกอบ UI โฆษณามาจัดการกับโฆษณา
การโต้ตอบ
จากนั้นกำหนดฟังก์ชันเพื่อขอพ็อดที่แสดงสตรีม VOD ฟังก์ชันนี้
สร้าง PodVodStreamRequest
ก่อน จากนั้นกำหนดค่าด้วย StreamRequest
พารามิเตอร์ที่ให้ไว้ในขั้นตอนที่ 2 แล้วจึงเรียกใช้ streamManager.requestStream()
ด้วยออบเจ็กต์คำขอนั้น
dai.js
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)
requestVodPodStream(NETWORK_CODE);
}
function requestVodPodStream(networkCode) {
// clear HLS.js instance, if in use
if (hls) {
hls.destroy();
}
// Generate a Pod Serving VOD Stream Request
const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
streamRequest.networkCode = networkCode;
streamRequest.format = 'hls';
streamManager.requestStream(streamRequest);
}
จัดการเหตุการณ์สตรีม
การแสดงพ็อดสตรีมแบบสด
ถัดไป ให้ใช้ Listener เหตุการณ์สำหรับเหตุการณ์วิดีโอที่สำคัญ ตัวอย่างนี้จัดการกับ
STREAM_INITIALIZED
ERROR
AD_BREAK_STARTED
และAD_BREAK_ENDED
โดยเรียกใช้ฟังก์ชัน onStreamEvent()
ฟังก์ชันนี้จัดการสตรีม
การโหลดและข้อผิดพลาด ตลอดจนการปิดการใช้งานตัวควบคุมวิดีโอเพลเยอร์ขณะที่โฆษณา
ซึ่ง SDK จำเป็นต้องใช้ เมื่อสตรีมโหลดแล้ว วิดีโอ
โปรแกรมเล่นจะโหลดและเล่น URL ที่ระบุโดยใช้ฟังก์ชัน loadStream()
dai.js
var isAdBreak;
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
streamManager.addEventListener(
[google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
google.ima.dai.api.StreamEvent.Type.ERROR,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
onStreamEvent,
false);
...
function onStreamEvent(e) {
switch (e.type) {
case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
console.log('Stream initialized');
loadStream(e.getStreamData().streamId);
break;
case google.ima.dai.api.StreamEvent.Type.ERROR:
console.log('Error loading stream, playing backup stream.' + e);
loadStream('');
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
console.log('Ad Break Started');
isAdBreak = true;
videoElement.controls = false;
adUiElement.style.display = 'block';
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
console.log('Ad Break Ended');
isAdBreak = false;
videoElement.controls = true;
adUiElement.style.display = 'none';
break;
default:
break;
}
}
function loadStream(streamID) {
var url;
if(streamID) {
url = STREAM_URL.replace('[[STREAMID]]', streamID);
} else {
console.log('Stream Initialization Failed');
url = BACKUP_STREAM;
}
console.log('Loading:' + url);
hls.loadSource(url);
hls.attachMedia(videoElement);
}
การแสดงพ็อด VOD
ถัดไป ให้ใช้ Listener เหตุการณ์สำหรับเหตุการณ์วิดีโอที่สำคัญ ตัวอย่างนี้จัดการ
STREAM_INITIALIZED
, LOADED
, ERROR
, AD_BREAK_STARTED
และ
AD_BREAK_ENDED
เหตุการณ์โดยเรียกใช้ฟังก์ชัน onStreamEvent()
ช่วงเวลานี้
จะช่วยจัดการการโหลดสตรีมและข้อผิดพลาด รวมถึงการปิดใช้โปรแกรมเล่น
ควบคุมขณะที่โฆษณากำลังเล่น ซึ่ง SDK กําหนด
นอกจากนี้ สตรีมที่แสดงพ็อด VOD ต้องมีการเรียกใช้
StreamManager.loadStreamMetadata()
เพื่อตอบสนองต่อ
STREAM_INITIALIZED
เหตุการณ์ นอกจากนี้คุณต้องขอ URL ของสตรีมจาก
พาร์ทเนอร์เทคโนโลยีวิดีโอ (VTP) เมื่อโทรหา loadStreamMetadata()
สำเร็จแล้ว
ทริกเกอร์เหตุการณ์ LOADED
ซึ่งควรเรียกฟังก์ชัน loadStream()
กับ URL ของสตรีมเพื่อโหลดและเล่นสตรีม
var isAdBreak;
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
streamManager.addEventListener(
[google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
google.ima.dai.api.StreamEvent.Type.ERROR,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
onStreamEvent,
false);
...
function onStreamEvent(e) {
switch (e.type) {
case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
const streamId = e.getStreamData().streamId;
// 'vtpInterface' is a place holder for your own video technology
// partner (VTP) API calls.
vtpInterface.requestStreamURL({
'streamId': streamId,
})
.then( (vtpStreamUrl) => {
streamUrl = vtpStreamUrl;
streamManager.loadStreamMetadata();
}, (error) => {
// Handle the error.
});
break;
case google.ima.dai.api.StreamEvent.Type.LOADED:
loadStream(streamUrl);
break;
case google.ima.dai.api.StreamEvent.Type.ERROR:
console.log('Error loading stream, playing backup stream.' + e);
loadStream();
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
console.log('Ad Break Started');
isAdBreak = true;
videoElement.controls = false;
adUiElement.style.display = 'block';
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
console.log('Ad Break Ended');
isAdBreak = false;
videoElement.controls = true;
adUiElement.style.display = 'none';
break;
default:
break;
}
}
function loadStream(url) {
if(url) {
console.log('Loading:' + url);
hls.loadSource(url);
} else {
console.log('Stream Initialization Failed');
hls.loadSource(BACKUP_STREAM);
}
hls.attachMedia(videoElement);
}
จัดการข้อมูลเมตาของสตรีม
ในขั้นตอนนี้ คุณจะใช้ Listener เหตุการณ์สำหรับข้อมูลเมตาเพื่อแจ้ง SDK เมื่อ ที่มีโฆษณาเกิดขึ้น การรอเหตุการณ์ข้อมูลเมตาในสตรีมอาจแตกต่างกันไป โดยขึ้นอยู่กับ รูปแบบสตรีม (HLS หรือ DASH), ประเภทสตรีม (สตรีมสดหรือ VOD) ประเภทโปรแกรมเล่น และประเภทของแบ็กเอนด์ DAI ที่ใช้ ดูกำหนดเวลา ข้อมูลเมตา เพื่อดูข้อมูลเพิ่มเติม
รูปแบบสตรีม HLS (สตรีมสดและ VOD, โปรแกรมเล่น HLS.js)
หากคุณใช้โปรแกรมเล่น HLS.js โปรดฟัง
เหตุการณ์ FRAG_PARSING_METADATA
ของ HLS.js เพื่อรับข้อมูลเมตา ID3 และส่งไปยัง
SDK กับ StreamManager.processMetadata()
หากต้องการเล่นวิดีโอโดยอัตโนมัติหลังจากทุกอย่างโหลดและพร้อมแล้ว โปรดฟัง
เหตุการณ์ MANIFEST_PARSED
ของ HLS.js เพื่อทริกเกอร์การเล่น
function loadStream(streamID) {
hls.loadSource(url);
hls.attachMedia(videoElement);
// Timed metadata is passed HLS stream events to the streamManager.
hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}
function parseID3Events(event, data) {
if (streamManager && data) {
// For each ID3 tag in the metadata, pass in the type - ID3, the
// tag data (a byte array), and the presentation timestamp (PTS).
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
}
function startPlayback() {
console.log('Video Play');
videoElement.play();
}
DASH.js (รูปแบบสตรีม DASH, ประเภทสตรีมสดและ VOD)
หากคุณใช้โปรแกรมเล่น DASH.js คุณต้องใช้สตริงที่แตกต่างกันเพื่อฟังข้อมูลเมตา ID3 สำหรับการถ่ายทอดสดหรือ VOD สตรีม:
- สตรีมแบบสด:
'https://developer.apple.com/streaming/emsg-id3'
- สตรีม VOD:
'urn:google:dai:2018'
ส่งข้อมูลเมตา ID3 ไปยัง SDK ด้วย StreamManager.processMetadata()
หากต้องการแสดงตัวควบคุมวิดีโอโดยอัตโนมัติหลังจากโหลดทุกอย่างพร้อมแล้ว
ฟังเหตุการณ์ MANIFEST_LOADED
ของ DASH.js
const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
function processMetadata(metadataEvent) {
const messageData = metadataEvent.event.messageData;
const timestamp = metadataEvent.event.calculatedPresentationTime;
// Use StreamManager.processMetadata() if your video player provides raw
// ID3 tags, as with dash.js.
streamManager.processMetadata('ID3', messageData, timestamp);
}
function loadlistener() {
showControls();
// This listener must be removed, otherwise it triggers as addional
// manifests are loaded. The manifest is loaded once for the content,
// but additional manifests are loaded for upcoming ad breaks.
dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}
Shaka Player ที่มีสตรีมแบบสด (รูปแบบสตรีม DASH)
หากคุณใช้ Shaka Player สำหรับ
การเล่นสตรีมแบบสด ให้ใช้สตริง 'emsg'
เพื่อฟังเหตุการณ์ข้อมูลเมตา
จากนั้นจึงใช้ข้อมูลข้อความเหตุการณ์ในการโทรไปยัง StreamManager.onTimedMetadata()
shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));
function onEmsgEvent(metadataEvent) {
// Use StreamManager.onTimedMetadata() if your video player provides
// processed metadata, as with Shaka player livestreams.
streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}
Shaka Player ที่มีสตรีม VOD (รูปแบบสตรีม DASH)
หากคุณใช้ Shaka Player สำหรับ
การเล่นสตรีม VOD ให้ใช้สตริง 'timelineregionenter'
เพื่อฟัง
เหตุการณ์ข้อมูลเมตา จากนั้นใช้ข้อมูลข้อความเหตุการณ์ในการโทรเพื่อ
StreamManager.processMetadata()
ด้วยสตริง 'urn:google:dai:2018'
shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));
function onTimelineEvent(metadataEvent) {
const detail = metadataEvent.detail;
if ( detail.eventElement.attributes &&
detail.eventElement.attributes['messageData'] &&
detail.eventElement.attributes['messageData'].value ) {
const mediaId = detail.eventElement.attributes['messageData'].value;
const pts = detail.startTime;
// Use StreamManager.processMetadata() if your video player provides raw
// ID3 tags, as with Shaka player VOD streams.
streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
}
}
จัดการเหตุการณ์ของผู้เล่น
เพิ่ม Listener เหตุการณ์ลงในเหตุการณ์ pause
และ start
ขององค์ประกอบวิดีโอเพื่ออนุญาต
ให้ผู้ใช้เล่นต่อเมื่อ SDK หยุดชั่วคราวในช่วงพักโฆษณา
function loadStream(streamUrl) {
...
videoElement.addEventListener('pause', onStreamPause);
videoElement.addEventListener('play', onStreamPlay);
}
function onStreamPause() {
console.log('paused');
if (isAdBreak) {
videoElement.controls = true;
adUiElement.style.display = 'none';
}
}
function onStreamPlay() {
console.log('played');
if (isAdBreak) {
videoElement.controls = false;
adUiElement.style.display = 'block';
}
}
เท่านี้ก็เรียบร้อย คุณกำลังขอและแสดงโฆษณาในสตรีมที่แสดงพ็อดด้วย IMA DAI SDK สำหรับ HTML5 หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับฟีเจอร์ขั้นสูงของ SDK โปรดดู ในคู่มืออื่นๆ หรือตัวอย่าง GitHub