Dieser Leitfaden enthält Anleitungen für Entwickler, wie sie ihre empfohlenen Videoinhalte mithilfe des Engage SDK einbinden können, um Empfehlungen auf Google-Oberflächen wie Fernsehern, Smartphones und Tablets zu präsentieren.
Die Empfehlung nutzt den Empfehlungscluster, um Filme und Serien aus mehreren Apps in einer UI-Gruppierung anzuzeigen. Jeder Entwicklerpartner kann maximal 25 Entitäten in jedem Empfehlungscluster übertragen und es kann maximal 7 Empfehlungscluster pro Anfrage geben.
Wenn du nicht personalisierte Empfehlungen direkt von deinen Backend-Servern statt von einer TV-App senden möchtest, findest du weitere Informationen unter Empfehlungen über die REST API einbinden.
Vorarbeit
Führen Sie die Schritte im Abschnitt Vorbereitung des Startleitfadens aus.
- Veröffentlichung in einem Dienst im Vordergrund ausführen.
- Empfehlungsdaten werden höchstens einmal täglich veröffentlicht, ausgelöst durch eine der folgenden Optionen:
- Erste Anmeldung des Nutzers am 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 Dienstverfügbarkeit, wie im Startleitfaden beschrieben.
client.publishRecommendationClusters(recommendationRequest)
Empfehlungscluster einfügen oder aktualisieren
Cluster sind logische Gruppen der Entitäten. In den folgenden Codebeispielen wird erläutert, wie Sie die Cluster nach Ihren Wünschen erstellen, eine Veröffentlichungsanfrage erstellen und alle Cluster 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 empfängt, werden die folgenden Aktionen innerhalb einer Transaktion ausgeführt:
- Vorhandene
RecommendationsCluster-Daten des Entwicklerpartners werden entfernt. - Die Daten aus der Anfrage werden geparst und im aktualisierten
RecommendationsClustergespeichert. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.
Geräte synchronisieren
Das Flag SyncAcrossDevices steuert, ob die Daten des Empfehlungsclusters eines Nutzers mit Google TV geteilt werden und auf seinen Geräten wie Fernseher, Smartphone und Tablets verfügbar sind. Damit die Empfehlung funktioniert, muss sie auf „true“ gesetzt sein.
Einwilligung einholen
Die Medien-App muss eine klare Einstellung zum Aktivieren oder Deaktivieren der geräteübergreifenden Synchronisierung bieten. Erläutere dem Nutzer die Vorteile, speichere seine Einstellung einmal und wende sie entsprechend in der publishRecommendations-Anfrage an. Damit Sie die geräteübergreifende Funktion optimal nutzen können, müssen Sie prüfen, ob die App die Einwilligung des Nutzers einholt und SyncAcrossDevices bis true aktiviert.
Engage-Daten löschen
Wenn du die Daten eines Nutzers vor Ablauf der standardmäßigen Aufbewahrungsdauer von 60 Tagen manuell vom Google TV-Server löschen möchtest, verwende 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.
Das Enum DeleteReason 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(
DeleteClustersRequest.Builder()
.setAccountProfile(accountProfile)
.setDeleteReason(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(
DeleteClustersRequest.Builder()
.setAccountProfile(accountProfile)
.setDeleteReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
.build()
)
Entitäten erstellen
Im SDK sind verschiedene Entitäten definiert, die die einzelnen Artikeltypen darstellen. Die folgenden Entitäten werden für den Empfehlungscluster unterstützt:
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 für jede Entität einen optionalen Call-to-Action-Text an. Dieser Text wird dem Nutzer angezeigt, um ihn zur Interaktion anzuregen.
Tags
Optional können Sie für jede Entität eine Liste von Tags angeben. 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 = RatingSystem
.Builder()
.setAgencyName("MPAA")
.setRating("PG-13")
.build()
Posterbilder
Für Posterbilder sind ein URI und Pixelabmessungen (Höhe und Breite) erforderlich. Du kannst verschiedene Formfaktoren ansprechen, indem du mehrere Posterbilder bereitstellst. Achte aber 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.
val image1 = Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
.setImageHeightInPixel(300)
.setImageWidthInPixel(169)
.build()
val image2 = 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
Optional können Sie einen Grund für die Empfehlung angeben, den Google TV verwenden kann, um Gründe dafür zu formulieren, 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
.Builder()
.addSimilarWatchedTitleName("Movie or TV Show Title")
.addSimilarWatchedTitleName("Movie or TV Show Title")
.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 userLikedTitle = RecommendationReasonUserLikedTitle
.Builder()
.setLikedTitleName("Movie or TV Show Title")
.build()
val generic = RecommendationReasonGeneric.Builder().build()
Zeitfenster für die Anzeige
Wenn eine Entität nur für eine begrenzte Zeit verfügbar sein soll, legen Sie eine benutzerdefinierte Ablaufzeit fest. Ohne explizite Ablaufzeit laufen Entitäten automatisch ab und werden nach 60 Tagen gelöscht. Legen Sie also nur dann eine Ablaufzeit fest, wenn die Entitäten früher ablaufen müssen. Geben Sie mehrere solcher Verfügbarkeitszeiträume an.
val window1 = DisplayTimeWindow
.Builder()
.setStartTimestampMillis(now() + 1.days.toMillis())
.setEndTimestampMillis(now() + 30.days.toMillis())
.build()
val window2 = DisplayTimeWindow
.Builder()
.setEndTimestampMillis(now() + 30.days.toMillis())
.build()
val availabilityTimeWindows: List<DisplayTimeWindow> = listOf(window1, window2)
DataFeedElementId
Wenn du deinen Medienkatalog oder Media Action-Feed in Google TV integriert hast, musst du keine separaten Entitäten für Filme oder Serien erstellen. Stattdessen kannst du ein MediaActionFeedEntity erstellen, das das Pflichtfeld „DataFeedElementId“ enthält. Diese ID muss eindeutig sein und mit der ID im Media Action-Feed übereinstimmen, da sie dazu dient, aufgenommene Feedinhalte zu identifizieren und Medieninhalte zu suchen.
val id = "dataFeedElementId"
MovieEntity
Hier ein Beispiel für das Erstellen eines MovieEntity mit allen erforderlichen Feldern:
val movieEntity = MovieEntity.Builder()
.setName("Movie name")
.setDescription("A sentence describing movie.")
.addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
.addPosterImages(images)
// Suppose the duration is 2 hours, it is 72000000 in milliseconds
.setDurationMillis(72000000)
.setCallToActionText("Watch Now")
.addTag("Action")
.build()
Du kannst zusätzliche Daten wie Genres, Altersfreigaben, Erscheinungsdatum, Empfehlungsgrund und Verfügbarkeitszeiträume angeben, die von Google TV für erweiterte Darstellungen 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 ein Beispiel für das Erstellen eines TvShowEntity mit allen erforderlichen Feldern:
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
.addPosterImages(images)
.setCallToActionText("Watch Now")
.addTag("Drama")
.build()
Optional können Sie zusätzliche Daten wie Genres, Altersfreigaben, Empfehlungsgrund, 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 ein Beispiel für das Erstellen eines 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, Empfehlungsgrund 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
Dies ist ein Live-TV-Kanal. Hier ein Beispiel für das Erstellen eines 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
.addPlatformSpecificPlaybackUris(channelPlaybackUris)
.setLogoImage(logoImage)
.setCallToActionText("Watch Now")
.addTag("News")
.build()
Optional können Sie zusätzliche Daten wie Altersfreigaben oder den 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
Dies ist eine Karte für ein Live-TV-Programm, das auf einem Live-TV-Kanal ausgestrahlt wird oder werden soll. Hier ein Beispiel für das Erstellen eines 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
.addPlatformSpecificPlaybackUris(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
.build()
)
.addPosterImage(programImage)
.setCallToActionText("Watch Now")
.addTag("Sports")
.build()
Optional können Sie zusätzliche Daten wie Altersfreigaben, Genres oder den 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()