Ten przewodnik zawiera instrukcje dla deweloperów dotyczące integracji polecanych treści wideo za pomocą pakietu Engage SDK w celu wyświetlania rekomendacji na platformach Google, takich jak telewizory, telefony i tablety.
Rekomendacje wykorzystują grupę rekomendacji do wyświetlania filmów i programów telewizyjnych z wielu aplikacji w jednym układzie interfejsu. Każdy partner deweloper może transmitować maksymalnie 25 elementów w każdym klastrze rekomendacji, a w każdym żądaniu może być maksymalnie 7 klastrów rekomendacji.
Aby wysyłać niespersonalizowane rekomendacje bezpośrednio z serwerów backendu zamiast z aplikacji TV, zapoznaj się z artykułem Integracja rekomendacji za pomocą interfejsu REST API.
Przygotowanie
Wykonaj czynności opisane w sekcji Prace wstępne w Przewodniku dla początkujących.
- Publikowanie powinno być wykonywane w usłudze na pierwszym planie.
- Publikuj dane rekomendacji maksymalnie raz dziennie, wywoływane przez:
- Pierwsze logowanie użytkownika w danym dniu. (lub)
- Gdy użytkownik zaczyna korzystać z aplikacji.
Integracja
AppEngagePublishClient publikuje klaster rekomendacji. Użyj metody publishRecommendationClusters, aby opublikować obiekt rekomendacji.
Pamiętaj, aby zainicjować klienta i sprawdzić dostępność usługi zgodnie z opisem w Przewodniku dla początkujących.
client.publishRecommendationClusters(recommendationRequest)
Aktualizuję klastry rekomendacji
Klastry to logiczne grupy encji. Poniższe przykłady kodu pokazują, jak tworzyć klastry na podstawie preferencji oraz jak utworzyć żądanie publikacji i wykonać operację upsert na wszystkich klastrach.
RecommendationClusterType określa, jak będzie wyświetlany klaster.
// 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()
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonywane są te działania:
- Istniejące dane
RecommendationsClusterod partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym obiekcie
RecommendationsCluster. W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.
Synchronizacja na innych urządzeniach
Flaga SyncAcrossDevices określa, czy dane klastra rekomendacji użytkownika są udostępniane Google TV i dostępne na jego urządzeniach, takich jak telewizor, telefon czy tablet. Aby rekomendacja działała, musi mieć wartość Prawda.
Uzyskiwanie zgody
Aplikacja multimedialna musi udostępniać przejrzyste ustawienie umożliwiające włączanie i wyłączanie synchronizacji między urządzeniami. Wyjaśnij użytkownikowi korzyści i zapisz jego preferencje, a następnie zastosuj je w odpowiedni sposób w żądaniu publishRecommendations. Aby w pełni wykorzystać możliwości funkcji obejmujących wiele urządzeń, sprawdź, czy aplikacja uzyskuje zgodę użytkownika i umożliwia SyncAcrossDevices na true.
Usuwanie danych Engage
Aby ręcznie usunąć dane użytkownika z serwera Google TV przed upływem standardowego 60-dniowego okresu przechowywania, użyj metody client.deleteClusters(). Po otrzymaniu prośby usługa usuwa wszystkie istniejące dane Engage z profilu konta lub z całego konta.
Typ wyliczeniowy DeleteReason określa przyczynę usunięcia danych.
Poniższy kod usuwa rekomendacje po wylogowaniu.
// 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()
)
Tworzenie encji
Pakiet SDK definiuje różne encje reprezentujące poszczególne typy produktów. W przypadku klastra rekomendacji obsługiwane są te encje:
Podaj opisy.
Podaj krótki opis każdego elementu. Ten opis będzie się wyświetlać, gdy użytkownicy najadą kursorem na element, i będzie zawierać dodatkowe informacje.
Tekst wezwania do działania
Podaj opcjonalny tekst wezwania do działania dla każdego elementu. Ten tekst będzie wyświetlany użytkownikowi, aby zachęcić go do zaangażowania.
Tagi
Opcjonalnie możesz podać listę tagów dla każdej encji. Tagi mogą służyć do kategoryzacji i filtrowania.
Identyfikatory URI odtwarzania na danej platformie
Utwórz identyfikatory URI odtwarzania dla każdej obsługiwanej platformy: Android TV, Android lub iOS. Dzięki temu system może wybrać odpowiedni identyfikator URI do odtwarzania filmu na danej platformie.
W rzadkich przypadkach, gdy identyfikatory URI odtwarzania są identyczne na wszystkich platformach, powtórz je dla każdej platformy.
// 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()
Obrazy plakatu
Obrazy plakatu wymagają identyfikatora URI i wymiarów w pikselach (wysokość i szerokość). Możesz kierować reklamy na różne formaty, udostępniając wiele obrazów plakatów, ale sprawdź, czy wszystkie obrazy mają format obrazu 16:9 i minimalną wysokość 200 pikseli, aby element „Rekomendacje” wyświetlał się prawidłowo, zwłaszcza w Przestrzeni rozrywki Google. Obrazy o wysokości mniejszej niż 200 pikseli mogą nie być wyświetlane.
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)
Powód rekomendacji
Opcjonalnie podaj powód rekomendacji, który może być używany przez Google TV do tworzenia powodów, dla których warto zasugerować użytkownikowi konkretny film lub program telewizyjny.
//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()
Przedział czasu wyświetlania
Jeśli encja powinna być dostępna tylko przez ograniczony czas, ustaw niestandardowy czas ważności. Jeśli nie określisz czasu ważności, encje automatycznie wygasną i zostaną usunięte po 60 dniach. Dlatego ustaw czas wygaśnięcia tylko wtedy, gdy encje muszą wygasnąć wcześniej. Możesz określić kilka takich okresów dostępności.
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
Jeśli masz katalog multimediów lub plik danych akcji multimedialnych zintegrowany z Google TV, nie musisz tworzyć osobnych elementów dla filmu lub serialu i programu telewizyjnego. Zamiast tego możesz utworzyć MediaActionFeedEntity, który zawiera wymagane pole DataFeedElementId. Ten identyfikator musi być unikalny i zgodny z identyfikatorem w pliku danych akcji multimedialnych, ponieważ pomaga identyfikować przetworzone treści z pliku danych i wyszukiwać treści multimedialne.
val id = "dataFeedElementId"
MovieEntity
Oto przykład tworzenia obiektu MovieEntity ze wszystkimi wymaganymi polami:
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()
Możesz podać dodatkowe dane, takie jak gatunki, oceny treści, data premiery, powód rekomendacji i przedziały czasu dostępności, które mogą być używane przez Google TV do ulepszonego wyświetlania lub filtrowania.
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
Oto przykład tworzenia obiektu TvShowEntity ze wszystkimi wymaganymi polami:
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
.addPosterImages(images)
.setCallToActionText("Watch Now")
.addTag("Drama")
.build()
Opcjonalnie możesz podać dodatkowe dane, takie jak gatunki, oceny treści, powód rekomendacji, cena oferty, liczba sezonów lub przedział czasu dostępności, które mogą być używane przez Google TV do ulepszonego wyświetlania lub filtrowania.
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
Oto przykład tworzenia obiektu MediaActionFeedEntity ze wszystkimi wymaganymi polami:
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setDataFeedElementId(id)
.setCallToActionText("Watch Now")
.addTag("Action")
.build()
Opcjonalnie możesz podać dodatkowe dane, takie jak opis, powód rekomendacji i przedział czasu wyświetlania, które mogą być używane przez Google TV do ulepszania wyświetlania lub filtrowania.
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
Reprezentuje kanał telewizji na żywo. Oto przykład tworzenia obiektu LiveTvChannelEntity ze wszystkimi wymaganymi polami:
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()
Opcjonalnie możesz podać dodatkowe dane, takie jak oceny treści lub powód rekomendacji.
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
Reprezentuje kartę programu telewizyjnego na żywo, który jest emitowany lub zaplanowany do emisji na kanale telewizyjnym na żywo. Oto przykład tworzenia obiektu LiveTvProgramEntity ze wszystkimi wymaganymi polami:
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()
Opcjonalnie podaj dodatkowe dane, takie jak oceny treści, gatunki lub powód rekomendacji.
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()