Ihrem benutzerdefinierten Webempfänger grundlegende Funktionen hinzufügen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Diese Seite enthält Code-Snippets und Beschreibungen der Funktionen einer benutzerdefinierten Web Receiver-App.

  1. Ein cast-media-player-Element, das die integrierte Player-UI 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 formatieren.
  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

Die CastReceiverContext ist die äußerste Klasse, die dem Entwickler zur Verfügung steht. 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 mit dem Absender kommunizieren konnte, den wir als maxInactivity-Sekunden beschrieben haben, wird auch das Ereignis SENDER_DISCONNECTED ausgelöst. Während der Entwicklung empfiehlt es sich, für maxInactivity einen hohen Wert festzulegen, damit die Web Receiver-App beim Debuggen der Anwendung 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 dem Standardwert zu basieren. Die Web Receiver-Optionen werden in der Anwendung nur einmal festgelegt.

Die andere Konfiguration ist cast.framework.PlaybackConfig. Dies kann folgendermaßen festgelegt werden:

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

Diese Konfiguration wirkt sich auf jede Inhaltswiedergabe aus und ermöglicht im Wesentlichen das Überschreiben. 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. Für jedes Attribut im Attribut PlaybackConfig that (undefined) werden die Standardwerte verwendet.

Ereignis-Listener

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

Wenn Sie beispielsweise wissen möchten, wann eine mediaStatus-Änderung übertragen wird, können Sie die folgende Logik für die 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. Im Message fangen Sie mit dem Parameter cast.framework.messages.MessageType ab, welche Art von Nachricht abgefangen werden soll.

Der Abfanger 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 nicht aufgerufen. Weitere Informationen finden Sie unter Medien werden geladen.

Wenn Sie beispielsweise die Daten der Ladeanfrage ändern möchten, können Sie diese mit folgender 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 im Nachrichtenabfangen Fehler auftreten, sollte Ihre Web Receiver-Anwendung 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 zu 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.
playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });
  • Mit dem Abfangen von Nachrichten können Sie eine Nachricht anhören, abfangen und die Anfragedaten selbst ändern.
  • Das Abfangen von Nachrichten eignet sich am besten für die Verarbeitung einer benutzerdefinierten Logik in Bezug auf Anfragedaten.

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.

Die entity ist die vorgeschlagene Property, die in deiner Implementierung sowohl für die Absender- als auch die Empfänger-App verwendet werden soll. Die Property ist eine Deeplink-URL, bei der es sich entweder um eine Playlist oder um einen bestimmten Medieninhalt handeln kann.

Die contentUrl ist für eine abspielbare URL vorgesehen und kann verwendet werden, sobald sie verfügbar ist.

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

Es wird empfohlen, entity mit der echten ID oder den Schlüsselparametern zu speichern und mit contentUrl als URL des Mediums festzulegen. Ein Beispiel dafür zeigt das folgende Snippet, in dem der entity in der LOAD-Anfrage vorhanden und der abspielbare contentUrl abgerufen ist:

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 Cast-Gerät und zu dem Video- oder Audiogerät angezeigt, das an das Gerät angeschlossen 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 Sie abfragen können, indem Sie eine der angegebenen Aufzählungen übergeben, um die Gerätefunktion für diese Aufzählung zu erhalten. 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 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

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, mit denen die Web Receiver-App diese Interaktionen verarbeiten und die Anwendungs-UI über Nutzeraktionsstatus aktualisieren kann. Optional können Sie die Änderungen zum Aktualisieren von Back-End-Diensten senden.

Unterstützte Medienbefehle

Die UI-Steuerstatus werden durch die MediaStatus.supportedMediaCommands für iOS- und Android-Sender mit erweiterten Controllern, Receiver und Fernbedienungs-Apps auf Touchgeräten sowie Receiver-Apps auf Android TV-Geräten gesteuert. Wenn ein bestimmtes Bit Command im Attribut aktiviert ist, werden die Schaltflächen, die sich auf diese Aktion beziehen, aktiviert. Wenn der Wert nicht festgelegt ist, ist die Schaltfläche deaktiviert. Diese Werte können im 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 in das Attribut supportedMediaCommands aufgenommen. Wenn der Status übertragen wird, aktualisieren die Apps des verbundenen Absenders 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 Nutzeraktionen verwalten

Wenn Nutzer mit der UI interagieren oder Sprachbefehle senden, können sie die Wiedergabe der Inhalte und Eigenschaften steuern, die sich auf das abgespielte Element beziehen. Anfragen, die die Wiedergabe steuern, werden vom SDK automatisch verarbeitet. Bei Anfragen, durch die Attribute für das aktuell wiedergegebene Element geändert werden, z. B. der Befehl LIKE, muss die Empfängeranwendung sie verarbeiten. Das SDK bietet eine Reihe von APIs, die diese Arten von Anfragen verarbeiten. Um diese Anfragen zu unterstützen, müssen Sie Folgendes tun:

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

Mit dem folgenden Snippet wird die Nachricht USER_ACTION abgefangen und das Back-End mit der gewünschten Änderung aufgerufen. 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 anhand von UserActionRequestData die Art der vom Nutzer angeforderten Änderung und führt nur dann einen Netzwerkaufruf durch, 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 der 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 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 für diese Befehle finden Sie unter cast.framework.PlayerManager.

Befehl Beschreibung
Spielen Wiedergabe im pausierten Zustand fortsetzen oder fortsetzen
Pausieren Wiedergabe von Inhalten pausieren.
Zurück Springe zum vorherigen Mediakostenelement.
Weiter Springe zum nächsten Media-Element in deiner Wiedergabeliste.
Beenden Beenden Sie die Wiedergabe von Medien.
Nichts wiederholen Wiederholung von Medienelementen in der Warteschlange deaktivieren, sobald die letzte Wiedergabe abgeschlossen ist.
Wiederholung wiederholen Die aktuell wiedergegebenen Medien auf unbestimmte Zeit wiederholen.
Alle wiederholen Wiederhole alle Elemente in der Warteschlange, sobald das letzte Element in der Warteschlange wiedergegeben wurde.
Alle wiederholen und Zufallsmix wiedergeben Nachdem das letzte Element in der Warteschlange abgespielt wurde, Zufallsmix der Warteschlange wiedergeben und alle Elemente in der Warteschlange wiederholen.
Zufallsmix Zufallsmixe in der Medienwarteschlange wiedergeben.
Untertitel aktivieren / deaktivieren Untertitel für deine Medien aktivieren / deaktivieren. „Aktivieren“ oder „Deaktivieren“ ist auch nach Sprache verfügbar.
Zur absoluten Suche springen Springt zur angegebenen absoluten Zeit.
Zur aktuellen Zeit suchen Springt im angegebenen Zeitraum relativ zur aktuellen Wiedergabe vor oder zurück.
Noch einmal spielen Starte das aktuell abgespielte Medium neu oder spiel das zuletzt abgespielte Medienelement ab, wenn gerade nichts abgespielt wird.
Wiedergabegeschwindigkeit festlegen Variieren Sie die Medienwiedergaberate. Dies sollte standardmäßig geschehen. Mit dem Nachrichtenabfangen von SET_PLAYBACK_RATE können Sie eingehende Preisanfragen überschreiben.

Unterstützte Medienbefehle per Sprachbefehl

Wenn du verhindern möchtest, dass ein Sprachbefehl einen Medienbefehl auf einem Gerät mit integriertem Assistant auslöst, musst du zuerst die unterstützten Medienbefehle festlegen, die du unterstützen möchtest. 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 angepasst. Ist das Flag nicht aktiviert, werden die eingehenden Sprachbefehle ausgeführt.

Wenn Sie beispielsweise PAUSE in Ihren Absenderanwendungen und auf Geräten mit Touchscreen zulassen, müssen Sie den Empfänger auch entsprechend konfigurieren. Wenn diese Option konfiguriert ist, werden alle eingehenden Sprachbefehle verworfen, wenn sie nicht in der Liste der unterstützten Befehle enthalten sind.

Im folgenden Beispiel geben Sie CastReceiverOptions an, wenn Sie CastReceiverContext starten. Wir haben die Unterstützung für den Befehl PAUSE hinzugefügt und den Player dazu gezwungen, nur diesen Befehl zu unterstützen. Wenn ein Sprachbefehl jetzt einen anderen Vorgang wie SEEK anfordert, 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 eigene 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 vom SDK bereitgestellte Anfrage ab, damit SEEK-Befehle an Geräte mit integriertem Assistant keine Suche in deiner Web Receiver-Anwendung auslösen.

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

Hintergrundinformationen zu Sprachaktivitäten

Wenn die Cast-Plattform den Hintergrundton deiner App aufgrund von Assistant-Aktivitäten, wie das Anhören von Nutzersprache oder Sprechen, im Hintergrund abspielt, wird zu Beginn der Aktivität die FocusState-Nachricht NOT_IN_FOCUS an die Web Receiver-Anwendung gesendet. Eine weitere Nachricht mit IN_FOCUS wird gesendet, wenn die Aktivität endet. Abhängig von Ihrer Anwendung und den abgespielten Medien können Sie Medien abfangen, wenn FocusState den Wert NOT_IN_FOCUS hat, indem Sie den Nachrichtentyp FOCUS_STATE abfangen.

Beispielsweise ist es eine gute Nutzererfahrung, 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 der Untertitel angibt, entspricht die Sprache der Untertitel der Sprache, in der der Befehl gesprochen wird. In diesen Fällen 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 „Hey Google, 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. in „Hey Google, aktiviere englische Untertitel“, ist isSuggestedLanguage auf false gesetzt.

Metadaten und Voice Streaming

Sprachbefehle werden vom Web Receiver standardmäßig verarbeitet. Du solltest aber darauf achten, dass die Metadaten für deine Inhalte vollständig und korrekt sind. So wird dafür gesorgt, dass Sprachbefehle vom Assistant richtig verarbeitet werden und die Metadaten auf neuen Arten von Schnittstellen wie der Google Home App und Smart Displays wie dem Google Nest Hub korrekt angezeigt werden.

Stream-Übertragung

Die Beibehaltung des Sitzungsstatus ist die Basis 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 (Ziel) fortgesetzt. Jedes Übertragungsgerät mit der neuesten Firmware kann als Quellen oder Ziele bei einer Streamübertragung verwendet werden.

Der Ereignisfluss für die Streamübertragung ist:

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

Elemente des Medienstatus:

  • Die spezifische Position oder der Zeitstempel des Titels, Videos oder Mediaelements.
  • Sie befindet sich in einer breiteren Warteschlange, z. B. in einer Playlist oder einem Radiosender eines Künstlers.
  • Der authentifizierte Nutzer.
  • Wiedergabestatus (z. B. Wiedergabe oder pausiert)

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. Optional können Sie die Nachrichtenabfanger SESSION_STATE und RESUME_SESSION überschreiben, wie unter Status der Sitzung beibehalten beschrieben. Sie sollten diese nur überschreiben, wenn benutzerdefinierte Daten als Teil des Sitzungs-Snapshots gespeichert werden müssen. Andernfalls unterstützt die Standardimplementierung zur Beibehaltung des Sitzungsstatus die Streamübertragung.

Sitzungsstatus beibehalten

Das Web Receiver SDK bietet eine Standardimplementierung für Web Receiver-Apps, mit denen Sitzungsstatus beibehalten werden. 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 im SESSION_STATE-Abfangdienst für Nachrichten bei Bedarf ü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;
    });

Inhalte 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 QueueItem-Objekt festgelegt (standardmäßig 20 Sekunden, falls 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 Dauer des Vorabladens höher ist als die des aktuellen Elements, wird das Vorabladen so schnell wie möglich ausgeführt. Wenn also ein sehr hoher Wert für das Vorabladen auf „QueueItem“ gesetzt ist, kann es passieren, dass die Auswirkungen immer dann auftreten, wenn wir das aktuelle Element abspielen. Es wird bereits das nächste Element vorab geladen. Wir überlassen jedoch die Einstellung und Auswahl dem Entwickler, da dieser Wert die Bandbreite und die Streaming-Leistung des aktuell wiedergebenden Elements beeinflussen kann.

Das Vorabladen ist für HLS-, DASH- und Smooth Streaming-Inhalte standardmäßig möglich.

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

Benutzerdefinierte Nachrichten

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

Ein Absender stellt über die Absender-APIs für die Plattform, auf der er ausgeführt wird (Android, iOS, Web), Nachrichten an einen Webempfänger aus. Das Ereignisobjekt (das die Manifestation einer Nachricht ist) und an die Ereignis-Listener übergeben wird, hat ein Datenelement (event.data), bei dem die Daten die Properties des jeweiligen Ereignistyps übernehmen.

Eine Web Receiver-Anwendung kann Nachrichten in einem bestimmten Namespace überwachen. Aus diesem Grund wird davon ausgegangen, dass die Web Receiver-Anwendung dieses Namespace-Protokoll unterstützt. Anschließend können 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".

Hier ist ein Code-Snippet, mit dem der Webempfänger benutzerdefinierte Nachrichten von verbundenen Absendern abhören 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 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 Webempfänger kann Nachrichten als Antwort auf eine empfangene Nachricht oder aufgrund einer Änderung des Anwendungsstatus an einen einzelnen Absender senden. Neben der Punkt-zu-Punkt-Nachricht (mit einem Limit von 64 KB) kann ein Webempfänger Nachrichten auch an alle verbundenen Absender senden.

Für Audiogeräte streamen

Im Leitfaden zu Google Cast für Audiogeräte finden Sie Informationen zur reinen Audiowiedergabe.

Android TV

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

Anwendung in die Fernbedienung einbinden

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

Richtlinien für die Kompatibilität mit Android TV

Hier sind einige Empfehlungen und häufige Fehler, die es zu vermeiden gilt, damit deine App mit Android TV kompatibel ist:

  • Beachten Sie, dass der User-Agent-String sowohl &Android als auch CFile enthält. Einige Websites leiten möglicherweise zu einer 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 hinweist.
  • Der Android-Media-Stack kann eine transparente GZIP-Datei zum Abrufen von Daten verwenden. Prüfe, ob deine Mediendaten auf Accept-Encoding: gzip reagieren können.
  • HTML5-Medienereignisse können in Android TV in unterschiedlichen Abständen ausgelöst werden, was unter Umständen zu Problemen bei der Anzeige auf Chromecast führt.
  • Verwende 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 im Empfänger finden Sie unter Medienereignisse.
  • Wenn du die HTTPS-Zertifikate der Empfängerwebsite konfigurierst, musst du auch CA-Zwischenzertifikate angeben. Informationen dazu finden Sie auf der Qualsys-SSL-Testseite: Wenn der vertrauenswürdige Zertifizierungspfad für Ihre Website ein CA-Zertifikat mit der Bezeichnung „zusätzlicher Download“ enthält, wird es möglicherweise nicht auf Android-basierten Plattformen geladen.
  • Während die Empfängerseite in Chromecast auf einer Grafikebene von 720p angezeigt wird, kann es auf anderen Cast-Plattformen wie Android TV bis zu 1080p sein. Sorgt dafür, dass die Empfängerseite mit verschiedenen Auflösungen skaliert werden kann.