Требования
Чтобы интегрировать и протестировать PAL SDK для Cast, вам понадобится следующее:
Приложение-получатель, которое генерирует одноразовый код с помощью перехвата сообщений.
Приложение отправителя, которое запускает загрузку контента с запросом объявления на устройстве получателя.
Поскольку для интеграции PAL SDK нужно обновить только приложение-получатель, вы можете использовать инструмент управления командами Cast (CAC) в качестве веб-отправителя для тестирования получателя.
Вы можете запустить образец в конце каждого шага, сначала запустив приложение веб-приемника в CAC Tool, а затем выполнив любой запрос на загрузку.
Сгенерировать одноразовый код
Однократно используемое число – это зашифрованная строка, сгенерированная PAL с помощью функции NonceManager. NonceManager генерируется методом loadNonceManager класса NonceLoader на основе настроек, переданных в NonceRequest. Чтобы посмотреть пример приложения, в котором PAL используется для создания одноразового кода, скачайте пример Cast с GitHub.
Каждый новый запрос потока требует нового одноразового кода. В одном потоке несколько запросов объявлений могут использовать один и тот же однократно используемый код. Чтобы создать однократно используемый номер с помощью PAL SDK, сначала создайте специализированное приложение веб-приемника и добавьте следующий код:
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) задайте это значение nonce в качестве значения параметра givn. Однократно используемое число не требует кодирования при добавлении в URL.
Если вы запрашиваете и показываете объявления Google, то должны отображать значок и оверлей AdChoices. Подробнее о том, как анализировать ответ VAST и показывать значки, рассказывается в статье Значок "Выбор рекламы" и оверлей.
Как отслеживать взаимодействия с видео
Помимо создания одноразового кода, PAL SDK должен получать уведомления о некоторых взаимодействиях с видео. Чтобы отслеживать взаимодействия с приемником Cast, добавьте в него следующий код:
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 Менеджера рекламы через сторонние серверы объявлений (необязательно)
Настройте запрос стороннего сервера объявлений для Менеджера рекламы. После того как вы выполните описанные ниже действия, параметр nonce будет передаваться из PAL SDK через ваши промежуточные серверы в Google Менеджер рекламы. Это позволяет повысить эффективность монетизации с помощью Google Менеджера рекламы.
Настройте сторонний сервер объявлений так, чтобы он включал одноразовый код в запрос к Менеджеру рекламы. Вот пример тега объявления, настроенного на стороннем сервере объявлений:
'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'
Подробнее о реализации на стороне сервера в Google Менеджере рекламы…
Менеджер рекламы ищет givn=, чтобы определить значение nonce. Сторонний сервер объявлений должен поддерживать собственный макрос, например %%custom_key_for_google_nonce%%, и заменять его параметром nonce, указанным на предыдущем шаге. Дополнительную информацию о том, как это сделать, можно найти в документации стороннего сервера объявлений.