Funktion „Weiter ansehen“ mit der REST API einbinden

Das Engage SDK bietet eine REST API, um eine einheitliche Funktion „Weiter ansehen“ auf Nicht-Android-Plattformen wie iOS und Roku TV zu ermöglichen. Mit der API können Entwickler den Status „Weiter ansehen“ für Nutzer, die sich angemeldet haben, von Nicht-Android-Plattformen aus aktualisieren.

Vorbereitung

  • Sie müssen zuerst die gerätebasierte Engage SDK-Integration abschließen. In diesem wichtigen Schritt wird die erforderliche Verknüpfung zwischen der Google-Nutzer-ID und der AccountProfile Ihrer App hergestellt.
  • API-Zugriff und Authentifizierung: Um die API in Ihrem Google Cloud-Projekt aufzurufen und zu aktivieren, müssen Sie einen Zulassungslistenprozess durchlaufen. Alle API-Anfragen erfordern eine Authentifizierung.

Zugriff erhalten

Damit Sie die API in der Google Cloud Console aufrufen und aktivieren können, muss Ihr Konto registriert sein.

  1. Die Google Workspace-Kundennummer sollte verfügbar sein. Falls nicht verfügbar, müssen Sie möglicherweise ein Google Workspace-Konto sowie alle Google-Konten einrichten, die Sie zum Aufrufen der API verwenden möchten.
  2. Richten Sie ein Konto in der Google Cloud Console mit einer E-Mail-Adresse ein, die mit Google Workspace verknüpft ist.
  3. Neues Projekt erstellen
  4. Erstellen Sie ein Dienstkonto für die API-Authentifizierung. Nachdem Sie das Dienstkonto erstellt haben, haben Sie zwei Elemente:
    • Eine Dienstkonto-ID.
    • Eine JSON-Datei mit Ihrem Dienstkontoschlüssel. Bewahren Sie diese Datei sicher auf. Sie benötigen ihn später, um Ihren Client bei der API zu authentifizieren.
  5. Workspace- und zugehörige Google-Konten können jetzt REST APIs verwenden. Sobald die Änderung übernommen wurde, werden Sie darüber informiert, ob die API von Ihren Dienstkonten aufgerufen werden kann.
  6. Folgen Sie dieser Anleitung, um einen delegierten API-Aufruf vorzubereiten.

Fortsetzungscluster veröffentlichen

Wenn Sie die Engage-Daten veröffentlichen möchten, senden Sie eine POST-Anfrage an die publishContinuationCluster API. Verwenden Sie dazu die folgende Syntax.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

Wobei:

  • package_name: Der Paketname des Medienanbieters
  • accountId: Die eindeutige ID für das Konto des Nutzers in Ihrem System. Sie muss mit der accountId im On-Device-Pfad übereinstimmen.
  • profileId: Die eindeutige ID für das Profil des Nutzers innerhalb des Kontos in Ihrem System. Sie muss mit der im On-Device-Pfad verwendeten profileId übereinstimmen.

Die URL für das Konto ohne Profil lautet:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

Die Nutzlast der Anfrage wird im Feld entities dargestellt. entities stellt eine Liste von Inhaltsentitäten dar, die aus einem oder mehreren der folgenden Elemente bestehen können: MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity oder VideoClipEntity. Dieses Feld ist erforderlich.

Anfragetext

Feld

Typ

Erforderlich

Beschreibung

entities

Liste der MediaEntity-Objekte

Ja

Liste der Inhaltsentitäten mit maximal 5 Einträgen. Nur die ersten fünf werden beibehalten, die restlichen werden verworfen. Eine leere Liste ist zulässig, um anzugeben, dass der Nutzer alle Entitäten angesehen hat.

Das Feld entities enthält einzelne movieEntity, tvEpisodeEntity, liveStreamingVideoEntity und videoClipEntity.

Feld

Typ

Beschreibung

movieEntity

MovieEntity

Ein Objekt, das einen Film im ContinuationCluster darstellt.

tvEpisodeEntity

TvEpisodeEntity

Ein Objekt, das eine TV-Folge im ContinuationCluster darstellt.

liveStreamingVideoEntity

LiveStreamingVideoEntity

Ein Objekt, das ein Video per Livestream im ContinuationCluster darstellt.

videoClipEntity

VideoClipEntity

Ein Objekt, das einen Videoclip innerhalb des ContinuationCluster darstellt.

Jedes Objekt im Array „entities“ muss einer der verfügbaren MediaEntity-Typen sein, nämlich MovieEntity, TvEpisodeEntity, LiveStreamingVideoEntity oder VideoClipEntity, zusammen mit allgemeinen und typspezifischen Feldern.

Das folgende Code-Snippet zeigt die Nutzlast des Anfragetexts für die publishContinuationCluster API.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/movie_entity_uri_for_android",
          "platforms": [
            "PLATFORM_ANDROID_TV",
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/movie_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/movie1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Movie 1 HD poster"
          },
          {
            "url": "http://www.example.com/movie1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Movie 1 SD poster"
          }
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_mobile",
          "platforms": [
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_tv",
          "platforms": [
            "PLATFORM_ANDROID_TV"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/episode1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Episode 1 HD poster"
          },
          {
            "url": "http://www.example.com/episode1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Episode 1 SD poster"
          }
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    },
    {
      "liveStreamingVideoEntity": {
        "name": "Live Sports Championship",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 1800000,
        "duration_millis": 7200000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/live_streaming_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/live_stream_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Live Sports Championship Cover Image"
          }
        ],
        "start_time_epoch_millis": 1780976484000,
        "broadcaster": "Global Sports Network",
        "broadcaster_icon": {
          "url": "https://www.example.com/gsports.jpg",
          "width": 512,
          "height": 512,
          "accessibility_text": "Global Sports Network Logo"
        }
      }
    },
    {
      "videoClipEntity": {
        "name": "How to Brew the Perfect Espresso",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 120000,
        "duration_millis": 600000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/video_clip_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/video_clip_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Espresso Tutorial Cover Image"
          }
        ],
        "created_time_epoch_millis": 1780900000000,
        "creator": "Coffee Enthusiast John",
        "creator_image": {
          "url": "https://www.example.com/image/thumb/creators/john_avatar.jpg",
          "width": 256,
          "height": 256,
          "accessibility_text": "John's Avatar"
        }
      }
    }
  ]
}

Engage-Daten löschen

Verwenden Sie die clearCluster API, um die Engage-Daten zu entfernen.

Wenn Sie die Daten des Fortsetzungsclusters löschen möchten, senden Sie eine POST-Anfrage an die clearCluster API. Verwenden Sie dazu die folgende Syntax.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearCluster

Wobei:

  • package_name: Der Paketname des Medienanbieters.
  • accountId: Die eindeutige ID für das Konto des Nutzers in Ihrem System. Sie muss mit der accountId im On-Device-Pfad übereinstimmen.
  • profileId: Die eindeutige ID für das Profil des Nutzers innerhalb des Kontos in Ihrem System. Sie muss mit der im On-Device-Pfad verwendeten profileId übereinstimmen.

Die URL für das Konto ohne Profil lautet:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/clearCluster

Die Nutzlast für die clearCluster API enthält nur ein Feld, reason, das einen DeleteReason enthält, der den Grund für das Entfernen von Daten angibt.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Test

Nachdem du die Daten erfolgreich gepostet hast, kannst du mit einem Testkonto prüfen, ob die erwarteten Inhalte in der Zeile „Weiter ansehen“ auf den Google-Zieloberflächen wie Google TV und den mobilen Google TV-Apps für Android und iOS angezeigt werden.

Plane beim Testen eine angemessene Verzögerung von einigen Minuten ein und halte dich an die Wiedergabeanforderungen, z. B. einen Teil eines Films anzusehen oder eine Folge zu beenden. Weitere Informationen findest du in den Empfehlungen zu „Als Nächstes ansehen“ für App-Entwickler.