يوضّح هذا الدليل كيفية تشغيل بث "إدراج إعلان ديناميكي" باستخدام حزمة تطوير البرامج (SDK) لإدراج الإعلان ديناميكيًا في إطار عمل تطبيق Google Cast (CAF) لإعلانات الوسائط التفاعلية (IMA). إذا أردت الاطّلاع على نموذج مكتمل لعملية دمج أو اتّباعه، يمكنك تنزيل النموذج.
قبل استخدام هذا الدليل، تأكَّد من التعرّف على بروتوكول جهاز الاستقبال على الويب لإطار عمل تطبيق
Chromecast. يفترض هذا الدليل مستوى أساسيًا من الإلمام بمفاهيم جهاز استقبال CAF، مثل معترضات الرسائل وعناصر mediaInformation، بالإضافة إلى الإلمام باستخدام أداة التحكّم والقيادة في Cast لمحاكاة مُرسِل CAF.
لاستخدام IMA DAI، يجب أن يكون لديك حساب على "إدارة إعلانات Google 360". إذا كان لديك حساب على "مدير إعلانات Google"، يُرجى التواصل مع مدير حسابك لمزيد من التفاصيل. للحصول على معلومات حول الاشتراك في "إدارة إعلانات Google"، يُرجى الانتقال إلى مركز مساعدة "إدارة إعلانات Google".
للحصول على معلومات حول الدمج مع منصات أخرى أو حول استخدام حِزم تطوير البرامج (SDK) من جهة العميل في "وكالة التسويق عبر المؤثرين"، يُرجى الاطّلاع على حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية.
نظرة عامة على CAF DAI
يتضمن تنفيذ ميزة "إدراج الإعلان الديناميكي" باستخدام حزمة تطوير البرامج (SDK) لإدراج الإعلان الديناميكي في إطار عمل إعلانات Google على أجهزة الجوّال (CAF) عنصرَين رئيسيَّين كما هو موضّح في هذا الدليل:
StreamRequest: عنصر يحدّد طلب بث إلى خوادم Google الإعلانية. تتوفّر طلبات البث بنوعَين رئيسيَّين:-
LiveStreamRequest: تحدّد مفتاح مادة العرض، بالإضافة إلى مَعلمات اختيارية أخرى. VODStreamRequest: تحدّد هذه السمة معرّف مصدر المحتوى ومعرّف الفيديو، بالإضافة إلى مَعلمات اختيارية أخرى.- يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى مصادر بيانات محدّدة، ورمز شبكة "إدارة إعلانات Google" لكي تعالج حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) معرّفات الإعلانات على النحو المحدّد في إعدادات "إدارة إعلانات Google".
-
StreamManager: هو عنصر يعالج الاتصال بين بث الفيديو وحزمة تطوير البرامج (SDK) لتقنية IMA DAI، مثل إرسال إشعارات التتبُّع وإعادة توجيه أحداث البث إلى الناشر.
المتطلبات الأساسية
- حساب على Cast Developer Console مع جهاز اختبار مسجَّل
- تطبيق ويب مستقبِل مستضاف ومسجَّل في Cast Developer Console ويمكن تعديله لاستضافة الرمز البرمجي المقدَّم في هذا الدليل
- تطبيق إرسال تم ضبطه لاستخدام تطبيق الاستقبال على الويب. يستخدم هذا المثال أداة التحكّم في البث كمرسِل.
ضبط عناصر MediaInfo الخاصة بالمرسِل
أولاً، عليك ضبط عنصر MediaInfo في تطبيق المُرسِل ليتضمّن الحقول التالية:
contentId
|
معرّف فريد لملف الوسائط هذا | |
contentUrl
|
عنوان URL للبث الاحتياطي الذي يتم تحميله في حال تعذّر تنفيذ طلب DAI StreamRequest لأي سبب | |
streamType
|
بالنسبة إلى أحداث البث المباشر، يجب ضبط هذه القيمة على "LIVE". أما بالنسبة إلى أحداث الفيديو عند الطلب، فيجب ضبط هذه القيمة على "BUFFERED". | |
customData
|
assetKey
|
أحداث البث المباشر فقط: يحدّد البث المباشر الذي سيتم تحميله |
contentSourceId
|
أحداث البث المباشر للفيديوهات عند الطلب فقط يحدّد خلاصة الوسائط التي تحتوي على البث المطلوب. | |
videoId
|
أحداث البث المباشر للفيديوهات عند الطلب فقط يحدّد البث المطلوب ضمن خلاصة الوسائط المحدّدة. | |
networkCode
|
(اختياري) رمز شبكة "إدارة إعلانات Google" | |
ApiKey
|
مفتاح واجهة برمجة تطبيقات اختياري يمكن أن يكون مطلوبًا لاسترداد عنوان URL الخاص بالبث من حزمة تطوير البرامج (SDK) لإدراج الإعلان الديناميكي (DAI) في إعلانات الوسائط التفاعلية (IMA) | |
senderCanSkip
|
قيمة منطقية لإعلام جهاز الاستقبال بما إذا كان جهاز الإرسال لديه القدرة على عرض زر تخطّي، ما يتيح إمكانية عرض الإعلانات القابلة للتخطّي | |
لضبط هذه القيم في أداة التحكم والتحكم في البث، انقر على علامة التبويب تحميل الوسائط، واضبط نوع طلب التحميل المخصّص على LOAD. ثم استبدل بيانات JSON في مربّع نصّ بأحد عناصر JSON التالية:
LIVE
{
"media": {
"contentId": "bbb",
"contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8",
"streamType": "LIVE",
"customData": {
"assetKey": "c-rArva4ShKVIAkNfy6HUQ",
"networkCode": "21775744923",
"ApiKey": "",
"senderCanSkip": true
}
},
"credentials": "testCredentials"
}
فيديو عند الطلب
{
"media": {
"contentId": "tos",
"contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/tos.m3u8",
"streamType": "BUFFERED",
"customData": {
"contentSourceId": "2548831",
"videoId": "tears-of-steel",
"networkCode": "21775744923",
"ApiKey": "",
"senderCanSkip": true
}
},
"credentials": "testCredentials"
}
يمكن إرسال عنصر طلب التحميل المخصّص هذا إلى جهاز الاستقبال لاختبار الخطوات التالية.
إنشاء تطبيق استقبال CAF أساسي
اتّبِع دليل "جهاز الاستقبال الأساسي" في حزمة تطوير البرامج (SDK) لإطار عمل تطبيقات البث (CAF) لإنشاء جهاز استقبال ويب أساسي.
من المفترض أن يظهر رمز جهاز الاستقبال على النحو التالي:
<html>
<head>
<script type="text/javascript"
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
</script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
cast.framework.CastReceiverContext.getInstance().start();
</script>
</body>
</html>
استيراد حزمة تطوير البرامج (SDK) لتقنية IMA DAI والحصول على Player Manager
أضِف علامة برمجية لاستيراد حزمة تطوير البرامج (SDK) لتقنية IMA DAI في CAF إلى جهاز الاستقبال على الويب، بعد تحميل CAF مباشرةً. حزمة تطوير البرامج (SDK) لإدراج الإعلانات الديناميكية في CAF هي حزمة دائمة، لذا لا حاجة إلى ضبط إصدار معيّن. بعد ذلك، في العلامة البرمجية التالية، يمكنك تخزين سياق جهاز الاستقبال ومدير المشغّل كثوابت قبل بدء تشغيل جهاز الاستقبال.
<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();
castContext.start();
</script>
</body>
</html>
إعداد IMA Stream Manager
ابدأ إعداد مدير البث في حزمة تطوير البرامج (SDK) الخاصة بـ "إدراج الإعلان الديناميكي" في CAF.
<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>
إنشاء معترض رسائل التحميل
تستخدم حزمة تطوير البرامج (SDK) لخدمة "إدراج الإعلانات ديناميكيًا" في CAF معترِض رسائل تحميل CAF لتقديم طلبات البث واستبدال عنوان URL للمحتوى ببث "إدراج الإعلانات ديناميكيًا" النهائي.
يستدعي معترض الرسائل streamManager.requestStream() الذي يعالج
إعداد الفواصل الإعلانية وطلب البث واستبدال contentURL الحالي.
يمكن أن يكون هناك معترض واحد فقط لرسائل التحميل، لذا إذا كان تطبيقك يتطلب استخدام المعترض، عليك دمج أي دوال مخصّصة في عملية الاستدعاء نفسها.
<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();
const getStreamRequest = (request) => null;
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (request) => {
return streamManager.requestStream(request, getStreamRequest(request))
.then((request) => {
this.broadcast('Stream request successful.');
return Promise.resolve(request);
})
.catch((error) => {
this.broadcast('Stream request failed.');
return Promise.resolve(request);
});
});
castContext.start();
</script>
</body>
</html>
إنشاء طلب البث
لإكمال عملية دمج ميزة "إدراج الإعلانات الديناميكية" في CAF، عليك إنشاء طلب
البث
باستخدام البيانات التي تم تضمينها في عنصر mediaInfo من المُرسِل.
<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();
const getStreamRequest = (request) => {
const imaRequestData = request.media.customData;
let streamRequest = null;
if (imaRequestData.assetKey) {
// Live stream
streamRequest = new google.ima.cast.dai.api.LiveStreamRequest();
streamRequest.assetKey = imaRequestData.assetKey;
} else if (imaRequestData.contentSourceId) {
// VOD stream
streamRequest = new google.ima.cast.dai.api.VODStreamRequest();
streamRequest.contentSourceId = imaRequestData.contentSourceId;
streamRequest.videoId = imaRequestData.videoId;
}
if (streamRequest && imaRequestData.networkCode) {
streamRequest.networkCode = imaRequestData.networkCode;
}
if (streamRequest && imaRequestData.ApiKey) {
streamRequest.ApiKey = imaRequestData.ApiKey;
}
if (streamRequest && imaRequestData.senderCanSkip) {
streamRequest.senderCanSkip = imaRequestData.senderCanSkip;
}
return streamRequest;
};
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (request) => {
return streamManager.requestStream(request, getStreamRequest(request))
.then((request) => {
return Promise.resolve(request);
})
.catch((error) => {
this.broadcast('Stream request failed.');
return Promise.resolve(request);
});
});
castContext.start();
</script>
</body>
</html>
يمكنك الآن طلب بثّ "إدراج الإعلان الديناميكي" وتشغيله باستخدام حزمة تطوير البرامج (SDK) لإدراج الإعلان الديناميكي في CAF من Google. لمزيد من المعلومات حول ميزات حزمة تطوير البرامج (SDK) الأكثر تقدّمًا، يُرجى الاطّلاع على الأدلة الأخرى أو تنزيل نماذج تطبيقات الاستقبال.