IMA SDK ช่วยให้การผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปเป็นเรื่องง่าย
IMA SDK สามารถขอโฆษณาจากเซิร์ฟเวอร์โฆษณาที่เป็นไปตามข้อกำหนด VAST และจัดการการเล่นโฆษณาในแอปของคุณได้
เมื่อใช้ IMA DAI SDK แอปจะส่งคำขอสตรีมสำหรับโฆษณาและวิดีโอเนื้อหาสำหรับเนื้อหา VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงสตรีมวิดีโอแบบรวม เพื่อให้คุณไม่ต้องจัดการการสลับระหว่างโฆษณากับวิดีโอเนื้อหาภายในแอป
คู่มือนี้แสดงวิธีเล่นสตรีม DAI Pod Serving โดยใช้ IMA DAI SDK สำหรับ CAF
ก่อนใช้คู่มือนี้ โปรดทำความคุ้นเคยกับโปรโตคอล Web Receiver ของ Chromecast Application Framework คู่มือนี้ถือว่าคุณมีความเข้าใจพื้นฐานเกี่ยวกับแนวคิดของตัวรับ CAF เช่น ออบเจ็กต์ message interceptors และ mediaInformation รวมถึงมีความคุ้นเคยกับการใช้เครื่องมือคำสั่งและการควบคุมของ Cast เพื่อจำลองตัวส่ง CAF
หากต้องการใช้ IMA DAI Pod Serving คุณต้องทำงานร่วมกับพาร์ทเนอร์ Pod Serving และต้องมีบัญชี Ad Manager 360 Advanced หากคุณมีบัญชี Ad Manager โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าเพื่อขอรายละเอียดเพิ่มเติม ดูข้อมูลเกี่ยวกับการลงชื่อสมัครใช้ Ad Manager ได้ที่ศูนย์ช่วยเหลือของ Ad Manager
ดูข้อมูลเกี่ยวกับการผสานรวมกับแพลตฟอร์มอื่นๆ หรือการใช้ SDK ฝั่งไคลเอ็นต์ของ IMA ได้ที่ SDK โฆษณาสื่ออินเทอร์แอกทีฟ
ภาพรวมของ IMA DAI Pod Serving
การใช้ Pod Serving โดยใช้ IMA CAF DAI SDK ประกอบด้วยองค์ประกอบหลัก 2 อย่าง ซึ่งจะแสดงในคู่มือนี้
StreamRequest: ออบเจ็กต์ที่กำหนดคำขอสตรีมไปยังเซิร์ฟเวอร์โฆษณาของ Google คำขอจะระบุรหัสเครือข่าย คีย์เนื้อหาที่กำหนดเอง และคีย์ API (ไม่บังคับ) รวมถึงพารามิเตอร์อื่นๆ (ไม่บังคับ)StreamManager: ออบเจ็กต์ที่จัดการการสื่อสารระหว่างสตรีมวิดีโอกับ IMA DAI SDK เช่น การเริ่มใช้คำสั่ง ping เพื่อติดตามและการส่งต่อเหตุการณ์สตรีมไปยังผู้เผยแพร่โฆษณา
ข้อกำหนดเบื้องต้น
- บัญชี Cast Developer Console ที่มีอุปกรณ์ทดสอบที่ลงทะเบียนไว้
- แอป Web Receiver ที่โฮสต์ซึ่งลงทะเบียนกับ Cast Developer Console และสามารถแก้ไขเพื่อโฮสต์โค้ดที่ระบุไว้ในคู่มือนี้
- แอปผู้ส่งที่กำหนดค่าให้ใช้แอป Web Receiver สำหรับวัตถุประสงค์ของตัวอย่างนี้ ให้ใช้เครื่องมือคำสั่งและการควบคุมของ Cast เป็นผู้ส่ง
กำหนดค่าออบเจ็กต์ MediaInfo ของผู้ส่ง
ก่อนอื่น ให้กำหนดค่าออบเจ็กต์ MediaInfo ของแอปผู้ส่งให้มีช่องต่อไปนี้
| ช่อง | เนื้อหา | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
ตัวระบุที่ไม่ซ้ำกันสำหรับรายการสื่อนี้
CONTENT_ID |
||||||||||
contentUrl
|
ไม่บังคับ URL ของสตรีมสำรองที่จะเล่นหากโหลดสตรีม DAI ไม่สำเร็จ
BACKUP_STREAM_URL |
||||||||||
contentType
|
ไม่บังคับ ประเภท MIME ของสตรีมสำรองของเนื้อหา จำเป็นสำหรับสตรีม DASH เท่านั้น
CONTENT_STREAM_MIMETYPE |
||||||||||
streamType
|
สตริงลิเทอรัลหรือค่าคงที่ที่ใช้สำหรับค่านี้จะแตกต่างกันไปตามแพลตฟอร์มของผู้ส่ง | ||||||||||
customData
|
ช่อง customData มีที่เก็บคีย์-ค่าของช่องที่ต้องกรอกเพิ่มเติม ในตัวอย่างนี้ จะมีพารามิเตอร์สตรีม DAI ของคุณ ในแอปเวอร์ชันที่ใช้งานจริง คุณอาจส่งตัวระบุที่แอปตัวรับสัญญาณแคสต์จะใช้เพื่อดึงข้อมูลพารามิเตอร์เหล่านี้ด้วยคำขอฝั่งเซิร์ฟเวอร์แทน
|
ตัวอย่างโค้ดที่จะช่วยคุณเริ่มต้นใช้งานมีดังนี้
เว็บ
หากต้องการกำหนดค่าเหล่านี้ใน Web Sender ของ Cast ก่อนอื่นให้สร้างออบเจ็กต์ MediaInfo ที่มีข้อมูลที่จำเป็น จากนั้นส่งคำขอโหลดไปยัง Web Receiver
// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
daiStreamType: "DAI_STREAM_TYPE",
networkCode: "NETWORK-CODE",
customAssetKey: "CUSTOM_ASSET_KEY",
apiKey: "API_KEY"
};
// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
() => { console.log('Load succeed'); },
(errorCode) => { console.log('Error code: ' + errorCode); });
Android
หากต้องการกำหนดค่าเหล่านี้ใน Web Sender ของ Cast ก่อนอื่นให้สร้างออบเจ็กต์ MediaInfo ที่มีข้อมูลที่จำเป็น จากนั้นส่งคำขอโหลดไปยัง Web Receiver
JSONObject customData = new JSONObject()?
.put("daiStreamType", "DAI_STREAM_TYPE")
.put("networkCode", "NETWORK-CODE")
.put("customAssetKey", "CUSTOM_ASSET_KEY")
.put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
.setContentUrl("BACKUP_STREAM_URL")
.setContentType("CONTENT_STREAM_MIMETYPE")
.setStreamType(MediaInfo.STREAM_TYPE_LIVE)
.setCustomData(customData)
.build();
RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());
iOS (Obj-C)
หากต้องการกำหนดค่าเหล่านี้ใน Web Sender ของ Cast ก่อนอื่นให้สร้างออบเจ็กต์ GCKMediaInformation ที่มีข้อมูลที่จำเป็น จากนั้นส่งคำขอโหลดไปยัง Web Receiver
NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
@"daiStreamType": @"DAI_STREAM_TYPE",
@"networkCode": @"NETWORK-CODE",
@"customAssetKey": @"CUSTOM_ASSET_KEY",
@"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;
GCKMediaInformationBuilder *mediaInfoBuilder =
[[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];
GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
request.delegate = self;
}
iOS (Swift)
หากต้องการกำหนดค่าเหล่านี้ใน Web Sender ของ Cast ก่อนอื่นให้สร้างออบเจ็กต์ GCKMediaInformation ที่มีข้อมูลที่จำเป็น จากนั้นส่งคำขอโหลดไปยัง Web Receiver
let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
print("invalid mediaURL")
return
}
let customData = [
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"region": "API_KEY"
]
let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()
guard let mediaInfo = mediaInformation else {
print("invalid mediaInformation")
return
}
if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
request.delegate = self
}
เครื่องมือ CAC
หากต้องการกำหนดค่าเหล่านี้ในเครื่องมือคำสั่งและการควบคุมของ Cast ให้คลิกแท็บ Load Media และตั้งค่าประเภทคำขอโหลดที่กำหนดเองเป็น LOAD จากนั้นแทนที่ข้อมูล JSON ในพื้นที่ข้อความด้วย JSON ต่อไปนี้
{
"media": {
"contentId": "CONTENT_ID",
"contentUrl": "BACKUP_STREAM_URL",
"contentType": ""CONTENT_STREAM_MIMETYPE"",
"streamType": "LIVE",
"customData": {
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"oAuthToken": "API_KEY"
}
}
}
คุณสามารถส่งคำขอโหลดที่กำหนดเองนี้ไปยังตัวรับเพื่อทดสอบขั้นตอนที่เหลือได้
สร้างตัวรับสัญญาณ CAF พื้นฐาน
สร้าง Web Receiver ที่กำหนดเองตามที่เห็นในคู่มือ Web Receiver ที่กำหนดเองของ CAF SDK
รหัสของผู้รับควรมีลักษณะดังนี้
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
</script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
// ...
</script>
</body>
</html>
นำเข้า IMA DAI SDK และรับ Player Manager
เพิ่มแท็กสคริปต์เพื่อนำเข้า IMA DAI SDK สำหรับ CAF ไปยัง Web Receiver ต่อจากสคริปต์ที่โหลด CAF ในแท็กสคริปต์ ให้จัดเก็บบริบทของตัวรับสัญญาณและตัวจัดการเพลเยอร์เป็นค่าคงที่ก่อนเริ่มตัวรับสัญญาณ
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
castContext.start();
</script>
</body>
</html>
เริ่มต้นใช้งาน IMA Stream Manager
เริ่มต้นใช้งาน IMA Stream Manager
<html>
<head>
<script type="text/javascript"
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
castContext.start();
</script>
</body>
</html>
สร้างตัวสกัดกั้นการโหลดของ Stream Manager
ก่อนที่จะส่งรายการสื่อไปยัง CAF ให้สร้างคำขอสตรีมในตัวสกัดกั้นข้อความ LOAD
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => { /* ... */};
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// ...
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, createDAICastRequest);
castContext.start();
สร้างคำขอสตรีม
ใช้ฟังก์ชัน createStreamRequest เพื่อสร้างสตรีม Pod Serving โดยอิงตามคำขอโหลด CAF
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => {
const customData = castRequest.media.customData;
let streamRequest;
if (customData.daiStreamType == "LIVE") {
streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
streamRequest.customAssetKey = customData.customAssetKey;
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
} else if (customData.daiStreamType == "VOD") {
streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
}
return streamRequest;
};
ดึงข้อมูลไฟล์ Manifest ที่ต่อเข้าด้วยกันจาก VTP
หากคำขอสตรีมสำเร็จ ให้ใช้ streamManager.getStreamId() เพื่อดึงรหัสของสตรีม พาร์ทเนอร์ด้านเทคนิคด้านวิดีโอ (VTP) หรือเครื่องมือจัดการไฟล์ Manifest ที่กำหนดเองจะให้วิธีการดึงข้อมูล URL ของไฟล์ Manifest โดยใช้รหัสสตรีมนี้
เมื่อได้ URL ไฟล์ Manifest แล้ว ให้แทนที่ contentUrl ที่มีอยู่ด้วย manifestUrl ใหม่
สุดท้าย ก่อนที่จะแสดงไฟล์ Manifest ของสตรีมที่แก้ไขแล้ว ให้เรียกใช้เมธอด loadStreamMetadata ใน streamManager เพื่อแจ้ง IMA SDK ว่าสามารถขอข้อมูลเมตาของสตรีมได้อย่างปลอดภัย การเรียกนี้จำเป็นสำหรับสตรีม VOD เท่านั้น
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// This is a sample VTP integration. Consult your VTP documentation
// for how to retrieve an ad-stitched stream manifest URL.
const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
const streamId = streamManager.getStreamId();
const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
// Assign your manifestUrl to the request's content URL.
castRequestWithPodStreamData.media.contentUrl = manifestUrl;
// After generating the manifest URL, VOD streams must notify the
// IMA SDK that it is safe to request ad pod metadata.
// This is only necessary for VOD streams. It is a no-op for
// livestreams, so no conditional is needed.
streamManager.loadStreamMetadata();
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
ล้างเนื้อหา IMA DAI
เมื่อคุณขอและแสดงโฆษณาในสตรีมการแสดงโฆษณาแบบพ็อดด้วย IMA DAI SDK เรียบร้อยแล้ว เราขอแนะนำให้ล้างทรัพยากรหลังจากเซสชันการแสดงโฆษณาแบบพ็อดเสร็จสมบูรณ์ เรียกใช้ StreamManager.destroy() เพื่อหยุดการเล่นสตรีม หยุดการติดตามโฆษณาทั้งหมด และปล่อยชิ้นงานสตรีมที่โหลดไว้ทั้งหมด