المتطلبات الأساسية
لدمج حزمة تطوير البرامج (SDK) الخاصة بـ PAL واختبارها على Cast، يجب توفُّر ما يلي:
تطبيق استقبال لإنشاء رقم عشوائي غير متكرّر باستخدام اعتراض الرسائل
تطبيق مرسِل لتفعيل جهاز الاستقبال من أجل تحميل محتوى يتضمّن طلب عرض الإعلان.
بما أنّه عليك فقط تعديل تطبيق الاستقبال لدمج حزمة تطوير البرامج (SDK) الخاصة بـ PAL، يمكنك استخدام أداة "التحكّم في Cast" (CAC) كمرسِل على الويب لاختبار تطبيق الاستقبال.
يمكنك تشغيل العيّنة في نهاية كل خطوة من خلال تشغيل تطبيق أداة استقبال الويب أولاً في أداة CAC، ثم تقديم أي طلب تحميل.
إنشاء رقم خاص
"الرقم الخاص" هو سلسلة مشفّرة واحدة ينشئها PAL من خلال
NonceManager. يتم إنشاء
NonceManager بواسطة
طريقة loadNonceManager
في NonceLoader،
استنادًا إلى الإعدادات التي تم تمريرها في
NonceRequest. للاطّلاع على نموذج تطبيق يستخدم PAL لإنشاء رقم خاص، نزِّل مثال Cast من GitHub.
يتطلّب كل طلب بث جديد قيمة nonce جديدة. يمكن أن تستخدم طلبات إعلانات متعدّدة ضمن البث نفسه قيمة nonce نفسها. لإنشاء رقم عشوائي باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ PAL، عليك أولاً إنشاء تطبيق مخصّص لجهاز استقبال الويب وإضافة الرمز التالي:
receiver.html
<!DOCTYPE html>
<html>
<head>
<script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/pal/sdkloader/cast_pal.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<footer>
<script src="js/receiver.js" type="module"></script>
</footer>
</body>
</html>
يمثّل العنصر <cast-media-player> واجهة المستخدم المضمّنة الخاصة بمشغّل الوسائط التي توفّرها واجهة برمجة التطبيقات Cast Web Receiver API. قد يختلف مشغّل الفيديو الفعلي المستخدَم حسب نوع البث. يمكنك العثور على الإصدارات الدقيقة من مشغّلات الوسائط هذه في ملاحظات إصدار حزمة تطوير البرامج (SDK) الخاصة بـ Google Cast.
بعد ذلك، أضِف الرمز التالي لاعتراض أحداث LOAD وإنشاء رقم خاص في كل مرة يحمّل فيها جهاز الاستقبال عنصر MediaInformation جديدًا:
js/receiver.js
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const consentSettings = new goog.cast.pal.ConsentSettings();
// For the correct usage of the allowStorage property, See
// developers.google.com/ad-manager/pal/cast/reference/js/ConsentSettings#allowStorage.
consentSettings.allowStorage = true;
// You need a nonce loader to request your stream's nonceManager. The
// nonceManager provides your nonce. You should reuse the same nonce loader for
// the entire lifecycle of the receiver.
const nonceLoader = new goog.cast.pal.NonceLoader(consentSettings);
// You need a reference to the NonceManager to track when an ad is shown or
// clicked.
let nonceManager;
/**
* Sends a debug message to the CAF sender.
*
* @param {String} message - The message to send
*/
const log = (message) => {
// Use CastDebugLogger to log a message to the sender. See
// https://developers.google.com/cast/docs/debugging/cast_debug_logger.
}
/**
* Stores the nonce manager in the outer scoped variable and retrieves a nonce,
* so it can be used to build your ad request URL
*
* @param {NonceManager} loadedNonceManager - The loaded nonce manager
*/
const buildAdRequest = (loadedNonceManager) => {
nonceManager = loadedNonceManager;
const nonce = nonceManager.getNonce();
log('received nonce:' + nonce);
// TODO: Set this nonce as the value for the `givn` parameter of your ad
// request URL. For example:
// const adRequestURL = 'https://myadserver.com/ads?givn=' + nonce;
}
/**
* Configures a new nonce request, then requests a nonce.
*
* @param {LoadRequestData} loadRequestData - the load request object,
* which contains the MediaInformation object from the sender. See
* developers.google.com/cast/docs/reference/web_receiver/cast.framework.messages.LoadRequestData
* @return {(Promise<LoadRequestData>)} - A Promise to build an ad request.
*/
const handleLoadRequest = (loadRequestData) => {
// Clear any old nonceManager before loading new media.
nonceManager = null;
// See developers.google.com/ad-manager/pal/cast/reference/js/NonceRequest
// for details about each property. The NonceRequest parameters set here are
// example parameters. You should set your parameters based on your own app
// characteristics.
const nonceRequest = new goog.cast.pal.NonceRequest();
nonceRequest.adWillAutoPlay = true;
// A URL describing the video stream.
nonceRequest.descriptionUrl = 'https://example.com';
nonceRequest.iconsSupported = true;
nonceRequest.ppid = 'Sample PPID';
nonceRequest.sessionId = 'Sample SID';
nonceRequest.url = loadRequestData.media.contentUrl;
// The height of the player in physical pixels.
// For a fullscreen player on a 1080p screen, the video height would be 1080.
nonceRequest.videoHeight = window.devicePixelRatio * window.screen.height;
// The width of the player in physical pixels.
// For a fullscreen player on a 1080p screen, the video width would be 1920.
nonceRequest.videoWidth = window.devicePixelRatio * window.screen.width;
return nonceLoader.loadNonceManager(nonceRequest)
.then(buildAdRequest)
.catch((e) => {
log("Error: " + e.message);
});
};
// Set up the event handler for the LOAD event type.
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, handleLoadRequest);
castContext.start();
عند إجراء طلب VAST مباشر (DVC)، اضبط رقم الاستخدام لمرة واحدة هذا كقيمة في المَعلمة givn. إنّ الرقم الخاص صالح للاستخدام في عناوين URL، ولست بحاجة إلى ترميزه.
إذا كنت تطلب إعلانات وتعرضها من Google، عليك عرض رمز AdChoices والتراكب. للحصول على تفاصيل حول تحليل استجابة VAST وعرض الرموز، يُرجى الاطّلاع على رمز "خيارات الإعلان" والتراكب.
تتبُّع التفاعلات مع الفيديوهات
بالإضافة إلى إنشاء رقم عشوائي غير متكرّر، يجب إبلاغ حزمة تطوير البرامج (SDK) الخاصة بـ PAL ببعض التفاعلات مع الفيديو. لتتبُّع التفاعلات مع جهاز استقبال البث، أضِف الرمز التالي إلى جهاز الاستقبال المخصّص:
js/receiver.js
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const consentSettings = new goog.cast.pal.ConsentSettings();
// For the correct usage of the allowStorage property, See
// developers.google.com/ad-manager/pal/cast/reference/js/ConsentSettings#allowStorage.
consentSettings.allowStorage = true;
// You need a nonce loader to request your stream's nonceManager. The
// nonceManager provides your nonce. You should reuse the same nonce loader for
// the entire lifecycle of the receiver.
const nonceLoader = new goog.cast.pal.NonceLoader(consentSettings);
// You need a reference to the NonceManager for sending ad events.
let nonceManager;
// Track playback status.
let playbackDidStart = false;
...
// Register the start of playback.
playerManager.addEventListener(cast.framework.events.EventType.PLAYING, () => {
if (playbackDidStart) return;
playbackDidStart = true;
if (nonceManager) {
log('Registered playback start');
nonceManager.sendPlaybackStart();
} else {
log("Error: There is no nonce manager for this media.");
}
});
// Register any interactions with the player.
const interactionEvents = [
cast.framework.events.EventType.REQUEST_SEEK,
cast.framework.events.EventType.REQUEST_STOP,
cast.framework.events.EventType.REQUEST_PAUSE,
cast.framework.events.EventType.REQUEST_PLAY,
cast.framework.events.EventType.REQUEST_SKIP_AD,
cast.framework.events.EventType.REQUEST_PLAY_AGAIN,
cast.framework.events.EventType.REQUEST_PLAYBACK_RATE_CHANGE,
cast.framework.events.EventType.REQUEST_VOLUME_CHANGE,
cast.framework.events.EventType.REQUEST_USER_ACTION,
cast.framework.events.EventType.REQUEST_FOCUS_STATE,
];
playerManager.addEventListener(interactionEvents, (interactionEvent) => {
if (nonceManager) {
log('Registered interaction: ' + interactionEvent);
nonceManager.sendAdTouch(interactionEvent);
} else {
log("Error: There is no nonce manager for this media.");
}
});
// Register the end of playback.
playerManager.addEventListener(cast.framework.events.EventType.MEDIA_FINISHED, () => {
playbackDidStart = false;
if (nonceManager) {
log('Registered playback end');
nonceManager.sendPlaybackEnd();
} else {
log("Error: There is no nonce manager for this media.");
}
});
castContext.start();
(اختياري) إرسال إشارات "مدير إعلانات Google" من خلال خوادم إعلانات خارجية
اضبط طلب خادم الإعلانات التابع لجهة خارجية في "إدارة إعلانات Google". بعد إكمال الخطوات التالية، تنتقل المَعلمة nonce من حزمة تطوير البرامج (SDK) الخاصة بمنصة PAL، ومن خلال خوادمك الوسيطة، ثم إلى "مدير إعلانات Google". يتيح ذلك تحقيق الربح بشكل أفضل من خلال "مدير إعلانات Google".
اضبط خادم الإعلانات من جهة خارجية لتضمين الرقم الخاص في طلب الخادم إلى "إدارة الإعلانات". في ما يلي مثال على علامة إعلان تم إعدادها داخل خادم إعلانات من جهة خارجية:
'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'
لمزيد من التفاصيل، اطّلِع على دليل تنفيذ "مدير إعلانات Google" من جهة الخادم.
يبحث "مدير إعلانات Google" عن givn= لتحديد قيمة الرقم العشوائي. يجب أن يتيح خادم الإعلانات التابع لجهة خارجية استخدام بعض وحدات الماكرو الخاصة به، مثل %%custom_key_for_google_nonce%%، وأن يستبدلها بمَعلمة طلب البحث الخاصة برقم الاستخدام لمرة واحدة التي قدّمتها في الخطوة السابقة. يجب أن تتوفّر معلومات إضافية حول كيفية تنفيذ ذلك في مستندات خادم الإعلانات التابع لجهة خارجية.