Ihrem benutzerdefinierten Webempfänger grundlegende Funktionen hinzufügen

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

Hinweis: Wir empfehlen Folgendes:

• Codelab zu Cast Web Receiver – Schritt-für-Schritt-Anleitung zum Erstellen einer für Google Cast optimierten Web Receiver-App mit dem Google Cast SDK, das Videoübertragungen empfangen kann.
• CastReceiver-Beispiel-App (GitHub) – Diese Beispiel-App, die den UX-Richtlinien und der Design-Checkliste entspricht, ausführen, aufrufen und ansehen.

1. Ein cast-media-player-Element, das die integrierte Player-Benutzeroberfläche darstellt, die mit Web Receiver bereitgestellt wird.
2. Benutzerdefinierte CSS-ähnliche Stile 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 Verarbeitung von Ereignissen.
5. Wiedergabeliste für automatische Wiedergabe.
6. Optionen zum Konfigurieren der Wiedergabe.
7. Optionen zum Einstellen 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: Es wird dringend empfohlen, das HTML-Element cast-media-player zu verwenden, da es den gesamten UI-Status des Players zusammen mit seinem Stil verarbeitet.

Anwendungskonfiguration und Optionen

Die CastReceiverContext ist die äußerste Klasse, die dem Entwickler zugänglich ist. Sie verwaltet das Laden der zugrunde liegenden Bibliotheken und übernimmt die Initialisierung des Web Receiver SDK.

Wenn die Web Receiver API erkennt, dass ein Absender nicht verbunden ist, wird das Ereignis SENDER_DISCONNECTED ausgelöst. Wenn der Webempfänger nicht wie in den maxInactivity Sekunden beschrieben mit dem Absender kommunizieren konnte, wird auch das Ereignis SENDER_DISCONNECTED ausgelöst. Bei der Entwicklung empfiehlt es sich, maxInactivity auf einen hohen Wert zu setzen, damit die Web Receiver App beim Debuggen der App mit dem Chrome Remote Debugger nicht geschlossen wird:

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

Für eine veröffentlichte Web Receiver-Anwendung ist es jedoch besser, maxInactivity nicht festzulegen und stattdessen auf den Standardwert zu vertrauen. Die Optionen für Webempfänger werden in der Anwendung nur einmal festgelegt.

Die andere Konfiguration ist cast.framework.PlaybackConfig. Folgende Optionen sind verfügbar:

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

Diese Konfiguration wirkt sich auf jede Wiedergabe von Inhalten aus und bietet im Wesentlichen Überschreibungsverhalten. Eine Liste der Verhaltensweisen, die Entwickler überschreiben können, finden Sie in der Definition von cast.framework.PlaybackConfig. Wenn Sie die Konfiguration zwischen Inhalten ändern möchten, können Sie mit PlayerManager den aktuellen playbackConfig abrufen, eine Überschreibung ändern oder hinzufügen und playbackConfig so zurücksetzen:

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

Wenn PlaybackConfig nicht überschrieben wurde, gibt getPlaybackConfig() ein Nullobjekt zurück. Jedes Attribut in PlaybackConfig that verwendet den Standardwert undefined.

Ereignis-Listener

Mit der Web Receiver SDK kann deine Web Receiver App Spielerereignisse verarbeiten. Der Ereignis-Listener verwendet den Parameter cast.framework.events.EventType (oder ein Array dieser Parameter), der die Ereignisse festlegt, 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 bietet zusätzliche Informationen zum Ereignis.

Wenn Sie beispielsweise wissen möchten, wann eine mediaStatus-Änderung gesendet 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. Es ist kein expliziter SENDER_DISCONNECTED-Event-Listener in Ihrer eigenen Web Receiver-Logik erforderlich.

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 das Abfangen von Nachrichten wird der Parameter cast.framework.messages.MessageType verwendet. Dieser gibt an, welcher Nachrichtentyp abgefangen werden soll.

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

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

Achtung: Fügen Sie das Attribut queueData von LoadRequestData im LOAD-Interceptor nicht hinzu oder ändern Sie es nicht. Dies hat keine Auswirkungen auf die Wiedergabe, da queueData bereits gelesen und auf die Warteschlange angewendet wurde. Weitere Informationen finden Sie im Leitfaden für Warteschlangen.

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 im Nachrichtenabfangen Fehler auftreten, sollte Ihre Web Receiver-App den 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 Ereignis-Listener

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

• Mit einem Ereignis-Listener können Sie die Anfragedaten nicht ändern.
• Ein Ereignis-Listener wird am besten zum Auslösen von Analysen oder einer benutzerdefinierten Funktion verwendet.

Hinweis: Ein Ereignis-Listener kann auch verwendet werden, um eine Reihe von Ereignissen mit CORE, DEBUG oder FINE-Enum zu überwachen.

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

• Mit dem Abfangen von Nachrichten können Sie eine Nachricht überwachen, abfangen und die Anfragedaten selbst ändern.
• Das Abfangen von Nachrichten wird am besten zum Verarbeiten benutzerdefinierter Logik in Bezug auf Anfragedaten verwendet.

Medien werden geladen

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

entity ist die vorgeschlagene Property, die in der Implementierung sowohl für die Absender- als auch für die Empfänger-Apps verwendet werden kann. Die Property ist eine Deeplink-URL, die entweder eine Playlist oder ein bestimmter Medieninhalt sein kann.

contentUrl ist für spielbare URLs vorgesehen und kann verwendet werden, sobald sie verfügbar sind.

contentId wurde verworfen, da nicht eindeutig ist, ob der Wert eine URL des Mediums, eine echte ID oder ein Schlüsselparameter für die benutzerdefinierte Suche ist.

Es wird empfohlen, entity zum Speichern der echten ID oder der Schlüsselparameter und contentUrl für die URL der Medien zu verwenden. Ein Beispiel hierfür sehen Sie im folgenden Snippet, in dem 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

Die Methode getDeviceCapabilities liefert Geräteinformationen zum verbundenen Cast-Gerät und zu dem Video- oder Audiogerät, das damit verbunden ist. Die Methode getDeviceCapabilities bietet Supportinformationen für Google Assistant, Bluetooth sowie die verbundenen Anzeige- und Audiogeräte.

Diese Methode gibt ein Objekt zurück, das abgefragt werden kann. Dazu übergeben Sie eine der angegebenen Aufzählungen, um die Gerätefunktion für diese Aufzählung abzurufen. Die Aufzählungen 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

Ein Nutzer kann 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, damit die Web Receiver-App diese Interaktionen verarbeiten kann, die Anwendungs-UI über Status der Nutzeraktionen aktualisieren und optional die Änderungen zum Aktualisieren von Back-End-Diensten senden kann.

Unterstützte Medienbefehle

Die UI-Steuerstatus werden durch die MediaStatus.supportedMediaCommands für iOS- und Android-Absender-Controller, Empfänger- und Fernbedienungs-Apps, die auf Touch-Geräten ausgeführt werden, und auf Empfänger-Apps auf Android TV-Geräten gesteuert. Wenn ein bestimmtes bitweises Command in der Property aktiviert ist, werden die Schaltflächen für diese Aktion aktiviert. Wenn der Wert nicht festgelegt ist, ist die Schaltfläche deaktiviert. Diese Werte können auf dem Web Receiver geändert werden:

1. Mit PlayerManager.setSupportedMediaCommands den spezifischen Commands festlegen
2. Neuen Befehl mit addSupportedMediaCommands hinzufügen
3. Vorhandenen Befehl mit removeSupportedMediaCommands entfernen

playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Wenn der Empfänger das aktualisierte MediaStatus vorbereitet, werden die Änderungen im Attribut supportedMediaCommands übernommen. Wenn der Status übertragen wird, werden die Schaltflächen der verbundenen Absender in der UI entsprechend aktualisiert.

Hinweis: Änderungen an supportedMediaCommands haben keine Auswirkungen auf die Art der angezeigten Schaltfläche. Sie werden direkt in den Absenderanwendungen (iOS, Android) und der Controls API des Empfängers festgelegt. Die einzige Ausnahme, bei der supportedMediaCommands für diese Änderungen verwendet wird, sind die Media-Wiedergabekarten auf dem Startbildschirm von Smart-Display-Geräten.

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

Status von Nutzeraktionen verwalten

Wenn Nutzer mit der UI interagieren oder Sprachbefehle senden, können sie die Wiedergabe der Inhalte und Eigenschaften steuern, die mit dem wiedergegebenen Element verbunden sind. Anfragen, die die Wiedergabe steuern, werden automatisch vom SDK verarbeitet. Bei Anfragen, die Attribute für das aktuell wiedergegebene Element ändern, z. B. einen LIKE-Befehl, muss die Empfängeranwendung sie verarbeiten. Das SDK bietet eine Reihe von APIs für diese Arten von Anfragen. Zur Unterstützung dieser Anfragen muss Folgendes geschehen:

• Erfasst USER_ACTION Nachrichten und bestimmt die angeforderte Aktion.
• Aktualisieren Sie MediaInformation UserActionState, um die UI zu aktualisieren.

Hinweis: Bei Bedarf können Sie die Aktion an alle relevanten Back-Ends POST ausführen, um die Einstellung des Nutzers beizubehalten.

Das folgende Snippet fängt die Nachricht USER_ACTION ab und verarbeitet den Aufruf des Back-Ends mit der angeforderten Änderung. Anschließend wird ein Aufruf zum Aktualisieren von UserActionState auf dem Empfänger durchgeführt.

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

Mit dem folgenden Snippet wird ein Aufruf an einen Back-End-Dienst simuliert. Die Funktion prüft den 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));
    }
  });
}

Im folgenden Snippet wird UserActionRequestData verwendet und UserActionState wird dem MediaInformation hinzugefügt oder daraus entfernt. 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 Benutzeroberfläche des Smart Displays, der Fernbedienungs-App und der Android TV-UI wider. Er wird auch über ausgehende MediaStatus-Nachrichten übertragen, 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 für Geräte mit integriertem Assistant unterstützt. Die Standardimplementierungen für diese Befehle finden Sie in cast.framework.PlayerManager.

Befehl	Beschreibung
Spielen	Wiedergabe im pausierten Zustand abspielen oder fortsetzen
Pausieren	Inhalte pausieren, die gerade wiedergegeben werden.
Zurück	Springen Sie zum vorherigen Medienelement in Ihrer Medienwarteschlange.
Weiter	Springen Sie zum nächsten Medienelement in Ihrer Medienwarteschlange.
Beenden	Beende die Wiedergabe der Medien.
Keine wiederholen	Wiederholung von Medienelementen in der Warteschlange deaktivieren, sobald die Wiedergabe des letzten Elements in der Warteschlange abgeschlossen ist.
Wiederholung wiederholen	Die aktuell wiedergegebenen Medien werden unbegrenzt wiederholt.
Alle wiederholen	Wiederhole alle Elemente in der Warteschlange, sobald das letzte Element der Warteschlange abgespielt wurde.
Alle wiederholen und Zufallsmix wiedergeben	Wenn die Wiedergabe des letzten Elements in der Warteschlange abgeschlossen ist, kannst du die Wiedergabeliste als Zufallsmix wiedergeben und alle Elemente in der Warteschlange wiederholen.
Zufallsmix	Zufallsmixe in Ihrer Medienwarteschlange wiedergeben. Hinweis: Sie können die Medien auch vor der Wiedergabe mit dem Flag shuffle zufällig wiedergeben lassen, wenn dies in der loadRequestData der Nachricht LOAD festgelegt ist.
Untertitel aktivieren oder deaktivieren	Untertitel aktivieren / deaktivieren. „Aktivieren“ oder „Deaktivieren“ ist auch in verschiedenen Sprachen verfügbar.
Suche nach absoluter Zeit	Springt zur angegebenen absoluten Zeit.
Springen zu time relative zur aktuellen Zeit	Springt vorwärts oder rückwärts um den angegebenen Zeitraum bezogen auf die aktuelle Wiedergabedauer.
Noch einmal spielen	Starte das gerade wiedergegebene Medium neu oder starte die Wiedergabe des zuletzt wiedergegebenen Medienelements, sofern gerade nichts abgespielt wird.
Wiedergabegeschwindigkeit festlegen	Mediawiedergaberate variieren. Dies sollte standardmäßig geschehen. Mit dem Nachrichtenabfangen von SET_PLAYBACK_RATE können Sie eingehende Preisanfragen überschreiben.

Unterstützte Medienbefehle per Sprachbefehl

Um zu verhindern, 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, indem Sie das Attribut CastReceiverOptions.enforceSupportedCommands aktivieren. Die Benutzeroberfläche von Cast SDK-Absendern und Geräten mit Touchscreen wird entsprechend aktualisiert. Wenn das Flag nicht aktiviert ist, werden die eingehenden Sprachbefehle ausgeführt.

Wenn Sie beispielsweise PAUSE von Ihren Absenderanwendungen und Geräten mit Touchscreen zulassen, müssen Sie auch den Empfänger so konfigurieren, dass diese Einstellungen übernommen werden. Nach der Konfiguration werden alle eingehenden Sprachbefehle verworfen, wenn sie nicht in der Liste der unterstützten Befehle enthalten sind.

Im folgenden Beispiel wird CastReceiverOptions beim Start von CastReceiverContext angegeben. Der Befehl PAUSE wird jetzt unterstützt und der Player muss diesen Befehl unterstützen. Wenn jetzt 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 separate Logik verwenden. Entfernen Sie das Flag enforceSupportedCommands. Für jeden Befehl, den Sie einschränken möchten, können Sie die eingehende Nachricht abfangen. Hier fangen wir die Anfrage vom SDK ab, damit SEEK-Befehle an Geräte mit integriertem Assistant in Ihrer Web Receiver-Anwendung keine Suche auslösen.

Geben Sie für Medienbefehle, die von Ihrer Anwendung nicht unterstützt werden, 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;
  });

Hintergrundinformationen zur Sprachaktivität

Wenn die Cast-Plattform den Ton der Anwendung aufgrund von Assistant-Aktivitäten im Hintergrund überträgt, z. B. das Zuhören der Nutzer oder das Sprechen, wird die FocusState-Nachricht NOT_IN_FOCUS an die Web Receiver-Anwendung gesendet, wenn die Aktivität beginnt. Nach dem Ende der Aktivität wird eine weitere Nachricht mit IN_FOCUS gesendet. Abhängig von Ihrer Anwendung und den Medien, die wiedergegeben werden, können Sie Medien pausieren, wenn FocusState den Wert NOT_IN_FOCUS hat, indem Sie den Nachrichtentyp FOCUS_STATE abfangen.

Beispielsweise ist es empfehlenswert, die Wiedergabe des Hörbuchs 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;
  });

Sprache der Untertitel

Wenn ein Nutzer nicht explizit die Sprache für die Untertitel 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.

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

Metadaten und Spracheingabe

Sprachbefehle werden zwar vom Webempfänger standardmäßig verarbeitet, du solltest jedoch darauf achten, dass die Metadaten für deine Inhalte vollständig und korrekt sind. Dadurch wird sichergestellt, dass Sprachbefehle ordnungsgemäß von Assistant verarbeitet werden und dass die Metadaten auf neuen Benutzeroberflächen wie der Google Home App und Smart Displays wie Google Home Hub korrekt angezeigt werden.

Stream-Übertragung

Hinweis: Audio-Web-Receiver unterstützen standardmäßig die Stream-Erweiterung, bei der der Sitzung zusätzliche für 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, bei der Nutzer vorhandene Audio- und Videostreams mithilfe von Sprachbefehlen, der Google Home App oder Smart Displays geräteübergreifend verschieben können. Die Medienwiedergabe wird auf einem Gerät (Quelle) beendet und auf einem anderen Gerät (Ziel) fortgesetzt. Jedes Cast-Gerät mit der neuesten Firmware kann in einer Streamübertragung als Quelle oder Ziel dienen.

Der Ereignisfluss für die Streamübertragung ist:

1. Auf dem Quellgerät:
   1. Die Medienwiedergabe wird beendet.
   2. Die Web Receiver App empfängt einen Befehl zum Speichern des aktuellen Medienstatus.
   3. Die Web Receiver App wurde heruntergefahren.
2. Auf dem Zielgerät:
   1. Die Web Receiver-Anwendung wurde geladen.
   2. Die Webanwendung empfängt einen Befehl, um den gespeicherten Medienstatus wiederherzustellen.
   3. Die Medienwiedergabe wird fortgesetzt.

Zu den Elementen des Medienstatus gehören:

• Die spezifische Position oder der Zeitstempel des Titels, Videos oder Medienelements.
• Sie befindet sich in einer breiteren Warteschlange, z. B. in einer Playlist oder im Radio eines 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. Optional können Sie die Nachrichtenabfanger SESSION_STATE und RESUME_SESSION wie unter Sitzungsstatus beibehalten beschrieben überschreiben. Sie sollten diese nur überschreiben, wenn benutzerdefinierte Daten als Teil des Sitzungs-Snapshots gespeichert werden müssen. Andernfalls wird die Stream-Übertragung von der Standardimplementierung für die Beibehaltung des Sitzungsstatus unterstützt.

Sitzungsstatus beibehalten

Das Web Receiver SDK bietet eine Standardimplementierung für Web Receiver-Apps, bei der ein Snapshot des aktuellen Medienstatus beibehalten, der Status in eine Ladeanfrage umgewandelt und die Sitzung mit der Ladeanfrage fortgesetzt wird.

Die vom Webempfänger erstellte Ladeanfrage kann gegebenenfalls im SESSION_STATE-Abfangdienst für Nachrichten ü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 aus loadRequestData.customData im Nachrichten-Abfangdienst 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;
    });

Inhalt vorab laden

Der Webempfänger unterstützt das Vorabladen von Medienelementen nach dem aktuellen Wiedergabeelement in der Warteschlange.

Beim Vorabladen werden mehrere Segmente der anstehenden Elemente vorab heruntergeladen. Die Spezifikation wird für den preloadTime-Wert im Objekt QueueItem festgelegt (standardmäßig auf 20 Sekunden festgelegt, falls nicht angegeben). Die Zeit wird in Sekunden relativ zum 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 auf dem aktuellen Element verbleibende Zeit, wird das Vorabladen so schnell wie möglich ausgeführt. Wenn also ein sehr großer Wert für das Vorabladen in der Warteschlange angegeben ist, könnte dies die Wirkung erzielen, die sich ergibt, wenn das aktuelle Element bereits vorgeladen wird und das nächste Element bereits vorab geladen wird. Wir überlassen jedoch die Einstellung und Auswahl dem Entwickler, da dieser Wert die Bandbreite und die Streamingleistung des aktuell wiedergebenden Elements beeinträchtigen kann.

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

Reguläre MP4-Video- und -Audiodateien wie MP3 werden nicht vorab geladen, da Cast-Geräte nur ein Mediaelement 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 mit den Absender-APIs für die Plattform, auf der der Absender ausgeführt wird (Android, iOS, Web). Das Ereignisobjekt (das die Manifestation einer Nachricht ist), das an die Ereignis-Listener übergeben wird, hat ein Datenelement (event.data), in dem die Daten die Attribute des jeweiligen Ereignistyps übernehmen.

Eine Web Receiver-Anwendung kann Nachrichten in einem bestimmten Namespace überwachen. Die Web Receiver-Anwendung soll dieses Namespace-Protokoll unterstützen. Anschließend können alle verbundenen Absender das entsprechende Protokoll verwenden, um zu kommunizieren.

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 die Medianachricht „urn:x-cast:com.google.cast.media“ ist reserviert. Mediennachrichten, die mit den Cast APIs sowohl auf dem Absender als auch auf dem Webempfänger gesendet werden, verwenden standardmäßig das Medien-Namespace-Protokoll. Weitere Informationen zu Mediennachrichten finden Sie unter Medien und Player.

Hier ist ein Code-Snippet, mit dem der Webempfänger benutzerdefinierte Nachrichten von verbundenen Absendern erfassen kann:

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

Auf ähnliche Weise 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) in CastReceiverContext senden. Ein Webempfänger kann Nachrichten als Antwort auf eine empfangene Nachricht oder aufgrund einer Änderung des Anwendungsstatus an einen einzelnen Absender senden. Neben dem Punkt-zu-Punkt-Messaging (mit einer Begrenzung von 64 KB) kann ein Webempfänger Nachrichten auch an alle verbundenen Absender senden.

Streaming für Audiogeräte

Im Google Cast-Leitfaden für Audiogeräte finden Sie Informationen zur Unterstützung der Funktion „Nur Audio“.

Android TV

In diesem Abschnitt wird erläutert, wie der Google Web Receiver deine Eingaben zur Wiedergabe und für Android TV verwendet.

Anwendung in die Fernbedienung einbinden

Der auf dem Android TV-Gerät ausgeführte Google Web Receiver übersetzt Eingaben von den Steuerungseingaben des Geräts (d.h. der Handfernsteuerung) als Nachrichten zur Medienwiedergabe, die für den Namespace urn:x-cast:com.google.cast.media definiert sind, wie unter Medienwiedergabenachrichten beschrieben. Deine App muss diese Meldungen unterstützen, um die Medienwiedergabe von Apps steuern zu können, damit eine grundlegende Wiedergabesteuerung über die Steuerungseingaben von Android TV möglich ist.

Richtlinien zur Kompatibilität mit Android TV

Im Folgenden finden Sie einige Empfehlungen und häufige Fehler, die Sie vermeiden sollten, damit Ihre App mit Android TV kompatibel ist:

• Beachte, dass der User-Agent-String sowohl „Android“ als auch „CRTB“ enthält. Einige Websites leiten den Nutzer möglicherweise an eine rein mobile Website weiter, weil das Label „Android“ erkannt wird. Gehen Sie nicht davon aus, dass „Android“ im User-Agent-String immer einen mobilen Nutzer angibt.
• Der Android-Mediastack verwendet möglicherweise transparente GZIP-Dateien zum Abrufen von Daten. Achte darauf, dass deine Mediendaten auf Accept-Encoding: gzip reagieren können.
• Android TV-HTML5-Medienereignisse können zu anderen Zeiten ausgelöst werden als Chromecast. Dies kann auf Probleme hinweisen, die auf Chromecast verborgen waren.
• Verwenden Sie beim 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 zum Umgang mit Medienereignissen in Ihrem Empfänger finden Sie unter Medienereignisse.
• Wenn Sie die HTTPS-Zertifikate der Empfängerwebsite konfigurieren, müssen Sie CA-Zwischenzertifikate einfügen. Auf der SSL-Testseite von Qualsys 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. Es kann dann auf Android-basierten Plattformen nicht geladen werden.
• Während die Empfängerseite auf einer Grafikebene von 720p angezeigt wird, wird die Seite von anderen Cast-Plattformen, einschließlich Android TV, möglicherweise bis zu 1080p angezeigt. Sorgt dafür, dass die Empfängerseite in verschiedenen Auflösungen korrekt skaliert wird.