Zentrale Funktionen zu Ihrem benutzerdefinierten Web-Receiver hinzufügen

Diese Seite enthält Code-Snippets und Beschreibungen der Funktionen, die für benutzerdefinierte Webempfänger-Apps verfügbar sind.

Hinweis:Wir empfehlen Folgendes:

• Codelab für den Cast Web Receiver: Detaillierte Anleitung zum Erstellen einer für Google Cast optimierten Web Receiver-App mit dem Google Cast SDK, die Videostreams empfangen kann.
• CastReceiver-Beispiel-App (GitHub): Hier können Sie diese Referenz-Beispiel-App ausführen, aufrufen und aufrufen, die den UX-Richtlinien und der Design-Checkliste entspricht.

1. Ein cast-media-player-Element, das die im Web Receiver integrierte Player-UI darstellt.
2. Benutzerdefinierter CSS-ähnlicher Stil für das Element cast-media-player, 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 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.

Hinweis :Die Verwendung des HTML-Elements cast-media-player wird dringend empfohlen, da es den gesamten UI-Status des Players zusammen mit seinem Stil verarbeitet.

Anwendungskonfiguration und -optionen

Anwendung konfigurieren

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

Das folgende Beispiel zeigt, wie Sie das Standardverhalten zur Erkennung, ob eine Absenderverbindung noch aktiv ist, überschreiben. 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. Dies kann bei der Fehlerbehebung hilfreich sein, da die Web Receiver-App die Chrome Remote Debugger-Sitzung nicht schließt, wenn keine verbundenen Absender mit dem Status IDLE vorhanden sind.

Hinweis: Produktionsanwendungen von Web Receiver-Anwendungen sollten maxInactivity nicht festlegen und stattdessen den Standardwert verwenden.

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 Player ausgewertet. Player werden jedes Mal erstellt, wenn ein neuer Ladevorgang an das Web Receiver SDK übergeben wird. Änderungen am PlaybackConfig, nachdem der Player erstellt wurde, 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 angewendet oder bis sie wieder überschrieben wird.
• PlayerManager.setMediaPlaybackInfoHandler(), um zusätzliche Konfigurationen nur für das Medienelement anzuwenden, das zusätzlich zu den aktuellen Konfigurationen geladen wird. Der Handler wird kurz vor der Spielererstellung aufgerufen. Die hier vorgenommenen Änderungen sind nicht dauerhaft und werden nicht in Abfragen an getPlaybackConfig() einbezogen. Wenn das nächste Medienelement geladen wird, wird dieser Handler erneut 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-Zugriffssteuerungsanfragen mithilfe von Anmeldedaten wie Cookies oder Autorisierungsheadern gestellt werden sollen.

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 in PlayerManager überschrieben wird. Mit dieser Einstellung wird der Player so konfiguriert, dass die Inhaltswiedergabe nach dem Laden eines Segments fortgesetzt wird.

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 mit dem Handler für Medienwiedergabeinformationen für eine bestimmte Ladeanfrage überschrieben wird. Der Handler ruft eine von der Anwendung implementierte Methode getLicenseUrlForMedia auf, um die 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 Player-Ereignisse verarbeiten. Der Event-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 nützlich 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 übertragen wird, können Sie das Ereignis mit der folgenden Logik verarbeiten:

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

Hinweis :Das Web Receiver-Framework verfolgt automatisch, wenn ein Absender eine Verbindung herstellt oder trennt. In deiner Web Receiver-Logik ist kein expliziter SENDER_DISCONNECTED-Event-Listener erforderlich.

Abfangen von Nachrichten

Mit dem Web Receiver SDK kann die Web Receiver-App Nachrichten abfangen und benutzerdefinierten Code für diese Nachrichten ausführen. Das Abfangen von Nachrichten verwendet den Parameter cast.framework.messages.MessageType, 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 verhindert, dass der Standard-Nachrichten-Handler aufgerufen wird. Weitere Informationen finden Sie unter Medien laden.

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

Achtung :Sie dürfen das Attribut queueData von LoadRequestData im Interceptor LOAD nicht hinzufügen oder ändern. Dies hat keine Auswirkungen auf die Wiedergabe, da das queueData bereits gelesen und auf die Warteschlange angewendet wurde. Weitere Informationen finden Sie in der Anleitung zur Warteschlange.

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 Fehler beim Abfangen von Nachrichten auftreten, sollte Ihre Web Receiver-Anwendung einen entsprechenden cast.framework.messages.ErrorType und cast.framework.messages.ErrorReason 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 im Vergleich zum Event-Listener

Im Folgenden finden Sie einige wichtige Unterschiede zwischen dem Abfangen von Nachrichten und dem Event-Listener:

• Ein Event-Listener erlaubt es Ihnen nicht, die Anfragedaten zu ändern.
• Ein Ereignis-Listener eignet sich am besten zum Auslösen von Analysen oder einer benutzerdefinierten Funktion.

Hinweis: Ein Event-Listener kann auch verwendet werden, um mithilfe der Aufzählung CORE, DEBUG oder FINE eine übergeordnete Liste von Ereignissen zu überwachen.

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

• Mit dem Abfangen von Nachrichten können Sie eine Nachricht abhören, sie abfangen und die Anfragedaten selbst ändern.
• Das Abfangen von Nachrichten eignet sich am besten für die Verarbeitung benutzerdefinierter Logik in Bezug auf Anfragedaten.

Medien werden geladen

MediaInformation bietet zahlreiche Attribute zum Laden von Medien in die cast.framework.messages.MessageType.LOAD-Nachricht, einschließlich entity, contentUrl und contentId.

• entity ist das empfohlene Attribut, das Sie in Ihrer Implementierung sowohl für Ihre Absender- als auch für die Empfänger-Apps verwenden sollten. Die Property ist eine Deeplink-URL, bei der es sich entweder um eine Playlist oder um Medieninhalte handeln kann. Die Anwendung sollte diese URL parsen und mindestens eines der beiden anderen Felder ausfüllen.
• contentUrl entspricht der URL, die der Player zum Laden des Inhalts verwendet. Diese URL könnte beispielsweise auf ein DASH-Manifest verweisen.
• Beim contentId kann es sich entweder um eine abspielbare Inhalts-URL (ähnlich der contentUrl-Property) oder um eine eindeutige Kennung für den geladenen Inhalt oder die Playlist handeln. Wenn Sie dieses Attribut als Kennung verwenden, sollte Ihre Anwendung eine abspielbare URL im contentUrl ausfüllen.

Es wird empfohlen, entity zum Speichern der realen ID oder der Schlüsselparameter und contentUrl für die URL der Medien zu verwenden. Ein Beispiel dafür wird im folgenden Snippet gezeigt, in dem entity in der LOAD-Anfrage vorhanden ist und das 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

Mit der Methode getDeviceCapabilities werden Geräteinformationen zum verbundenen Übertragungsgerät und zum verbundenen 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 Tasten IS_HDR_SUPPORTED und 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 Absenderanwendungen (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 Anwendungs-UI über den Status von Nutzeraktionen aktualisieren und optional die Änderungen senden kann, um Back-End-Dienste zu aktualisieren.

Unterstützte Medienbefehle

Der Status der UI-Steuerelemente wird von MediaStatus.supportedMediaCommands für erweiterte Sender-Controller, Empfänger- und Fernbedienungs-Apps, die auf Touchgeräten ausgeführt werden, sowie von Empfänger-Apps auf Android TV-Geräten gesteuert. Wenn ein bestimmtes bitweises Command im Attribut aktiviert ist, werden die mit dieser Aktion verknüpften Schaltflächen aktiviert. Wenn der Wert nicht festgelegt ist, ist die Schaltfläche deaktiviert. Diese Werte können im Web Receiver wie folgt geändert werden:

1. Verwenden Sie PlayerManager.setSupportedMediaCommands, um den spezifischen 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 die aktualisierte MediaStatus vorbereitet, werden die Änderungen im Attribut supportedMediaCommands berücksichtigt. Wenn der Status gesendet wird, aktualisieren die verbundenen Absender-Apps die Schaltflächen in ihrer UI entsprechend.

Hinweis :Änderungen an supportedMediaCommands wirken sich nicht auf die Art der angezeigten Schaltfläche aus. Diese werden direkt in den Absender-Apps (iOS, Android) und in der Controls API des Empfängers festgelegt. Die einzige Ausnahme, die für diese Änderungen supportedMediaCommands verwendet, sind die Medienwiedergabekarten auf dem Startbildschirm von Smart Displays.

Weitere Informationen zu unterstützten Medienbefehlen und Touchgeräten finden Sie in der Accessing UI controls-Anleitung.

Status von Nutzeraktionen verwalten

Wenn Nutzer mit der Benutzeroberfläche interagieren oder Sprachbefehle senden, können sie die Wiedergabe der Inhalte und Eigenschaften im Zusammenhang mit dem wiedergegebenen Element steuern. Anfragen zur Steuerung der Wiedergabe werden automatisch vom SDK verarbeitet. Bei Anfragen, die Attribute für das aktuell wiedergegebene Element ändern, z. B. ein LIKE-Befehl, müssen diese von der Empfängeranwendung verarbeitet werden. Das SDK bietet eine Reihe von APIs, um diese Arten von Anfragen zu verarbeiten. Zur Unterstützung dieser Anfragen müssen folgende Schritte ausgeführt werden:

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

Hinweis: Bei Bedarf können Sie die Aktion mit POST an alle relevanten Back-Ends senden, um die Nutzereinstellung beizubehalten.

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 Inhalt, der geladen wird.

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 verarbeitet das Back-End mit der angeforderten Änderung. Anschließend wird ein Aufruf durchgeführt, um die UserActionState beim 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, um die Art der Änderung zu sehen, die der Nutzer angefordert hat, 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));
    }
  });
}

Das folgende Snippet verwendet UserActionRequestData und fügt entweder UserActionState aus MediaInformation hinzu oder entfernt es daraus. Wenn Sie UserActionState von MediaInformation aktualisieren, ändert sich der Status der Schaltfläche, die mit der angeforderten Aktion verknüpft ist. Diese Änderung spiegelt sich in der UI für Smart Displays, der Fernbedienungs-App und der Android TV-Benutzeroberfläche wider. Er wird auch über ausgehende MediaStatus-Nachrichten gesendet, um die UI 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 für Geräte mit integriertem Assistant unterstützt. Die Standardimplementierungen dieser Befehle finden Sie in cast.framework.PlayerManager.

Befehl	Beschreibung
Wiedergeben	Wiedergabe im Status „Pausiert“ starten oder fortsetzen
Pausieren	Aktuell wiedergegebene Inhalte pausieren
Zurück	Zum vorherigen Medienelement in der Wiedergabeliste springen.
Weiter	Zum nächsten Medienelement in der Medienwarteschlange springen.
Beenden	Stoppt die aktuell wiedergegebene Mediendatei.
Keinen wiederholen	Wiederholung von Medienelementen in der Wiedergabeliste deaktivieren, sobald das letzte Element der Wiedergabeliste abgespielt wurde
Einzel wiederholen	Die aktuell abgespielte Medienwiedergabe auf unbestimmte Zeit wiederholen.
Alle wiederholen	Wiederholen Sie alle Elemente in der Wiedergabeliste, sobald das letzte Element abgespielt wurde.
Alle wiederholen und Zufallsmix	Erstelle einen Zufallsmix der Wiedergabeliste und wiederhole alle Elemente in der Wiedergabeliste, sobald das letzte Element abgespielt wurde.
Zufallsmix	Du kannst die Medien in deiner Medienwarteschlange als Zufallsmix wiedergeben. Hinweis:Mit der Markierung shuffle kannst du die Medien vor der Wiedergabe als Zufallsmix wiedergeben, wenn sie in der loadRequestData der LOAD-Nachricht festgelegt ist.
Untertitel aktivieren / deaktivieren	Untertitel für Ihre Medien aktivieren oder deaktivieren Die Funktion „Aktivieren / Deaktivieren“ ist auch für die einzelnen Sprachen verfügbar.
Zur absoluten Zeit springen	Springt zur angegebenen absoluten Zeit.
Spulen auf Zeit relativ zur aktuellen Zeit	Springt im angegebenen Zeitraum zur aktuellen Wiedergabezeit vor oder zurück.
Noch einmal spielen	Starte die gerade wiedergegebene Mediendatei neu oder spiele das zuletzt wiedergegebene Medienelement ab, wenn gerade keine Medien abgespielt werden.
Wiedergaberate festlegen	Variieren Sie die Medienwiedergaberate. Dies sollte standardmäßig berücksichtigt werden. Sie können den Nachrichten-Abfangende SET_PLAYBACK_RATE verwenden, um eingehende Ratenanfragen zu überschreiben.

Unterstützte Medienbefehle per Sprachbefehl

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

Wenn Sie beispielsweise PAUSE von Ihren Absenderanwendungen und Touch-fähigen Geräten zulassen, müssen Sie auch den Empfänger entsprechend konfigurieren. Nach der Konfiguration werden eingehende Sprachbefehle verworfen, wenn sie nicht in der Liste der unterstützten Befehle enthalten sind.

Im folgenden Beispiel stellen wir das CastReceiverOptions bereit, wenn CastReceiverContext gestartet wird. Wir unterstützen jetzt den Befehl PAUSE und haben erzwungen, dass der Player nur diesen Befehl unterstützt. Wenn ein Sprachbefehl jetzt einen anderen Vorgang anfordert, z. B. SEEK, wird er 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 separate Logik anwenden. Entfernen Sie das Flag enforceSupportedCommands und bei jedem Befehl, den Sie einschränken möchten, können Sie die eingehende Nachricht abfangen. Hier fangen wir die vom SDK bereitgestellte Anfrage ab, sodass SEEK-Befehle, die an Geräte mit integriertem Assistant gesendet werden, keine Suche in Ihrer Web Receiver-Anwendung auslösen.

Geben Sie für Medienbefehle, die von Ihrer Anwendung nicht unterstützt werden, einen entsprechenden Fehlergrund zurück, z. B. NOT_SUPPORTED.

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 durch Sprachaktivität

Wenn die Cast-Plattform den Ton Ihrer App aufgrund von Assistant-Aktivitäten wie dem Vorlesen von Nutzerkommentaren oder der Spracheingabe im Hintergrund abspielt, wird beim Start der Aktivität die FocusState-Nachricht NOT_IN_FOCUS an die Web Receiver-App gesendet. Eine weitere Nachricht mit IN_FOCUS wird gesendet, wenn die Aktivität endet. Je nach Anwendung und wiedergegebenen Medien können Sie Medien pausieren, wenn FocusState den Wert NOT_IN_FOCUS hat, indem Sie den Nachrichtentyp FOCUS_STATE abfangen.

Beispielsweise ist es hilfreich, die Wiedergabe eines Hörbuchs anzuhalten, 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 die Untertitel nicht explizit angibt, wird für die 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, aktiviere die Untertitel“ 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 „Ok Google, aktiviere englische Untertitel“, wird isSuggestedLanguage auf false gesetzt.

Metadaten und Sprachstreaming

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

Stream-Übertragung

Hinweis :Audio-Web-Receiver unterstützen standardmäßig die Stream-Ausweitung, bei der der Sitzung zusätzliche für Google Cast optimierte Geräte hinzugefügt werden. Video-Web-Receiver müssen die Schritte in diesem Abschnitt ausführen, um die Stream-Übertragung zu unterstützen.

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

Der Ereignisablauf bei der Stream-Übertragung sieht so aus:

1. Auf dem Quellgerät:
   1. Medienwiedergabe wird beendet.
   2. Die Web Receiver-Anwendung empfängt einen Befehl zum Speichern des aktuellen Medienstatus.
   3. Die Web Receiver-Anwendung wurde beendet.
2. Auf dem Zielgerät:
   1. Die Web Receiver-Anwendung wird 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:

• Bestimmte Position oder der Zeitstempel des Songs, Videos oder Medienelements
• Das Video wird in eine größere Warteschlange eingereiht, z. B. in einer Playlist oder im Radio des Künstlers.
• Der authentifizierte Nutzer.
• Wiedergabestatus (z. B. „Wiedergabe“ oder „Pausiert“)

Stream-Übertragung aktivieren

So implementieren Sie die Stream-Übertragung für Ihren Web Receiver:

1. Aktualisieren Sie supportedMediaCommands mit dem Befehl STREAM_TRANSFER:

   playerManager.addSupportedMediaCommands(
   cast.framework.messages.Command.STREAM_TRANSFER, true);

2. Überschreiben Sie optional die Nachrichten-Abfangenden 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 des Sitzungsstatus die Streamübertragung.

Sitzungsstatus beibehalten

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

Die vom Web Receiver generierte Ladeanfrage kann bei Bedarf im SESSION_STATE-Nachrichtenabfanger überschrieben werden. Wenn Sie der Ladeanfrage benutzerdefinierte Daten hinzufügen möchten, empfehlen wir, sie in loadRequestData.customData einzufü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 aus loadRequestData.customData im Nachrichten-Abfangende RESUME_SESSION 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 aktuellen Wiedergabeelement in der Warteschlange.

Beim Vorabladen werden mehrere Segmente der kommenden Elemente vorab heruntergeladen. Die Angabe erfolgt für den preloadTime-Wert im QueueItem-Objekt (standardmäßig 20 Sekunden, wenn kein Wert angegeben ist). Die Zeit wird in Sekunden relativ zum Ende des gerade wiedergegebenen Elements ausgedrückt . 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 den Vorabladen größer ist als die für das aktuelle Element verbleibende Zeit, wird das Vorabladen so schnell wie möglich ausgeführt. Wenn also für das QueueItem ein sehr hoher Wert für das Vorabladen angegeben ist, könnte beim Abspielen des aktuellen Elements bereits das nächste Element vorab geladen werden. Die Einstellung und Wahl dieses Elements lassen wir jedoch dem Entwickler überlassen, da dieser Wert die Bandbreite und die Streamingleistung des aktuell wiedergegebenen Elements beeinflussen kann.

Das Vorabladen funktioniert standardmäßig für HLS-, DASH- und Smooth Streaming-Content.

Reguläre MP4-Video- und -Audiodateien wie MP3 werden nicht vorab geladen, da Cast-Geräte nur ein einziges Medienelement unterstützen und nicht zum Vorabladen verwendet werden können, während ein vorhandenes Inhaltselement noch abgespielt wird.

Benutzerdefinierte Nachrichten

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

Ein Absender sendet Nachrichten an einen Webempfänger, indem er die Absender-APIs für die vom Absender verwendete Plattform verwendet (Android, iOS, Web). Das Ereignisobjekt (die Manifestation einer Nachricht), das an die Ereignis-Listener übergeben wird, hat ein Datenelement (event.data), bei dem die Daten die Attribute des jeweiligen Ereignistyps annehmen.

Eine Web Receiver-Anwendung kann Nachrichten in einem bestimmten Namespace überwachen. Dadurch wird angenommen, dass die Web Receiver-Anwendung dieses Namespace-Protokoll unterstützt. Anschließend müssen alle verbundenen Absender, die über diesen Namespace kommunizieren möchten, 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“.

Hinweis :Der Namespace für Mediennachrichten „urn:x-cast:com.google.cast.media“ ist reserviert. Mediennachrichten, die mit den Cast APIs sowohl beim Absender als auch beim Webempfänger gesendet werden, verwenden standardmäßig das Media-Namespace-Protokoll. Weitere Informationen zu Mediennachrichten finden Sie unter Medien und Player.

Hier ist ein Code-Snippet für Web Receiver, mit dem benutzerdefinierte Nachrichten von verbundenen Absendern abgerufen werden können:

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

Ebenso können Web Receiver-Anwendungen Absender über den Status des Web Receivers auf dem Laufenden halten, indem sie Nachrichten an verbundene Absender senden. Eine Web Receiver-Anwendung kann Nachrichten mit sendCustomMessage(namespace, senderId, message) auf CastReceiverContext senden. Ein Web Receiver kann Nachrichten an einen einzelnen Absender senden, entweder als Antwort auf eine empfangene Nachricht oder aufgrund einer Änderung des Anwendungsstatus. Über die Punkt-zu-Punkt-Nachricht hinaus (mit einem Limit von 64 KB) kann ein Web Receiver auch Nachrichten an alle verbundenen Absender senden.

Streaming für Audiogeräte

Informationen zur Unterstützung bei der reinen Audiowiedergabe finden Sie im Leitfaden zu Google Cast für Audiogeräte.

Android TV

In diesem Abschnitt wird erläutert, wie 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 Google Web Receiver, der auf dem Android TV-Gerät ausgeführt wird, übersetzt die Eingabe von den Steuereingaben des Geräts (d.h. mit einer Handheld-Fernbedienung) als Nachrichten zur Medienwiedergabe, die für den Namespace urn:x-cast:com.google.cast.media definiert sind, wie unter Nachrichten zur Medienwiedergabe beschrieben. Ihre App muss diese Nachrichten unterstützen, um die Medienwiedergabe in der App zu steuern und eine grundlegende Steuerung der Wiedergabe über die Steuereingaben von Android TV zu ermöglichen.

Richtlinien für die Kompatibilität mit Android TV

Im Folgenden finden Sie einige Empfehlungen und häufige Fehler, die Sie vermeiden sollten, um die Kompatibilität Ihrer App mit Android TV sicherzustellen:

• Der User-Agent-String enthält sowohl „Android“ als auch „CrKey“. Einige Websites leiten möglicherweise zu einer Website nur für Mobilgeräte weiter, weil sie das Label „Android“ erkennen. Gehen Sie nicht davon aus, dass „Android“ im User-Agent-String immer einen mobilen Nutzer angibt.
• Der Mediastack von Android kann transparente GZIP zum Abrufen von Daten verwenden. Achten Sie darauf, dass Ihre Mediendaten auf Accept-Encoding: gzip reagieren können.
• HTML5-Medienereignisse von Android TV können zu unterschiedlichen Timings ausgelöst werden als Chromecast. Dies kann zu Problemen führen, die bei Chromecast versteckt waren.
• Verwenden Sie beim Aktualisieren der Medien medienbezogene Ereignisse, die durch <audio>/<video>-Elemente wie timeupdate, pause und waiting ausgelöst werden. Vermeiden Sie die Verwendung von netzwerkbezogenen Ereignissen wie progress, suspend und stalled, da diese in der Regel plattformabhängig sind. Weitere Informationen zur Verarbeitung von Medienereignissen im Receiver finden Sie unter Medienereignisse.
• Achten Sie beim Konfigurieren der HTTPS-Zertifikate der Empfängerwebsite darauf, Zwischen-CA-Zertifikate anzugeben. Auf der Qualsys SSL-Testseite können Sie prüfen, ob der vertrauenswürdige Zertifizierungspfad für Ihre Website ein CA-Zertifikat mit dem Label „zusätzlicher Download“ enthält. In diesem Fall wird es auf Android-basierten Plattformen möglicherweise nicht geladen.
• Während Chromecast die Empfängerseite in einer 720p-Grafikebene anzeigt, können andere Cast-Plattformen, einschließlich Android TV, die Seite mit einer Auflösung von bis zu 1080p anzeigen. Sorgen Sie dafür, dass Ihre Empfängerseite bei verschiedenen Auflösungen problemlos skaliert wird.