Rozpocznij

Wymagania wstępne

Aby zintegrować i przetestować pakiet SDK PAL na potrzeby Cast, potrzebujesz:

Aby zintegrować pakiet SDK PAL, musisz tylko zaktualizować aplikację odbiorcy. Do testowania odbiornika możesz użyć narzędzia Cast Command and Control (CAC) jako nadawcy internetowego.

Na końcu każdego kroku możesz uruchomić przykład, najpierw uruchamiając aplikację odbiornika internetowego w narzędziu CAC, a potem wysyłając żądanie wczytania.

Wygeneruj nonce

„Nonce” to pojedynczy zaszyfrowany ciąg znaków generowany przez PAL za pomocą NonceManager. NonceManager jest generowany przez metodę loadNonceManager interfejsu NonceLoader na podstawie ustawień przekazanych w NonceRequest. Aby zobaczyć przykładową aplikację, która używa PAL do generowania wartości nonce, pobierz przykład Cast z GitHub.

Każda nowa prośba o strumień wymaga nowego jednorazowego kodu. Wiele żądań reklam w tym samym strumieniu może używać tego samego identyfikatora nonce. Aby wygenerować wartość nonce za pomocą pakietu PAL SDK, najpierw utwórz dostosowaną aplikację odbiornika internetowego i dodaj ten kod:

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>

Element <cast-media-player> reprezentuje wbudowany interfejs odtwarzacza udostępniany przez interfejs Cast Web Receiver API. W zależności od typu transmisji używany odtwarzacz może się różnić. Dokładne wersje tych odtwarzaczy znajdziesz w informacjach o wersji pakietu SDK Google Cast.

Następnie dodaj ten kod, aby przechwytywać zdarzenia LOAD i generować liczbę jednorazową za każdym razem, gdy odbiornik wczytuje nowy obiekt 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();

Podczas wykonywania bezpośredniego wywołania VAST (DVC) ustaw ten nonce jako wartość parametru givn. Liczba jednorazowa jest bezpieczna w adresach URL, więc nie trzeba jej kodować w adresie URL.

Jeśli wysyłasz żądania reklam do Google i je renderujesz, musisz renderować ikonę i nakładkę AdChoices. Szczegółowe informacje o analizowaniu odpowiedzi VAST i renderowaniu ikon znajdziesz w sekcji Ikona Informacja i nakładka.

Śledzenie interakcji z filmami

Oprócz generowania wartości nonce pakiet SDK PAL musi być powiadamiany o określonych interakcjach z filmem. Aby śledzić interakcje z odbiornikiem Cast, dodaj do odbiornika niestandardowego ten kod:

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();

(Opcjonalnie) Wysyłanie sygnałów Google Ad Managera przez serwery reklamowe firm zewnętrznych

Skonfiguruj żądanie serwera reklam innej firmy wysyłane do Ad Managera. Po wykonaniu tych czynności parametr nonce będzie przekazywany z pakietu PAL SDK przez serwery pośredniczące do Google Ad Managera. Umożliwia to lepsze zarabianie dzięki Google Ad Managerowi.

Skonfiguruj serwer reklamowy firmy zewnętrznej tak, aby w żądaniu wysyłanym do Ad Managera uwzględniał wartość nonce. Oto przykład tagu reklamy skonfigurowanego na serwerze reklamowym firmy zewnętrznej:

'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'

Więcej informacji znajdziesz w przewodniku po implementacji po stronie serwera w Google Ad Managerze.

Ad Manager szuka znaku givn=, aby zidentyfikować wartość nonce. Serwer reklamowy firmy zewnętrznej musi obsługiwać własne makro, np. %%custom_key_for_google_nonce%%, i zastąpić je parametrem zapytania nonce podanym w poprzednim kroku. Więcej informacji o tym, jak to zrobić, znajdziesz w dokumentacji serwera reklam firmy zewnętrznej.