Engage SDK für Videoempfehlungen

Diese Anleitung enthält Anweisungen für Entwickler zum Einbinden ihrer empfohlenen Videoinhalte mit dem Engage SDK, um Empfehlungen auf Google-Oberflächen wie Fernsehern, Smartphones und Tablets zu präsentieren.

Bei Empfehlungen werden Filme und Serien aus mehreren Apps in einer UI-Gruppierung im Empfehlungscluster angezeigt. Jeder Entwicklerpartner kann maximal 25 Entitäten in jedem Empfehlungscluster übertragen. Pro Anfrage können maximal 7 Empfehlungscluster vorhanden sein.

Vorarbeit

Führen Sie die Schritte unter „Vorarbeit“ im Startleitfaden aus.

  1. Veröffentlichung in einem Dienst im Vordergrund ausführen
  2. Empfehlungsdaten höchstens einmal täglich veröffentlichen, ausgelöst durch eine der folgenden Aktionen:
    • Erste Anmeldung des Nutzers an diesem Tag (oder)
    • Wenn der Nutzer mit der Anwendung interagiert

Integration

AppEngagePublishClient veröffentlicht den Empfehlungscluster. Verwenden Sie die Methode publishRecommendationClusters, um ein Empfehlungsobjekt zu veröffentlichen.

Initialisieren Sie den Client und prüfen Sie die Verfügbarkeit des Dienstes wie im Startleitfaden beschrieben.

client.publishRecommendationClusters(recommendationRequest)

Empfehlungscluster einfügen oder aktualisieren

Cluster sind logische Gruppierungen der Entitäten. In den folgenden Codebeispielen wird erläutert, wie Sie die Cluster nach Ihren Vorlieben erstellen und wie Sie eine Veröffentlichungsanfrage erstellen und alle Cluster einfügen oder aktualisieren.

Der RecommendationClusterType bestimmt, wie der Cluster angezeigt wird.

// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
  .Builder()
  .addEntity(movie1)
  .addEntity(movie2)
  .addEntity(movie3)
  .addEntity(movie4)
  .addEntity(tvShow)
  // This cluster is meant to be used as an individual provider row
  .setRecommendationClusterType(TYPE_PROVIDER_ROW)
  .setTitle("Popular Movies")
  .build()

// cluster for live TV programs
val recommendationCluster2 = RecommendationCluster
  .Builder()
  .addEntity(liveTvProgramEntity1)
  .addEntity(liveTvProgramEntity2)
  .addEntity(liveTvProgramEntity3)
  .addEntity(liveTvProgramEntity4)
  .addEntity(liveTvProgramEntity5)
 // This cluster is meant to be used as an individual provider row
  .setRecommendationClusterType(TYPE_PROVIDER_ROW)
  .setTitle("Popular Live TV Programs")
  .build()

// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
  .Builder()
  .setSyncAcrossDevices(true)
  .setAccountProfile(accountProfile)
  .addRecommendationCluster(recommendationCluster1)
  .addRecommendationCluster(recommendationCluster2)
  .build()

Wenn der Dienst die Anfrage erhält, werden die folgenden Aktionen in einer Transaktion ausgeführt:

  • Vorhandene RecommendationsCluster-Daten des Entwicklerpartners werden entfernt.
  • Daten aus der Anfrage werden geparst und im aktualisierten RecommendationsCluster gespeichert. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

Geräteübergreifende Synchronisierung

Mit dem Flag SyncAcrossDevices wird gesteuert, ob die Empfehlungsclusterdaten eines Nutzers für Google TV freigegeben werden und auf seinen Geräten wie Fernsehern, Smartphones und Tablets verfügbar sind. Damit die Empfehlung funktioniert, muss sie auf „true“ gesetzt sein.

Die Media-Anwendung muss eine klare Einstellung zum Aktivieren oder Deaktivieren der geräteübergreifenden Synchronisierung bieten. Erläutern Sie dem Nutzer die Vorteile, speichern Sie die Präferenz des Nutzers einmal und wenden Sie sie entsprechend in der Anfrage publishRecommendations an. Damit Sie die geräteübergreifende Funktion optimal nutzen können, prüfen Sie, ob die App die Einwilligung des Nutzers einholt und SyncAcrossDevices auf true setzt.

Engage-Daten löschen

Wenn Sie die Daten eines Nutzers vor Ablauf der standardmäßigen Aufbewahrungsfrist von 60 Tagen manuell vom Google TV-Server löschen möchten, verwenden Sie die Methode client.deleteClusters(). Nach Erhalt der Anfrage löscht der Dienst alle vorhandenen Engage-Daten für das Kontoprofil oder für das gesamte Konto.

Die DeleteReason Enum definiert den Grund für das Löschen von Daten. Mit dem folgenden Code werden Empfehlungen beim Abmelden entfernt.

// If the user logs out from your media app, you must make the following call
// to remove recommendations data from the current Google TV device, otherwise,
// the recommendations data persists on the current Google TV device until 60
// days later.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
    .setAccountProfile(AccountProfile())
    .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
    .build()
)

// If the user revokes the consent to share data with Google TV, you must make
// the following call to remove recommendations data from all current Google TV
// devices. Otherwise, the recommendations data persists until 60 days later.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
    .setAccountProfile(AccountProfile())
    .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

Entitäten erstellen

Im SDK sind verschiedene Entitäten definiert, um die einzelnen Elementtypen darzustellen. Die folgenden Entitäten werden für den Empfehlungscluster unterstützt:

  1. MediaActionFeedEntity
  2. MovieEntity
  3. TvShowEntity
  4. LiveTvChannelEntity
  5. LiveTvProgramEntity

Beschreibungen angeben

Geben Sie für jede Entität eine kurze Beschreibung an. Diese Beschreibung wird angezeigt, wenn Nutzer den Mauszeiger auf die Entität bewegen, und enthält zusätzliche Details.

Call-to-Action-Text

Geben Sie optional einen Call-to-Action-Text für jede Entität an. Dieser Text wird dem Nutzer angezeigt, um ihn zur Interaktion zu animieren.

Tags

Geben Sie optional eine Liste von Tags für jede Entität an. Tags können zur Kategorisierung und Filterung verwendet werden.

Plattformspezifische Wiedergabe-URIs

Erstellen Sie Wiedergabe-URIs für jede unterstützte Plattform: Android TV, Android oder iOS. So kann das System den entsprechenden URI für die Videowiedergabe auf der jeweiligen Plattform auswählen.

In dem seltenen Fall, dass die Wiedergabe-URIs für alle Plattformen identisch sind, wiederholen Sie sie für jede Plattform.

// Required. Set this when you want recommended entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri
  .Builder()
  .setPlatformType(PlatformType.TYPE_ANDROID_TV)
  .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
  .build()

// Optional. Set this when you want recommended entities to show up on
// Google TV Android app
val playbackUriAndroid = PlatformSpecificUri
  .Builder()
  .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
  .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
  .build()

// Optional. Set this when you want recommended entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri
  .Builder()
  .setPlatformType(PlatformType.TYPE_IOS)
  .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
  .build()

val platformSpecificPlaybackUris =
  Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

// Provide appropriate rating for the system.
val contentRating = new RatingSystem
  .Builder()
  .setAgencyName("MPAA")
  .setRating("PG-13")
  .build()

Posterbilder

Für Posterbilder sind ein URI und Pixelabmessungen (Höhe und Breite) erforderlich. Sie können mehrere Posterbilder für verschiedene Formfaktoren angeben. Achten Sie jedoch darauf, dass alle Bilder ein Seitenverhältnis von 16:9 und eine Mindesthöhe von 200 Pixeln haben, damit die Entität „Empfehlungen“ korrekt angezeigt wird, insbesondere im Entertainment Space von Google. Bilder mit einer Höhe von weniger als 200 Pixeln werden möglicherweise nicht angezeigt.

Image image1 = new Image.Builder()
  .setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
  .setImageHeightInPixel(300)
  .setImageWidthInPixel(169)
  .build()

Image image2 = new Image.Builder()
  .setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
  .setImageHeightInPixel(640)
  .setImageWidthInPixel(360)
  .build()

// And other images for different form factors.
val images = Arrays.asList(image1, image2)

Grund für Empfehlung

Geben Sie optional einen Grund für die Empfehlung an, der von Google TV verwendet werden kann, um Gründe dafür zu erstellen, warum dem Nutzer ein bestimmter Film oder eine bestimmte Serie vorgeschlagen wird.

//Allows us to construct reason: "Because it is top 10 on your Channel"
val topOnPartner = RecommendationReasonTopOnPartner
  .Builder()
  .setNum(10) //any valid integer value
  .build()

//Allows us to construct reason: "Because it is popular on your Channel"
val popularOnPartner = RecommendationReasonPopularOnPartner
  .Builder()
  .build()

//Allows us to construct reason: "New to your channel, or Just added"
val newOnPartner = RecommendationReasonNewOnPartner
  .Builder()
  .build()

//Allows us to construct reason: "Because you watched Star Wars"
val watchedSimilarTitles = RecommendationReasonWatchedSimilarTitles
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .Builder()
  .build()

//Allows us to construct reason: "Recommended for you by ChannelName"
val recommendedForUser = RecommendationReasonRecommendedForUser
  .Builder()
  .build()

val watchAgain = RecommendationReasonWatchAgain
  .Builder()
  .build()

val fromUserWatchList = RecommendationReasonFromUserWatchlist
  .Builder()
  .build()

val userLikedOnPartner = RecommendationReasonUserLikedOnPartner
  .Builder()
  .setTitleName("Movie or TV Show Title")
  .build()

val generic = RecommendationReasonGeneric.Builder().build()

Anzeigezeitraum

Wenn eine Entität nur für einen begrenzten Zeitraum verfügbar sein soll, legen Sie eine benutzerdefinierte Ablaufzeit fest. Ohne explizite Ablaufzeit laufen Entitäten nach 60 Tagen automatisch ab und werden gelöscht. Legen Sie also nur dann eine Ablaufzeit fest, wenn die Entitäten früher ablaufen sollen. Sie können mehrere solcher Verfügbarkeitszeiträume angeben.

val window1 = DisplayTimeWindow
  .Builder()
  .setStartTimeStampMillis(now()+ 1.days.toMillis())
  .setEndTimeStampMillis(now()+ 30.days.toMillis())

val window2 = DisplayTimeWindow
  .Builder()
  .setEndTimeStampMillis(now()+ 30.days.toMillis())

val availabilityTimeWindows: List<DisplayTimeWindow> = listof(window1,window2)

DataFeedElementId

Wenn Sie Ihren Medienkatalog oder Ihren Media-Aktionsfeed in Google TV eingebunden haben, müssen Sie keine separaten Entitäten für Filme oder Serien erstellen. Stattdessen können Sie eine MediaActionFeedEntity erstellen, die das erforderliche Feld DataFeedElementId enthält. Diese ID muss eindeutig sein und mit der ID im Media-Aktionsfeed übereinstimmen, da sie zur Identifizierung aufgenommener Feedinhalte und zur Suche nach Medieninhalten verwendet wird.

val id = "dataFeedElementId"

MovieEntity

Hier ist ein Beispiel für das Erstellen einer MovieEntity mit allen erforderlichen Feldern:

val movieEntity = MovieEntity.Builder()
  .setName("Movie name")
  .setDescription("A sentence describing movie.")
  .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
  .addPosterImages(images)
  // Suppose the duration is 2 hours, it is 72000000 in milliseconds
  .setDurationMills(72000000)
  .setCallToActionText("Watch Now")
  .addTag("Action")
  .build()

Sie können zusätzliche Daten wie Genres, Altersfreigaben, Erscheinungsdatum, Grund für die Empfehlung und Verfügbarkeitszeiträume angeben, die von Google TV für erweiterte Anzeigen oder Filterzwecke verwendet werden können.

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("pg-13").build();
val contentRatings = Arrays.asList(rating1);
//Suppose release date is 11-02-2025
val releaseDate  = 1739233800000L
val movieEntity = MovieEntity.Builder()
  ...
  .addGenres(genres)
  .setReleaseDateEpochMillis(releaseDate)
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addAllAvailabilityTimeWindows(availabilityTimeWindows)
  .build()

TvShowEntity

Hier ist ein Beispiel für das Erstellen einer TvShowEntity mit allen erforderlichen Feldern:

val tvShowEntity = TvShowEntity.Builder()
  .setName("Show title")
  .setDescription("A sentence describing TV Show.")
  .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
  .addPosterImages(images)
  .setCallToActionText("Watch Now")
  .addTag("Drama")
  .build();

Optional können Sie zusätzliche Daten wie Genres, Altersfreigaben, Grund für die Empfehlung, Angebotspreis, Anzahl der Staffeln oder Verfügbarkeitszeitraum angeben, die von Google TV für erweiterte Anzeigen oder Filterzwecke verwendet werden können.

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build();
val price = Price.Builder()
  .setCurrentPrice("$14.99")
  .setStrikethroughPrice("$16.99")
  .build();
val contentRatings = Arrays.asList(rating1);
val seasonCount = 5;
val tvShowEntity = TvShowEntity.Builder()
  ...
  .addGenres(genres)
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addAllAvailabilityTimeWindows(availabilityTimeWindows)
  .setSeasonCount(seasonCount)
  .setPrice(price)
  .build()

MediaActionFeedEntity

Hier ist ein Beispiel für das Erstellen einer MediaActionFeedEntity mit allen erforderlichen Feldern:

val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setDataFeedElementId(id)
  .setCallToActionText("Watch Now")
  .addTag("Action")
  .build()

Optional können Sie zusätzliche Daten wie Beschreibung, Grund für die Empfehlung und Anzeigezeitraum angeben, die von Google TV für erweiterte Anzeigen oder Filterzwecke verwendet werden können.

val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setName("Movie name or TV Show name")
  .setDescription("A sentence describing an entity")
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addPosterImages(images)
  .build()

LiveTvChannelEntity

Diese Entität stellt einen Live-TV-Kanal dar. Hier ist ein Beispiel für das Erstellen einer LiveTvChannelEntity mit allen erforderlichen Feldern:

val liveTvChannelEntity = LiveTvChannelEntity.Builder()
  .setName("Channel Name")
  // ID of the live TV channel
  .setEntityId("https://www.example.com/channel/12345")
  .setDescription("A sentence describing this live TV channel.")
  // channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
  .addPlatformSpecificPlaybackUri(channelPlaybackUris)
  .addLogoImage(logoImage)
  .setCallToActionText("Watch Now")
  .addTag("News")
  .build()

Optional können Sie zusätzliche Daten wie Altersfreigaben oder Grund für die Empfehlung angeben.

val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build()
val contentRatings = Arrays.asList(rating1)

val liveTvChannelEntity = LiveTvChannelEntity.Builder()
  ...
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner)
  .build()

LiveTvProgramEntity

Diese Entität stellt eine Live-TV-Programmkachel dar, die auf einem Live-TV-Kanal ausgestrahlt wird oder deren Ausstrahlung geplant ist. Hier ist ein Beispiel für das Erstellen einer LiveTvProgramEntity mit allen erforderlichen Feldern:

val liveTvProgramEntity = LiveTvProgramEntity.Builder()
  // First set the channel information
  .setChannelName("Channel Name")
  .setChannelId("https://www.example.com/channel/12345")
  // channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
  .addPlatformSpecificPlaybackUri(channelPlaybackUris)
  .setChannelLogoImage(channelLogoImage)
  // Then set the program or card specific information.
  .setName("Program Name")
  .setEntityId("https://www.example.com/schedule/123")
  .setDescription("Program Description")
  .addAvailabilityTimeWindow(
      DisplayTimeWindow.Builder()
        .setStartTimestampMillis(1756713600000L)// 2025-09-01T07:30:00+0000
        .setEndTimestampMillis(1756715400000L))// 2025-09-01T08:00:00+0000
  .addPosterImage(programImage)
  .setCallToActionText("Watch Now")
  .addTag("Sports")
  .build()

Optional können Sie zusätzliche Daten wie Altersfreigaben, Genres oder Grund für die Empfehlung angeben.

val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build()
val contentRatings = Arrays.asList(rating1)
val genres = Arrays.asList("Action", "Science fiction")

val liveTvProgramEntity = LiveTvProgramEntity.Builder()
  ...
  .addContentRatings(contentRatings)
  .addGenres(genres)
  .setRecommendationReason(topOnPartner)
  .build()