تسهّل حزم تطوير البرامج (SDK) للإعلانات التفاعلية (IMA) دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك.
يمكن لحِزم تطوير البرامج للإعلانات التفاعلية (IMA SDK) طلب الإعلانات من أي خادم إعلانات متوافق مع نموذج عرض إعلانات الفيديو (VAST) وإدارة تشغيل الإعلانات في تطبيقاتك.
باستخدام حزم تطوير البرامج (SDK) لتقنية IMA DAI، تقدّم التطبيقات طلب بث لإعلان وفيديو محتوى، سواء كان فيديو عند الطلب أو محتوى مباشرًا. بعد ذلك، تعرض حزمة تطوير البرامج (SDK) بث فيديو مدمجًا، وبالتالي لن تحتاج إلى إدارة التبديل بين الإعلان ومحتوى الفيديو داخل تطبيقك.
يوضّح هذا الدليل كيفية تشغيل بثّ "عرض مجموعات إعلانية متسلسلة" في ميزة "إدراج الإعلان ديناميكيًا" (DAI) باستخدام حزمة تطوير البرامج (SDK) لخدمة "إدراج الإعلان ديناميكيًا" في "إعلانات الوسائط التفاعلية" (IMA) لإطار عمل تطبيق البث (CAF).
قبل استخدام هذا الدليل، تعرَّف على بروتوكول جهاز الاستقبال على الويب في إطار عمل تطبيق Chromecast. يفترض هذا الدليل فهمًا أساسيًا لمفاهيم مستقبل CAF، مثل عناصر معترضات الرسائل وmediaInformation، والإلمام باستخدام أداة التحكّم والأوامر في Cast لمحاكاة مُرسِل CAF.
لاستخدام ميزة "عرض مجموعات إعلانية متسلسلة" في IMA DAI، يجب أن تعمل مع شريك في هذه الميزة وأن يكون لديك حساب على إصدار Advanced من "مدير إعلانات Google 360". إذا كان لديك حساب على "مدير إعلانات Google"، يُرجى التواصل مع مدير حسابك لمزيد من التفاصيل. للحصول على معلومات حول الاشتراك في "إدارة إعلانات Google"، يُرجى الانتقال إلى مركز مساعدة "إدارة إعلانات Google".
للحصول على معلومات حول الدمج مع منصات أخرى أو حول استخدام حِزم تطوير البرامج (SDK) من جهة العميل في IMA، يُرجى الاطّلاع على حِزم تطوير البرامج لإعلانات الوسائط التفاعلية.
نظرة عامة على عرض مجموعات إعلانية متسلسلة في IMA DAI
يتضمّن تنفيذ ميزة "عرض الإعلانات في مجموعة" باستخدام حزمة تطوير البرامج (SDK) لإدراج الإعلانات الديناميكية (DAI) في إطار عمل "إعلانات الوسائط التفاعلية" (IMA) من Google مكوّنَين رئيسيَّين، يتم توضيحهما في هذا الدليل:
StreamRequest: عنصر يحدّد طلب بث إلى خوادم Google الإعلانية. تحدّد الطلبات رمز الشبكة ومفتاح مادة العرض المخصّصة ومفتاح واجهة برمجة التطبيقات الاختياري، بالإضافة إلى مَعلمات اختيارية أخرى.-
StreamManager: عنصر يعالج الاتصال بين بث الفيديو وحزمة تطوير البرامج (SDK) لتقنية IMA DAI، مثل إرسال إشعارات التتبُّع وإعادة توجيه أحداث البث إلى الناشر
المتطلبات الأساسية
- حساب على Cast Developer Console يتضمّن أجهزة اختبار مسجَّلة
- تطبيق ويب مستقبِل مستضاف ومسجَّل في Cast Developer Console ويمكن تعديله لاستضافة الرمز البرمجي المقدَّم في هذا الدليل
- تطبيق إرسال تم ضبطه لاستخدام تطبيق استقبال الويب. لأغراض هذا المثال، استخدِم أداة Cast Command and Control كمرسِل.
ضبط عناصر MediaInfo الخاصة بالمرسِل
أولاً، اضبط عنصر MediaInfo في تطبيق المُرسِل
ليتضمّن الحقول التالية:
| الحقل | المحتويات | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
معرّف فريد لملف الوسائط هذا
CONTENT_ID |
||||||||||
contentUrl
|
اختيارية: عنوان URL للبث الاحتياطي الذي يتم تشغيله في حال تعذّر تحميل بث "إدراج الإعلانات الديناميكية"
BACKUP_STREAM_URL |
||||||||||
contentType
|
اختيارية: نوع Mime لمجموعات بث المحتوى الاحتياطية هذه السمة مطلوبة فقط للبث المباشر عبر بروتوكول DASH.
CONTENT_STREAM_MIMETYPE |
||||||||||
streamType
|
تختلف السلسلة الحرفية أو الثابتة المستخدَمة لهذه القيمة حسب منصة المُرسِل. | ||||||||||
customData
|
يحتوي الحقل customData على مخزن مفتاح/قيمة للحقول الإضافية المطلوبة. في هذا النموذج، يحتوي على معلَمات بث إعلانات الفيديو المدمجة مع المحتوى. في
تطبيق الإنتاج، يمكنك بدلاً من ذلك تمرير معرّف يستخدمه تطبيق
جهاز الاستقبال المتوافق مع Google Cast لاسترداد هذه المَعلمات من خلال طلب
من جهة الخادم.
|
في ما يلي بعض عيّنات التعليمات البرمجية لمساعدتك في البدء:
الويب
لضبط هذه القيم في تطبيق ويب مُرسِل يتوافق مع Cast، عليك أولاً إنشاء عنصر
MediaInfo
يتضمّن البيانات المطلوبة، ثم إرسال طلب
تحميل إلى تطبيق الويب المُستقبِل.
// 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
لضبط هذه القيم في تطبيق ويب مُرسِل متوافق مع Cast، عليك أولاً إنشاء عنصر MediaInfo يتضمّن البيانات المطلوبة، ثم إرسال طلب تحميل إلى تطبيق الويب المُستقبِل.
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)
لضبط هذه القيم في تطبيق ويب مُرسِل يتوافق مع Cast، عليك أولاً إنشاء عنصر
GCKMediaInformation
يتضمّن البيانات المطلوبة، ثم إرسال طلب
تحميل إلى تطبيق الويب المُستقبِل.
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)
لضبط هذه القيم في تطبيق ويب مُرسِل يتوافق مع Cast، عليك أولاً إنشاء عنصر
GCKMediaInformation
يتضمّن البيانات المطلوبة، ثم إرسال طلب
تحميل إلى تطبيق الويب المُستقبِل.
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. ثم استبدل بيانات 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 أساسي
أنشئ جهاز استقبال ويب مخصّصًا، كما هو موضّح في دليل جهاز استقبال الويب المخصّص لحزمة تطوير البرامج (SDK) لإطار عمل Google Cast.
من المفترض أن يظهر رمز جهاز الاستقبال على النحو التالي:
<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>
استيراد حزمة تطوير البرامج (SDK) لتقنية IMA DAI والحصول على Player Manager
أضِف علامة برمجية لاستيراد حزمة تطوير البرامج (SDK) لخدمة IMA DAI في CAF إلى جهاز الاستقبال على الويب، بعد تحميل 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.
<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 لإنشاء بث "عرض الإعلانات في مجموعات" استنادًا إلى طلب تحميل 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;
};
استرداد البيان المدمج من "مقدّم تكنولوجيا الفيديو"
إذا نجح طلب البث، استخدِم streamManager.getStreamId() لاسترداد معرّف البث. سيقدّم لك شريكك الفني في مجال الفيديو (VTP) أو معالج البيان المخصّص تعليمات لاسترداد عنوان URL للبيان باستخدام معرّف البث هذا.
بعد استرداد عنوان URL لملف البيان، استبدِل السمة contentUrl الحالية
بالسمة manifestUrl الجديدة.
أخيرًا، قبل عرض بيان البث المعدَّل، يمكنك استدعاء الإجراء
loadStreamMetadata
على
streamManager
لإعلام حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) بأنّه يمكنها طلب البيانات الوصفية للبث بأمان. هذا الطلب ضروري فقط
لأحداث البث المباشر للفيديو عند الطلب.
/**
* 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
عند الانتهاء بنجاح من طلب الإعلانات وعرضها في بث عرض الإعلانات المتعدّدة باستخدام حزمة تطوير البرامج (SDK) لعرض الإعلانات الديناميكي (DAI) في "إعلانات الوسائط التفاعلية" (IMA)، ننصحك بإزالة أي موارد بعد اكتمال جلسة عرض الإعلانات المتعدّدة. يمكنك استدعاء StreamManager.destroy() لإيقاف تشغيل البث وإيقاف تتبُّع الإعلانات وإصدار جميع مواد عرض البث التي تم تحميلها.