Zentrale Funktionen zu Ihrem benutzerdefinierten Web-Receiver hinzufügen

Diese Seite enthält Code-Snippets und Beschreibungen der Funktionen, die für eine App des benutzerdefinierten Webempfängers verfügbar sind.

  1. Ein cast-media-player-Element, das die integrierte Player-Benutzeroberfläche von Web Receiver darstellt.
  2. Benutzerdefinierte CSS-ähnliche Stile für das cast-media-player-Element, um verschiedene UI-Elemente wie background-image, splash-image und font-family zu gestalten.
  3. Ein Skriptelement zum Laden des Web Receiver-Frameworks.
  4. JavaScript-Code zum Abfangen von Nachrichten und zum Verarbeiten von Ereignissen.
  5. Wiedergabeliste für Autoplay.
  6. Optionen zum Konfigurieren der Wiedergabe.
  7. Optionen zum Festlegen des Web Receiver-Kontexts.
  8. Optionen zum Festlegen von Befehlen, die von der Web Receiver-App unterstützt werden.
  9. Ein JavaScript-Aufruf zum Starten der Web Receiver-Anwendung

Anwendungskonfiguration und Optionen

Anwendung konfigurieren

Die CastReceiverContext ist die äußerste Klasse, die dem Entwickler zur Verfügung gestellt wird. Sie verwaltet das Laden der zugrunde liegenden Bibliotheken und übernimmt die Initialisierung des Web Receiver SDK. Das SDK umfasst APIs, mit denen Anwendungsentwickler das SDK über CastReceiverOptions konfigurieren können. Diese Konfigurationen werden einmal pro App-Start ausgewertet und an das SDK übergeben, wenn der optionale Parameter im Aufruf auf start festgelegt wird.

Das folgende Beispiel zeigt, wie das Standardverhalten für die Erkennung, ob eine Absenderverbindung noch aktiv ist, überschrieben wird. Wenn der Webempfänger maxInactivity Sekunden lang nicht mit einem Absender kommunizieren konnte, wird ein SENDER_DISCONNECTED-Ereignis ausgelöst. Die folgende Konfiguration überschreibt dieses Zeitlimit. Das kann beim Debuggen von Problemen nützlich sein, da die Web Receiver-App die Chrome Remote Debugger-Sitzung nicht schließt, wenn keine verbundenen Absender mit dem Status IDLE verbunden sind.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

Player konfigurieren

Beim Laden von Inhalten bietet das Web Receiver SDK die Möglichkeit, Wiedergabevariablen wie DRM-Informationen, Wiederholungskonfigurationen und Anfrage-Handler mit cast.framework.PlaybackConfig zu konfigurieren. Diese Informationen werden von PlayerManager verarbeitet und beim Erstellen der Spieler ausgewertet. Player werden jedes Mal erstellt, wenn eine neue Last an das Web Receiver SDK übergeben wird. Änderungen am PlaybackConfig nach dem Erstellen des Players werden beim nächsten Laden von Inhalten ausgewertet. Das SDK bietet die folgenden Methoden zum Ändern von PlaybackConfig.

  • CastReceiverOptions.playbackConfig, um die Standardkonfigurationsoptionen beim Initialisieren von CastReceiverContext zu überschreiben.
  • PlayerManager.getPlaybackConfig(), um die aktuelle Konfiguration abzurufen.
  • PlayerManager.setPlaybackConfig(), um die aktuelle Konfiguration zu überschreiben. Diese Einstellung wird auf alle nachfolgenden Ladevorgänge oder so lange angewendet, bis sie wieder überschrieben wird.
  • PlayerManager.setMediaPlaybackInfoHandler(), um zusätzliche Konfigurationen nur für das Medienelement anzuwenden, das über die aktuellen Konfigurationen geladen wird. Der Handler wird unmittelbar vor der Spielererstellung aufgerufen. Hier vorgenommene Änderungen sind nicht dauerhaft und werden nicht in Abfragen von getPlaybackConfig() berücksichtigt. Beim Laden des nächsten Medienelements wird dieser Handler noch einmal aufgerufen.

Das folgende Beispiel zeigt, wie PlaybackConfig beim Initialisieren von CastReceiverContext festgelegt wird. Die Konfiguration überschreibt ausgehende Anfragen zum Abrufen von Manifesten. Der Handler gibt an, dass CORS-Anfragen für die Zugriffssteuerung mit Anmeldedaten wie Cookies oder Autorisierungsheadern gestellt werden.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

Das folgende Beispiel zeigt, wie PlaybackConfig mit dem Getter und Setter aus PlayerManager überschrieben wird. Mit dieser Einstellung wird der Player so konfiguriert, dass die Inhaltswiedergabe fortgesetzt wird, nachdem ein Segment geladen wurde.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

Das folgende Beispiel zeigt, wie PlaybackConfig für eine bestimmte Ladeanfrage mit dem Info-Handler zur Medienwiedergabe überschrieben werden kann. Der Handler ruft die von der Anwendung implementierte Methode getLicenseUrlForMedia auf, um das licenseUrl aus dem contentId des aktuellen Elements abzurufen.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

Event-Listener

Mit dem Web Receiver SDK kann deine Web Receiver-App Playerereignisse verarbeiten. Der Ereignis-Listener verwendet einen cast.framework.events.EventType-Parameter (oder ein Array dieser Parameter), der die Ereignisse angibt, die den Listener auslösen sollen. Vorkonfigurierte cast.framework.events.EventType-Arrays, die für die Fehlerbehebung hilfreich sind, finden Sie in cast.framework.events.category. Der Ereignisparameter liefert zusätzliche Informationen zum Ereignis.

Wenn Sie beispielsweise wissen möchten, wann eine mediaStatus-Änderung gesendet wird, können Sie die folgende Logik zur Verarbeitung des Ereignisses verwenden:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

Abfangen von Nachrichten

Mit dem Web Receiver SDK kann Ihre Web Receiver-App Nachrichten abfangen und benutzerdefinierten Code für diese Nachrichten ausführen. Für den Nachrichtenabfangen wird der Parameter cast.framework.messages.MessageType verwendet, der angibt, welche Art von Nachricht abgefangen werden soll.

Der Interceptor sollte die geänderte Anfrage oder ein Promise zurückgeben, das mit dem geänderten Anfragewert aufgelöst wird. Durch die Rückgabe von null wird der Aufruf des Standard-Nachrichten-Handlers verhindert. Weitere Informationen finden Sie unter Medien laden.

Wenn Sie beispielsweise die Daten der Ladeanfrage ändern möchten, können Sie diese mit der folgenden Logik abfangen und ändern:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

Fehlerbehandlung

Wenn beim Abfangen von Nachrichten Fehler auftreten, sollte Ihre Web Receiver-Anwendung ein entsprechendes cast.framework.messages.ErrorType- und ein cast.framework.messages.ErrorReason-Objekt zurückgeben.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

Abfangen von Nachrichten und Event-Listener im Vergleich

Im Folgenden sind einige wesentliche Unterschiede zwischen dem Abfangen von Nachrichten und dem Event-Listener aufgeführt:

  • Ein Event-Listener erlaubt nicht, dass Sie die Anfragedaten ändern.
  • Ein Event-Listener eignet sich am besten zum Auslösen von Analysen oder einer benutzerdefinierten Funktion.
playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });
  • Das Abfangen von Nachrichten ermöglicht es Ihnen, eine Nachricht anzuhören, sie abzufangen und die Anfragedaten selbst zu ändern.
  • Das Abfangen von Nachrichten eignet sich am besten für die Verarbeitung benutzerdefinierter Logik in Bezug auf Datenanfragen.

Medien werden geladen

MediaInformation bietet zahlreiche Attribute zum Laden von Medien in der cast.framework.messages.MessageType.LOAD-Nachricht, darunter entity, contentUrl und contentId.

  • entity wird bei der Implementierung für Ihre Sender- und Empfänger-Apps empfohlen. Die Property ist eine Deeplink-URL, die entweder eine Playlist oder ein Medieninhalt sein kann. Ihre Anwendung sollte diese URL parsen und mindestens eines der anderen beiden Felder ausfüllen.
  • Das contentUrl entspricht der Wiedergabe-URL, die der Player zum Laden des Inhalts verwendet. Diese URL könnte beispielsweise auf ein DASH-Manifest verweisen.
  • Bei contentId kann es sich entweder um eine URL für einen abspielbaren Inhalt (ähnlich wie die contentUrl-Property) oder um eine eindeutige ID für den zu ladenden Inhalt oder die zu ladende Playlist handeln. Wenn Sie dieses Attribut als Kennung verwenden, muss Ihre App eine spielbare URL im contentUrl ausfüllen.

Es empfiehlt sich, entity zum Speichern der tatsächlichen ID oder der Schlüsselparameter und contentUrl für die URL der Medien zu verwenden. Ein Beispiel dafür wird im folgenden Snippet gezeigt, bei dem die entity in der LOAD-Anfrage vorhanden ist und die spielbare contentUrl abgerufen wird:

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

Gerätefunktionen

Über die Methode getDeviceCapabilities werden Geräteinformationen auf dem verbundenen Übertragungsgerät und dem angeschlossenen Video- oder Audiogerät bereitgestellt. Die Methode getDeviceCapabilities bietet Supportinformationen für Google Assistant, Bluetooth und die verbundenen Display- und Audiogeräte.

Diese Methode gibt ein Objekt zurück, das Sie abfragen können, indem Sie eine der angegebenen Enums übergeben, um die Gerätefunktion für diese Enum zu erhalten. Die Enums sind in cast.framework.system.DeviceCapabilities definiert.

In diesem Beispiel wird geprüft, ob das Web Receiver-Gerät HDR und DolbyVision (DV) mit den Schlüsseln IS_HDR_SUPPORTED bzw. IS_DV_SUPPORTED wiedergeben kann.

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

Umgang mit Nutzerinteraktionen

Nutzer können mit Ihrer Web Receiver-App über Sender-Apps (Web, Android und iOS), Sprachbefehle auf Geräten mit integriertem Assistant, Touchbedienung auf Smart Displays und Fernbedienungen auf Android TV-Geräten interagieren. Das Cast SDK bietet verschiedene APIs, mit denen die Web Receiver-App diese Interaktionen verarbeiten, die App-UI über Nutzeraktionsstatus aktualisieren und optional die Änderungen senden kann, um Back-End-Dienste zu aktualisieren.

Unterstützte Medienbefehle

Die Status der UI-Steuerelemente werden von den erweiterten Sender-Controllern von iOS und Android über MediaStatus.supportedMediaCommands, Empfangs- und Fernbedienungs-Apps auf Touch-Geräten und Empfangs-Apps auf Android TV-Geräten festgelegt. Wenn eine bestimmte bitweise Command in der Property aktiviert ist, werden die Schaltflächen aktiviert, die sich auf diese Aktion beziehen. Wenn der Wert nicht festgelegt ist, ist die Schaltfläche deaktiviert. Diese Werte können auf dem Web-Receiver folgendermaßen geändert werden:

  1. Verwenden Sie PlayerManager.setSupportedMediaCommands, um die spezifische Commands festzulegen.
  2. Neuen Befehl mit addSupportedMediaCommands hinzufügen
  3. Einen vorhandenen Befehl mit removeSupportedMediaCommands entfernen.
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Wenn der Empfänger den aktualisierten MediaStatus vorbereitet, enthält er die Änderungen im Attribut supportedMediaCommands. Wenn der Status gesendet wird, aktualisieren die verbundenen Senderanwendungen die Schaltflächen in ihrer UI entsprechend.

Weitere Informationen zu unterstützten Medienbefehlen und Touchgeräten finden Sie im Leitfaden zu Accessing UI controls.

Status der Nutzeraktion verwalten

Wenn Nutzer mit der Benutzeroberfläche interagieren oder Sprachbefehle senden, können sie die Wiedergabe von Inhalten und Eigenschaften steuern, die mit dem wiedergegebenen Element zusammenhängen. Anfragen zur Steuerung der Wiedergabe werden automatisch vom SDK verarbeitet. Anfragen, die Eigenschaften des aktuell wiedergegebenen Elements ändern, z. B. ein LIKE-Befehl, müssen von der Empfängeranwendung verarbeitet werden. Das SDK stellt eine Reihe von APIs zur Verarbeitung dieser Anfragetypen zur Verfügung. Um diese Anfragen zu unterstützen, müssen Sie Folgendes tun:

  • Legen Sie MediaInformation userActionStates mit den Nutzereinstellungen fest, wenn ein Medienelement geladen wird.
  • Fangen Sie USER_ACTION-Nachrichten ab und bestimmen Sie die angeforderte Aktion.
  • Aktualisieren Sie MediaInformation UserActionState, um die UI zu aktualisieren.

Das folgende Snippet fängt die LOAD-Anfrage ab und füllt die MediaInformation der LoadRequestData aus. In diesem Fall gefällt dem Nutzer der geladene Inhalt.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

Das folgende Snippet fängt die Nachricht USER_ACTION ab und ruft das Back-End mit der angeforderten Änderung auf. Dann wird ein Aufruf gesendet, um UserActionState auf dem Empfänger zu aktualisieren.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

Das folgende Snippet simuliert einen Aufruf an einen Back-End-Dienst. Die Funktion prüft UserActionRequestData auf den vom Nutzer angeforderten Änderungstyp und führt nur dann einen Netzwerkaufruf aus, wenn die Aktion vom Back-End unterstützt wird.

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

Im folgenden Snippet wird das UserActionRequestData-Objekt verwendet und das UserActionState-Element der MediaInformation entweder hinzugefügt oder daraus entfernt. Durch das Aktualisieren der UserActionState von MediaInformation wird der Status der Schaltfläche geändert, die mit der angeforderten Aktion verknüpft ist. Diese Änderung spiegelt sich in der UI für Smart Display-Steuerungen, in der App für die Fernbedienung und in der Android TV-Benutzeroberfläche wider. Er wird auch über ausgehende MediaStatus-Nachrichten gesendet, um die Benutzeroberfläche des erweiterten Controllers für iOS- und Android-Absender zu aktualisieren.

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

Sprachbefehle

Die folgenden Medienbefehle werden derzeit im Web Receiver SDK auf Geräten mit integriertem Assistant unterstützt. Die Standardimplementierungen dieser Befehle finden Sie in cast.framework.PlayerManager.

Befehl Beschreibung
Wiedergeben Starte die Wiedergabe oder setze sie im pausierten Status fort.
Pausieren Aktuell wiedergegebenen Inhalt pausieren.
Zurück Zum vorherigen Medienelement in der Medienwarteschlange springen
Weiter Zum nächsten Medienelement in der Medienwarteschlange springen
Beenden Beendet die aktuell wiedergegebene Medien.
Keine wiederholen Hiermit können Sie das Wiederholen von Medienelementen in der Wiedergabeliste deaktivieren, nachdem das letzte Element in der Wiedergabeliste abgespielt wurde.
Einzelne wiederholen Wiederhole die aktuell wiedergegebenen Medien auf unbestimmte Zeit.
Alle wiederholen Alle Elemente in der Warteschlange wiederholen, sobald das letzte Element in der Warteschlange abgespielt wurde.
Alle wiederholen und Zufallsmix Nachdem das letzte Element in der Wiedergabeliste abgespielt wurde, musst du den Zufallsmix wiedergeben und alle Elemente in der Wiedergabeliste wiederholen.
Zufallsmix Medien in der Wiedergabeliste als Zufallsmix wiedergeben.
verwendest.
Untertitel EIN / AUS Untertitel für deine Medien aktivieren / deaktivieren „Aktivieren / Deaktivieren“ ist auch für die einzelnen Sprachen verfügbar.
Zur absoluten Zeit springen Springt zur angegebenen absoluten Zeit.
Sucht nach der Zeit relativ zur aktuellen Zeit Springt um den angegebenen Zeitraum vor oder zurück, relativ zur aktuellen Wiedergabezeit.
Noch einmal spielen Starte die aktuell wiedergegebene Medien neu oder gib das zuletzt abgespielte Element wieder, wenn gerade nichts wiedergegeben wird.
Wiedergabegeschwindigkeit festlegen Wiedergabegeschwindigkeit der Medien variieren. Dies sollte standardmäßig bearbeitet werden. Mit dem Nachrichtenabfangprogramm SET_PLAYBACK_RATE können Sie eingehende Ratenanfragen überschreiben.

Unterstützte Medienbefehle per Sprachbefehl

Wenn Sie verhindern möchten, dass ein Sprachbefehl einen Medienbefehl auf einem Gerät mit integriertem Assistant auslöst, müssen Sie zuerst die unterstützten Medienbefehle festlegen, die unterstützt werden sollen. Anschließend müssen Sie diese Befehle erzwingen. Dazu aktivieren Sie das Attribut CastReceiverOptions.enforceSupportedCommands. Die Benutzeroberfläche von Cast SDK-Sendern und Geräten mit Touchscreen wird entsprechend geändert. Wenn das Flag nicht aktiviert ist, werden die eingehenden Sprachbefehle ausgeführt.

Wenn Sie beispielsweise PAUSE in Ihren Senderanwendungen und Geräten mit Touchscreen zulassen, müssen Sie auch den Empfänger entsprechend konfigurieren. Nach der Konfiguration werden alle eingehenden Sprachbefehle gelöscht, wenn sie nicht in der Liste der unterstützten Befehle enthalten sind.

Im folgenden Beispiel geben wir die CastReceiverOptions an, wenn der CastReceiverContext gestartet wird. Wir haben Unterstützung für den Befehl PAUSE hinzugefügt und den Player so erzwungen, dass er nur diesen Befehl unterstützt. Wenn nun ein Sprachbefehl einen anderen Vorgang wie SEEK anfordert, wird dieser abgelehnt. Der Nutzer wird benachrichtigt, dass der Befehl noch nicht unterstützt wird.

const context = cast.framework.CastReceiverContext.getInstance();

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

Sie können für jeden Befehl, den Sie einschränken möchten, eine eigene Logik anwenden. Entfernen Sie das Flag enforceSupportedCommands. Sie können dann für jeden Befehl, den Sie einschränken möchten, die eingehende Nachricht abfangen. Hier fangen wir die vom SDK bereitgestellte Anfrage ab, damit SEEK-Befehle, die an Geräte mit integriertem Assistant gesendet werden, in deiner Web Receiver-Anwendung keine Suche auslösen.

Für Medienbefehle, die von Ihrer Anwendung nicht unterstützt werden, geben Sie einen entsprechenden Fehlergrund wie NOT_SUPPORTED zurück.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

Hintergrundwiedergabe von Sprachaktivitäten

Wenn die Cast-Plattform den Ton deiner App aufgrund von Assistant-Aktivitäten wie dem Anhören der Spracheingabe oder dem Sprechen im Hintergrund abspielt, wird beim Start der Aktivität eineFocusState Nachricht von NOT_IN_FOCUS an den Web Receiver gesendet. Wenn die Aktivität endet, wird eine weitere Nachricht mit IN_FOCUS gesendet. Abhängig von Ihrer App und den wiedergegebenen Medien empfiehlt es sich, Medien zu pausieren, wenn FocusState den Status NOT_IN_FOCUS hat. Dafür wird der Nachrichtentyp FOCUS_STATE abgefangen.

Beispielsweise ist es hilfreich, die Hörbuchwiedergabe zu pausieren, wenn Assistant auf eine Nutzeranfrage reagiert.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

Sprachspezifische Untertitelsprache

Wenn ein Nutzer die Sprache für Untertitel nicht explizit angibt, wird für Untertitel dieselbe Sprache verwendet, in der der Befehl gesprochen wurde. In diesen Szenarien gibt der Parameter isSuggestedLanguage der eingehenden Nachricht an, ob die zugehörige Sprache vom Nutzer vorgeschlagen oder explizit angefordert wurde.

Beispielsweise ist isSuggestedLanguage für den Befehl „Ok Google, schalte Untertitel aktivieren“ auf true gesetzt, da die Sprache aus der Sprache abgeleitet wurde, in der der Befehl gesprochen wurde. Wenn die Sprache explizit angefordert wird, z. B. mit „Hey Google, aktiviere englische Untertitel“, wird isSuggestedLanguage auf false gesetzt.

Metadaten- und Sprachstreaming

Sprachbefehle werden zwar standardmäßig vom Web Receiver verarbeitet, Sie sollten jedoch darauf achten, dass die Metadaten für Ihre Inhalte vollständig und genau sind. Dadurch wird sichergestellt, dass Sprachbefehle von Assistant ordnungsgemäß verarbeitet werden und die Metadaten auf neuen Benutzeroberflächen wie der Google Home App und Smart Displays wie Google Home Hub ordnungsgemäß angezeigt werden.

Stream-Übertragung

Das Beibehalten des Sitzungsstatus ist die Grundlage der Streamübertragung, bei der Nutzer vorhandene Audio- und Videostreams mithilfe von Sprachbefehlen, der Google Home App oder Smart Displays auf andere Geräte verschieben können. Die Wiedergabe von Medien wird auf einem Gerät (der Quelle) beendet und auf einem anderen (dem Ziel) fortgesetzt. Jedes Übertragungsgerät mit der neuesten Firmware kann als Quellen oder Ziele bei einer Stream-Übertragung dienen.

Der Ereignisablauf für die Streamübertragung ist:

  1. Auf dem Quellgerät:
    1. Die Medienwiedergabe wird beendet.
    2. Die Web Receiver-Anwendung erhält einen Befehl zum Speichern des aktuellen Medienstatus.
    3. Die Web Receiver-Anwendung wurde heruntergefahren.
  2. Auf dem Zielgerät:
    1. Die Web Receiver-Anwendung wurde geladen.
    2. Die Web Receiver-Anwendung erhält einen Befehl zum Wiederherstellen des gespeicherten Medienstatus.
    3. Die Medienwiedergabe wird fortgesetzt.

Zu den Elementen des Medienstatus gehören:

  • Spezifische Position oder Zeitstempel des Songs, Videos oder Medienelements
  • Er befindet sich in einer größeren Wiedergabeliste, z. B. in einer Playlist oder einem Künstlerradio.
  • Der authentifizierte Nutzer.
  • Wiedergabestatus (z. B. Wiedergabe oder Pause)

Stream-Übertragung aktivieren

So implementieren Sie die Streamübertragung für Ihren Webempfänger:

  1. Aktualisieren Sie supportedMediaCommands mit dem Befehl STREAM_TRANSFER:
    playerManager.addSupportedMediaCommands(
    cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. Überschreiben Sie optional die Nachrichten-Interceptor SESSION_STATE und RESUME_SESSION, wie unter Sitzungsstatus beibehalten beschrieben. Überschreiben Sie diese nur, wenn benutzerdefinierte Daten als Teil des Sitzungs-Snapshots gespeichert werden müssen. Andernfalls unterstützt die Standardimplementierung zum Beibehalten von Sitzungsstatus die Streamübertragung.

Sitzungsstatus beibehalten

Das Web Receiver SDK bietet eine Standardimplementierung für Web Receiver-Apps, um den Sitzungsstatus beizubehalten. Dazu wird ein Snapshot des aktuellen Medienstatus erstellt, der Status in eine Ladeanfrage umgewandelt und die Sitzung mit der Ladeanfrage fortgesetzt.

Die vom Webempfänger generierte Ladeanfrage kann bei Bedarf im Nachrichtenabfangprogramm SESSION_STATE überschrieben werden. Wenn Sie der Ladeanfrage benutzerdefinierte Daten hinzufügen möchten, sollten Sie sie in loadRequestData.customData einfügen.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

Die benutzerdefinierten Daten können im Nachrichtenabfangen RESUME_SESSION aus loadRequestData.customData abgerufen werden.

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

Inhalte vorab laden

Web Receiver unterstützt das Vorabladen von Medienelementen nach dem aktuell wiedergegebenen Element in der Warteschlange.

Beim Vorabladen werden mehrere Segmente der kommenden Elemente vorab heruntergeladen. Die Spezifikation erfolgt über den Wert preloadTime im Objekt QueueItem. Der Standardwert ist 20 Sekunden, wenn nicht angegeben. Die Zeit wird in Sekunden bezogen auf das Ende des aktuell wiedergegebenen Elements angegeben . Nur positive Werte sind gültig. Wenn der Wert beispielsweise 10 Sekunden beträgt, wird dieses Element 10 Sekunden vor dem Ende des vorherigen Elements vorab geladen. Wenn die Zeit für das Vorabladen länger ist als die verbleibende Zeit für „currentItem“, erfolgt das Vorabladen so schnell wie möglich. Wenn also ein sehr großer Wert für das Vorabladen für „queueItem“ angegeben ist, könnte dies bewirken, dass das nächste Element bei jeder Wiedergabe des aktuellen Elements bereits vorab geladen wird. Die Einstellung und Auswahl werden jedoch den Entwicklern überlassen, da sich dieser Wert auf die Bandbreite und die Streamingleistung des aktuell wiedergegebenen Elements auswirken kann.

Das Vorabladen funktioniert standardmäßig bei HLS-, DASH- und Smooth Streaming-Inhalten.

Normale MP4-Video- und -Audiodateien wie MP3 werden nicht vorab geladen, da Übertragungsgeräte nur ein Medienelement unterstützen und nicht zum Vorabladen verwendet werden können, während ein vorhandenes Inhaltselement wiedergegeben wird.

Benutzerdefinierte Nachrichten

Der Nachrichtenaustausch ist die wichtigste Interaktionsmethode für Web Receiver-Anwendungen.

Ein Absender sendet Nachrichten an einen Webempfänger über die Sender-APIs der vom Absender verwendeten Plattform (Android, iOS, Web). Das Ereignisobjekt (die Manifestation einer Nachricht), das an die Ereignis-Listener übergeben wird, hat ein Datenelement (event.data), dessen Daten die Attribute des jeweiligen Ereignistyps übernehmen.

Eine Web Receiver-Anwendung kann Nachrichten in einem angegebenen Namespace überwachen. Dadurch soll die Web Receiver-Anwendung das Namespace-Protokoll unterstützen. Alle verbundenen Absender, die über diesen Namespace kommunizieren möchten, können dann das entsprechende Protokoll verwenden.

Alle Namespaces werden durch einen String definiert und müssen mit „urn:x-cast:“ beginnen, gefolgt von einem beliebigen String. Beispiel: „urn:x-cast:com.example.cast.mynamespace“.

Hier ist ein Code-Snippet für den Webempfänger, um benutzerdefinierte Nachrichten von verbundenen Absendern anzuhören:

const context = cast.framework.CastReceiverContext.getInstance();

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

In ähnlicher Weise können Web Receiver-Anwendungen Absender über den Status des Web Receiver informieren, indem sie Nachrichten an verbundene Sender senden. Eine Anwendung für den Webempfänger kann Nachrichten mit sendCustomMessage(namespace, senderId, message) in CastReceiverContext senden. Ein Webempfänger kann Nachrichten an einen einzelnen Absender senden, entweder als Antwort auf eine empfangene Nachricht oder aufgrund einer Änderung des Anwendungsstatus. Neben Punkt-zu-Punkt-Nachrichten (mit einer Beschränkung von 64 KB) kann ein Webempfänger auch Nachrichten an alle verbundenen Absender senden.

Streamen für Audiogeräte

Weitere Informationen zur reinen Audiowiedergabe finden Sie in der Anleitung zu Google Cast für Audiogeräte.

Android TV

In diesem Abschnitt wird erläutert, wie der Google Web Receiver Ihre Eingaben zur Wiedergabe verwendet. Außerdem wird die Kompatibilität mit Android TV erläutert.

Anwendung in die Fernbedienung einbinden

Der auf dem Android TV-Gerät ausgeführte Google Web Receiver übersetzt Eingaben der Steuerungseingaben des Geräts (d.h. die Fernbedienung per Handheld) als Nachrichten zur Medienwiedergabe, die für den urn:x-cast:com.google.cast.media-Namespace definiert sind, wie unter Nachrichten zur Medienwiedergabe beschrieben. Ihre App muss diese Nachrichten unterstützen, um die Medienwiedergabe der App zu steuern und eine grundlegende Wiedergabesteuerung über die Steuereingänge von Android TV zu ermöglichen.

Richtlinien zur Kompatibilität mit Android TV

Im Folgenden findest du einige Empfehlungen und häufige Fehler, die du vermeiden solltest, damit deine App mit Android TV kompatibel ist:

  • Der User-Agent-String enthält sowohl „Android“ als auch „CrKey“. Einige Websites leiten möglicherweise zu einer rein mobilen Website weiter, weil sie das Label „Android“ erkennen. Gehen Sie nicht davon aus, dass „Android“ im User-Agent-String immer auf einen mobilen Nutzer verweist.
  • Der Medienstapel von Android verwendet möglicherweise transparentes GZIP zum Abrufen von Daten. Achten Sie darauf, dass Ihre Mediendaten auf Accept-Encoding: gzip reagieren können.
  • HTML5-Medienereignisse von Android TV können zu anderen Zeiten ausgelöst werden als Chromecast. Dadurch können Probleme auftauchen, die bei Chromecast ausgeblendet waren.
  • Verwenden Sie zum Aktualisieren der Medien medienbezogene Ereignisse, die von <audio>/<video>-Elementen wie timeupdate, pause und waiting ausgelöst werden. Vermeiden Sie netzwerkbezogene Ereignisse wie progress, suspend und stalled, da diese in der Regel plattformabhängig sind. Weitere Informationen zur Verarbeitung von Medienereignissen bei Ihrem Empfänger finden Sie unter Medienereignisse.
  • Beim Konfigurieren der HTTPS-Zertifikate der Empfängerwebsite müssen Zwischenzertifikate von Zertifizierungsstellen einbezogen werden. Auf der SSL-Testseite von Qualsys können Sie prüfen, ob der Pfad des vertrauenswürdigen Zertifizierungspfads für Ihre Website ein CA-Zertifikat mit der Bezeichnung „zusätzlicher Download“ enthält. In diesem Fall kann es auf Android-basierten Plattformen möglicherweise nicht geladen werden.
  • Während Chromecast die Seite des Empfängers in einer 720p-Grafikebene anzeigt, können andere Übertragungsplattformen wie Android TV die Seite mit einer Auflösung von bis zu 1080p anzeigen. Achte darauf, dass die Empfängerseite bei verschiedenen Auflösungen korrekt skaliert wird.