Bu kılavuzda, geliştiricilerin Engage SDK'yı kullanarak önerilen video içeriklerini entegre etme ve TV, mobil cihaz ve tablet gibi Google platformlarında öneri deneyimleri oluşturma ile ilgili talimatlar yer almaktadır.
Öneri, tek bir kullanıcı arayüzü grubunda birden fazla uygulamadan film ve TV programı göstermek için Öneri kümesini kullanır. Her geliştirici iş ortağı, her öneri kümesinde en fazla 25 öğe yayınlayabilir ve istek başına en fazla 7 öneri kümesi olabilir.
Kişiselleştirilmemiş önerileri bir TV uygulaması yerine doğrudan arka uç sunucularınızdan göndermek için REST API kullanarak önerileri entegre etme başlıklı makaleyi inceleyin.
Ön çalışma
Başlangıç kılavuzundaki Ön çalışma talimatlarını tamamlayın.
- Ön plan hizmetinde yayınlama işlemini yürütme
- Öneri verilerini günde en fazla bir kez yayınlayın. Bu işlem, aşağıdakilerden biri tarafından tetiklenir:
- Kullanıcının gün içindeki ilk girişi. (veya)
- Kullanıcı uygulamayla etkileşime geçmeye başladığında.
Entegrasyon
AppEngagePublishClient, öneri kümesini yayınlar. Öneri nesnesi yayınlamak için publishRecommendationClusters yöntemini kullanın.
Başlangıç kılavuzunda açıklandığı şekilde istemciyi başlatın ve hizmet kullanılabilirliğini kontrol edin.
client.publishRecommendationClusters(recommendationRequest)
Öneri kümeleri ekleniyor/güncelleniyor
Kümeler, varlıkların mantıksal gruplandırmasıdır. Aşağıdaki kod örneklerinde, tercihlerinize göre kümelerin nasıl oluşturulacağı, yayınlama isteğinin nasıl oluşturulacağı ve tüm kümelerin nasıl güncelleneceği açıklanmaktadır.
RecommendationClusterType, kümenin nasıl
görüntüleneceğini belirler.
// 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()
Hizmet isteği aldığında tek bir işlemde aşağıdaki eylemler gerçekleşir:
- Geliştirici iş ortağından alınan mevcut
RecommendationsClusterverileri kaldırılır. - İstekten alınan veriler ayrıştırılır ve güncellenen
RecommendationsClusteriçinde depolanır. Hata durumunda isteğin tamamı reddedilir ve mevcut durum korunur.
Cihazlar arası senkronizasyon
SyncAcrossDevices işareti, kullanıcının öneri kümesi verilerinin Google TV ile paylaşılıp paylaşılmayacağını ve TV, telefon, tablet gibi cihazlarında kullanılabilir olup olmayacağını kontrol eder. Önerinin çalışması için bu değerin "true" olarak ayarlanması gerekir.
İzin alın
Medya uygulaması, cihazlar arası senkronizasyonu etkinleştirmek veya devre dışı bırakmak için net bir ayar sunmalıdır. Kullanıcıya avantajları açıklayın ve kullanıcının tercihini bir kez kaydedip publishRecommendations isteğinde buna göre uygulayın. Cihazlar arası özellikten en iyi şekilde yararlanmak için uygulamanın kullanıcı izni aldığını ve SyncAcrossDevices ile true arasında bağlantı kurduğunu doğrulayın.
Etkileşim verilerini silme
Bir kullanıcının verilerini, standart 60 günlük saklama süresinden önce Google TV sunucusundan manuel olarak silmek için client.deleteClusters() yöntemini kullanın. İstek alındığında hizmet, hesap profili veya hesabın tamamı için mevcut tüm Engage verilerini siler.
DeleteReason enum'u, veri silme nedenini tanımlar.
Aşağıdaki kod, çıkış yapıldığında önerileri kaldırır.
// 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()
)
Varlık oluşturma
SDK, her öğe türünü temsil etmek için farklı varlıklar tanımlamıştır. Öneri kümesi için aşağıdaki varlıklar desteklenir:
Açıklama ekleme
Her öğe için kısa bir açıklama girin. Bu açıklama, kullanıcılar fareyle öğenin üzerine geldiğinde gösterilir ve onlara ek ayrıntılar sağlar.
Harekete geçirici mesaj
Her öğe için isteğe bağlı bir harekete geçirici mesaj metni sağlayın. Bu metin, etkileşimi teşvik etmek için kullanıcıya gösterilir.
Etiketler
İsteğe bağlı olarak her öğe için bir etiket listesi sağlayın. Etiketler, kategorizasyon ve filtreleme için kullanılabilir.
Platforma özgü oynatma URI'leri
Desteklenen her platform (Android TV, Android veya iOS) için oynatma URI'leri oluşturun. Bu sayede sistem, ilgili platformda video oynatmak için uygun URI'yi seçebilir.
Oynatma URI'lerinin tüm platformlar için aynı olduğu nadir durumlarda, her platform için tekrarlayın.
// 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()
Poster resimleri
Poster resimleri için URI ve piksel boyutları (yükseklik ve genişlik) gerekir. Birden fazla poster resmi sağlayarak farklı form faktörlerini hedefleyin ancak "Öneriler" varlığının özellikle Google'ın Entertainment Space'inde doğru şekilde gösterilmesi için tüm resimlerin 16:9 en-boy oranına ve en az 200 piksel yüksekliğe sahip olduğunu doğrulayın. Yüksekliği 200 pikselden az olan resimler gösterilmeyebilir.
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)
Öneri nedeni
İsteğe bağlı olarak, Google TV'nin kullanıcıya belirli bir film veya TV programı önerme nedenlerini oluşturmak için kullanabileceği bir öneri nedeni sağlayın.
//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()
Görüntüleme zaman aralığı
Bir varlığın yalnızca sınırlı bir süre için kullanılabilir olması gerekiyorsa özel bir geçerlilik bitiş zamanı ayarlayın. Açık bir geçerlilik bitiş zamanı belirtilmezse varlıkların geçerliliği otomatik olarak sona erer ve 60 gün sonra silinir. Bu nedenle, geçerlilik bitiş zamanını yalnızca varlıkların daha erken geçerliliğini yitirmesi gerektiğinde ayarlayın. Bu tür birden fazla kullanım dönemi belirtebilirsiniz.
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
Medya kataloğunuzu veya medya işlemi feed'inizi Google TV ile entegre ettiyseniz film veya TV programı için ayrı öğeler oluşturmanız gerekmez. Bunun yerine, zorunlu DataFeedElementId alanını içeren bir MediaActionFeedEntity oluşturabilirsiniz. Bu kimlik benzersiz olmalı ve Medya İşlemi Feed'indeki kimlikle eşleşmelidir. Bu kimlik, alınan feed içeriğini tanımlamaya ve medya içeriği aramaları yapmaya yardımcı olur.
val id = "dataFeedElementId"
MovieEntity
Aşağıda, tüm zorunlu alanları içeren bir MovieEntity oluşturma örneği verilmiştir:
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()
Türler, içerik derecelendirmeleri, yayın tarihi, öneri nedeni ve kullanılabilirlik zaman aralıkları gibi ek veriler sağlayabilirsiniz. Bu veriler, Google TV tarafından gelişmiş görüntüleme veya filtreleme amacıyla kullanılabilir.
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
Aşağıda, tüm zorunlu alanları içeren bir TvShowEntity oluşturma örneği verilmiştir:
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
.addPosterImages(images)
.setCallToActionText("Watch Now")
.addTag("Drama")
.build()
İsteğe bağlı olarak türler, içerik derecelendirmeleri, öneri nedeni, teklif fiyatı, sezon sayısı veya kullanılabilirlik zaman aralığı gibi ek veriler sağlayabilirsiniz. Bu veriler, Google TV tarafından gelişmiş görüntüleme veya filtreleme amacıyla kullanılabilir.
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
Aşağıda, tüm zorunlu alanları içeren bir MediaActionFeedEntity oluşturma örneği verilmiştir:
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setDataFeedElementId(id)
.setCallToActionText("Watch Now")
.addTag("Action")
.build()
İsteğe bağlı olarak açıklama, öneri nedeni ve görüntüleme zaman aralığı gibi ek veriler sağlayabilirsiniz. Bu veriler, Google TV tarafından gelişmiş görüntüleme veya filtreleme amacıyla kullanılabilir.
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
Bu, canlı TV kanalını temsil eder. Aşağıda, tüm zorunlu alanları içeren bir LiveTvChannelEntity oluşturma örneği verilmiştir:
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()
İsteğe bağlı olarak, içerik derecelendirmeleri veya öneri nedeni gibi ek veriler sağlayın.
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
Bu, bir canlı TV kanalında yayınlanan veya yayınlanması planlanan canlı TV programı kartını temsil eder. Aşağıda, tüm zorunlu alanları içeren bir LiveTvProgramEntity oluşturma örneği verilmiştir:
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()
İsteğe bağlı olarak içerik derecelendirmeleri, türler veya öneri nedeni gibi ek veriler sağlayın.
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()