Ten przewodnik zawiera instrukcje dla deweloperów dotyczące integracji rekomendowanych treści wideo za pomocą pakietu Engage SDK w celu wypełniania rekomendacji na różnych platformach Google, takich jak telewizor, telefon komórkowy i tablet.
Rekomendacje korzystają z grupy rekomendacji, aby wyświetlać filmy i seriale z różnych aplikacji w jednym układzie interfejsu. Każdy partner deweloper może przesyłać maksymalnie 25 elementów w każdym klastrze rekomendacji, a w przypadku każdego żądania może być maksymalnie 7 klastrów rekomendacji.
Przygotowanie
Zanim zaczniesz, wykonaj te czynności. 1. Sprawdź, czy Twoja aplikacja jest kierowana na interfejs API na poziomie 19 lub wyższym.
Dodaj bibliotekę
com.google.android.engage
do aplikacji.Do integracji służą osobne pakiety SDK: jeden do aplikacji mobilnych, a drugi do aplikacji na telewizory.
Urządzenia mobilne
dependencies { implementation 'com.google.android.engage:engage-core:1.5.5 }
do telewizora
dependencies { implementation 'com.google.android.engage:engage-tv:1.0.2 }
W pliku
AndroidManifest.xml
ustaw środowisko usługi Engage na produkcyjne.Aplikacja mobilna w formacie APK
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
Aplikacja na telewizor
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
Wykonaj publikowanie w usłudze na pierwszym planie.
publikować dane rekomendacji najwyżej raz dziennie, uruchamiając je za pomocą jednej z tych metod:
- Pierwsze logowanie użytkownika w danym dniu. (lub)
- Gdy użytkownik rozpoczyna interakcję z aplikacją.
Integracja
AppEngagePublishClient
publikuje klaster rekomendacji. Aby opublikować obiekt recommendations, użyj metody publishRecommendationClusters
.
Użyj isServiceAvailable()
2, aby sprawdzić, czy usługa jest dostępna do integracji.
val client = AppEngagePublishClient(context)
client.isServiceAvailable().addOnCompleteListener { task ->
if (task.isSuccessful) {
// Handle IPC call success
if(task.result) {
// Service is available on the device, proceed with content publish
// calls.
client.publishRecommendationClusters(recommendationRequest)
} else {
// Service is not available
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
}
Grupy rekomendacji i żądanie publikacji
Gromadzą one logicznie encji. Podane niżej przykłady kodu wyjaśniają, jak tworzyć klastry na podstawie preferencji oraz jak tworzyć prośby o opublikowanie dla wszystkich klastrów.
// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
.Builder()
.addEntity(movie)
.addEntity(tvShow)
.setTitle("Popular Movies")
.build()
// cluster for top searches
val recommendationCluster2 = RecommendationCluster
.Builder()
.addEntity(movie)
.addEntity(tvShow)
.setTitle("Top Searches")
.build()
// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
.Builder()
.setSyncAcrossDevices(true)
.setAccountProfile(accountProfile)
.addRecommendationCluster(recommendationCluster1)
.addRecommendationCluster(recommendationCluster2)
.build()
Tworzenie profilu konta
Aby umożliwić personalizację Google TV, podaj informacje o koncie i profilu. Użyj AccountProfile
, aby podać:
- Identyfikator konta: unikalny identyfikator reprezentujący konto użytkownika w aplikacji. Może to być rzeczywisty identyfikator konta lub jego zaciemniona wersja.
- Identyfikator profilu (opcjonalnie): jeśli Twoja aplikacja obsługuje wiele profili na jednym koncie, podaj unikalny identyfikator konkretnego profilu użytkownika.
- Język(opcjonalnie): możesz podać preferowany język użytkownika.
To pole jest przydatne, jeśli w polu
RecommendationRequest
wysyłaszMediaActionFeedEntity
.
// If app only supports account
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.build();
// If app supports both account and profile
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.setProfileId("profile_id")
.build();
// set Locale
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.setProfileId("profile_id")
.setLocale("en-US")
.build();
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonuje te działania:
- Istniejące dane
RecommendationsCluster
od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym pliku
RecommendationsCluster
. W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.
Synchronizacja na różnych urządzeniach
Flaga SyncAcrossDevices
określa, czy dane z grupowania rekomendacji użytkownika są udostępniane Google TV i czy są dostępne na jego urządzeniach, takich jak telewizor, telefon czy tablet. Aby rekomendacja działała, musi mieć wartość true.
Uzyskiwanie zgody
Aplikacja multimedialna musi zawierać wyraźne 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 odpowiednim publishRecommendations
żądaniu. Aby w pełni korzystać z funkcji obejmujących wiele urządzeń, sprawdź, czy aplikacja uzyskała zgodę użytkownika i czy umożliwia SyncAcrossDevices
do true
.
Usuwanie danych dotyczących wyszukiwania filmów
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 dotyczące odkrywania filmów na profilu konta lub na całym koncie.
Wyliczenie DeleteReason
określa powód 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 elementy, które reprezentują poszczególne typy elementów. W przypadku klastra Rekomendacje obsługiwane są te typy obiektów:
MediaActionFeedEntity
MovieEntity
TvShowEntity
Opis
Podaj krótki opis każdego elementu. Opis będzie wyświetlany, gdy użytkownicy najeżą kursorem na element, i zawierać będzie dodatkowe informacje.
Identyfikatory URI odtwarzania specyficzne dla platformy
Utwórz 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 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ść i szerokość). Ukierunkowuj reklamy na różne formaty, przesyłając wiele obrazów z plakatem, ale sprawdź, czy wszystkie obrazy mają współczynnik proporcji 16:9 i minimalną wysokość 200 pikseli, aby zapewnić prawidłowe wyświetlanie informacji „Rekomendacje”, zwłaszcza w miejscu na rozrywkę w Google. Obrazy o wysokości mniejszej niż 200 pikseli mogą nie być wyświetlane.
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 podaj powód rekomendacji, który może być wykorzystany przez Google TV do sformułowania powodów, dla których użytkownikowi ma zostać zasugerowany 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
.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 wyświetlania czasu
Jeśli element ma być dostępny tylko przez ograniczony czas, ustaw niestandardowy czas wygaśnięcia. Jeśli nie określisz wyraźnego czasu ważności, elementy wygasną automatycznie i zostaną usunięte po 60 dniach. Ustaw czas wygaśnięcia tylko wtedy, gdy encje muszą 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 zintegrowałeś swój katalog multimediów lub kanał danych działań związanych z multimediami z Google TV, nie musisz tworzyć osobnych jednostek dla filmów ani programów telewizyjnych. Zamiast tego możesz utworzyć jednostkę MediaActionFeed, która zawiera wymagane pole DataFeedElementId. Identyfikator musi być unikalny i pasować do identyfikatora w pliku danych z działaniami dotyczącymi multimediów, ponieważ pomaga identyfikować treści z przetworzonego pliku danych i przeszukiwać treści multimedialne.
val id = "dataFeedEleemntId"
MovieEntity
Oto przykład tworzenia obiektu MovieEntity
ze wszystkimi polami wymaganymi:
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)
.build()
Możesz podać dodatkowe dane, takie jak gatunki, oceny treści, data premiery, powód rekomendacji i okna dostępności, które mogą być wykorzystywane przez Google TV do wyświetlania ulepszonych treści 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 polami wymaganymi:
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
.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 mogą być używane przez Google TV do ulepszonych wyświetleń 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 polami wymaganymi:
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setDataFeedElementId(id)
.build()
Opcjonalnie możesz podać dodatkowe dane, takie jak opis, powód rekomendacji i czas wyświetlania, które mogą być wykorzystywane przez Google TV do wyświetlania ulepszonych treści 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()
Dzięki temu deweloperzy mogą integrować rekomendacje treści wideo w Google TV, zwiększając widoczność i zaangażowanie użytkowników oraz zapewniając im spójne i spersonalizowane wrażenia podczas oglądania na wszystkich urządzeniach.