Pakiet Engage SDK do rekomendacji wideo

Ten przewodnik zawiera instrukcje dla deweloperów dotyczące integrowania rekomendowanych treści wideo za pomocą pakietu Engage SDK, aby wyświetlać rekomendacje w różnych usługach Google, takich jak telewizor, telefon i tablet.

Rekomendacje wykorzystują klaster rekomendacji do wyświetlania filmów i seriali 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 na żądanie może przypadać maksymalnie 7 klastrów rekomendacji.

Przygotowanie

Wykonaj instrukcje przygotowania opisane w Przewodniku dla początkujących.

  1. Przeprowadź publikację w usłudze działającej na pierwszym planie.
  2. Publikuj dane rekomendacji najwyżej raz dziennie, w jednym z tych przypadków:
    • pierwsze logowanie użytkownika w danym dniu, (lub)
    • gdy użytkownik zacznie korzystać z aplikacji.

Integracja

AppEngagePublishClient publikuje klaster rekomendacji. Aby opublikować obiekt rekomendacji, użyj metody publishRecommendationClusters.

Zainicjuj klienta i sprawdź dostępność usługi zgodnie z opisem w Przewodniku dla początkujących.

client.publishRecommendationClusters(recommendationRequest)

Aktualizowanie klastrów rekomendacji

Klastry to logiczne grupowanie encji. Poniższe przykłady kodu pokazują, jak tworzyć klastry zgodnie z preferencjami oraz jak utworzyć żądanie publikacji i zaktualizować wszystkie klastry.

The RecommendationClusterType określa sposób wyświetlania klastra.

// 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 zostaną wykonane te działania:

  • Usunięte zostaną dotychczasowe dane RecommendationsCluster od partnera dewelopera.
  • Dane z żądania zostaną przeanalizowane i zapisane w zaktualizowanym klastrze RecommendationsCluster. W przypadku błędu całe żądanie zostanie odrzucone, a dotychczasowy stan zostanie zachowany.

Synchronizacja na innych urządzeniach

Flaga SyncAcrossDevices określa, czy dane klastra rekomendacji użytkownika są udostępniane w Google TV i dostępne na jego urządzeniach, takich jak telewizor, telefon i tablet. Aby rekomendacja działała, musi być ustawiona na true.

Aplikacja multimedialna musi mieć wyraźne ustawienie umożliwiające włączanie i wyłączanie synchronizacji na innych urządzeniach. Wyjaśnij użytkownikowi korzyści i zapisz jego preferencje, a następnie zastosuj je w żądaniu publishRecommendations. Aby w pełni wykorzystać funkcję na innym urządzeniu, sprawdź, czy aplikacja uzyskuje zgodę użytkownika i ustawia SyncAcrossDevices na true.

Usuwanie danych Engage

Aby ręcznie usunąć dane użytkownika z serwera Google TV przed standardowym 60-dniowym okresem przechowywania, użyj metody client.deleteClusters(). Po otrzymaniu żądania usługa usuwa wszystkie dotychczasowe dane Engage dotyczące profilu konta lub całego konta.

Wyliczenie 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(
  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()
)

Tworzenie encji

Pakiet SDK definiuje różne encje reprezentujące każdy typ produktu. W przypadku klastra rekomendacji obsługiwane są te encje:

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

Podawanie opisów

Podaj krótki opis każdej encji. Ten opis będzie wyświetlany, gdy użytkownicy najadą kursorem na encję, co pozwoli im uzyskać dodatkowe informacje.

Tekst wezwania do działania

W przypadku każdej encji możesz podać opcjonalny tekst wezwania do działania. Ten tekst będzie wyświetlany użytkownikowi, aby zachęcić go do interakcji.

Tagi

Opcjonalnie możesz podać listę tagów dla każdej encji. Tagi mogą służyć do kategoryzowania i filtrowania.

Identyfikatory URI odtwarzania specyficzne dla platformy

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 filmów na danej platformie.

W rzadkich przypadkach, gdy identyfikatory URI odtwarzania są identyczne na wszystkich platformach, powtórz je na każdej z nich.

// 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()

Obrazy plakatu

Obrazy plakatu wymagają identyfikatora URI i wymiarów w pikselach (wysokości i szerokości). Aby kierować reklamy na różne formaty, podaj kilka obrazów plakatu, ale sprawdź, czy wszystkie obrazy zachowują format obrazu 16:9 i minimalną wysokość 200 pikseli, aby encja „Rekomendacje” była wyświetlana prawidłowo, zwłaszcza w Entertainment Space. Obrazy o wysokości mniejszej niż 200 pikseli mogą się nie wyświetlać.

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)

Powód rekomendacji

Opcjonalnie możesz podać powód rekomendacji, który Google TV może wykorzystać do podania przyczyn sugerowania użytkownikowi konkretnego filmu lub serialu.

//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()

Okno czasu wyświetlania

Jeśli encja ma być dostępna tylko przez ograniczony czas, ustaw niestandardowy czas wygaśnięcia. Bez wyraźnego czasu wygaśnięcia encje automatycznie wygasną i zostaną usunięte po 60 dniach. Dlatego ustaw czas wygaśnięcia tylko wtedy, gdy encje mają wygasnąć wcześniej. Określ kilka takich okien dostępności.

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

Jeśli masz zintegrowany katalog multimediów lub plik danych działań multimedialnych z Google TV, nie musisz tworzyć oddzielnych encji dla filmu lub serialu. Zamiast tego możesz utworzyć MediaActionFeedEntity, która zawiera wymagane pole DataFeedElementId. Ten identyfikator musi być unikalny i zgodny z identyfikatorem w pliku danych działań multimedialnych, ponieważ pomaga identyfikować treści z pliku danych i wyszukiwać treści multimedialne.

val id = "dataFeedElementId"

MovieEntity

Oto przykład tworzenia encji MovieEntity ze wszystkimi wymaganymi polami:

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()

Możesz podać dodatkowe dane, takie jak gatunki, oceny treści, data premiery, powód rekomendacji i okna czasowe dostępności, które Google TV może wykorzystać 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 encji TvShowEntity ze wszystkimi wymaganymi polami:

val tvShowEntity = TvShowEntity.Builder()
  .setName("Show title")
  .setDescription("A sentence describing TV Show.")
  .addPlatformSpecificPlaybackUri(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 okno czasowe dostępności, które Google TV może wykorzystać 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 encji 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 czas wyświetlania, które Google TV może wykorzystać do ulepszonego 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 encji 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
  .addPlatformSpecificPlaybackUri(channelPlaybackUris)
  .addLogoImage(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 lub ma być emitowany na kanale telewizji na żywo. Oto przykład tworzenia encji 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
  .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()

Opcjonalnie możesz podać 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()