Bu kılavuzda, geliştiricilerin TV, mobil cihaz ve tablet gibi Google platformlarında öneri deneyimlerini doldurmak için Engage SDK'sını kullanarak önerilen video içeriklerini entegre etme talimatları yer almaktadır.
Öneriler, tek bir kullanıcı arayüzü gruplandırmasında birden fazla uygulamadan film ve TV programı göstermek için Öneri kümesinden yararlanı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.
Ön çalışma
Başlamadan önce aşağıdaki adımları tamamlayın. 1. Uygulamanızın bu entegrasyon için API düzeyi 19 veya üstünü hedeflediğini doğrulayın.
com.google.android.engage
kitaplığını uygulamanıza ekleyin.Entegrasyonda kullanılacak ayrı SDK'lar vardır: biri mobil uygulamalar için, diğeri TV uygulamaları için.
Mobil için
dependencies { implementation 'com.google.android.engage:engage-core:1.5.5 }
TV için
dependencies { implementation 'com.google.android.engage:engage-tv:1.0.2 }
AndroidManifest.xml
dosyasında Engage hizmet ortamını üretim olarak ayarlayın.Mobil APK için
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
For tv apk
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
Ön plan hizmetinde yayınlama işlemini yürütün.
Öneriler verilerini en fazla günde bir kez yayınlayın. Bu işlem aşağıdakilerden biri tarafından tetiklenir:
- Kullanıcının günün ilk girişi. (veya)
- Kullanıcı uygulamayla etkileşime geçtiğinde.
Entegrasyon
AppEngagePublishClient
, öneri kümesini yayınlar. Öneriler nesnesi yayınlamak için publishRecommendationClusters
yöntemini kullanın.
Hizmetin entegrasyon için uygun olup olmadığını kontrol etmek üzere isServiceAvailable()
2 değerini kullanın.
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.
}
}
Öneri kümeleri ve yayınlama isteği
Kümeler, öğelerin mantıksal gruplandırılmasıdır. Aşağıdaki kod örnekleri, kümelerin tercihinize göre nasıl oluşturulacağını ve tüm kümeler için yayınlama isteği oluşturmayı açıklar.
// 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()
Hesap profili oluşturma
Google TV'de kişiselleştirilmiş bir deneyim sunmak için hesap ve profil bilgilerini sağlayın. Aşağıdakileri sağlamak için AccountProfile
simgesini kullanın:
- Hesap kimliği: Kullanıcının uygulamanızdaki hesabını temsil eden benzersiz bir tanımlayıcıdır. Bu, gerçek hesap kimliği veya uygun şekilde karartılmış bir sürüm olabilir.
- Profil kimliği (isteğe bağlı): Uygulamanız tek bir hesapta birden fazla profili destekliyorsa belirli bir kullanıcı profili için benzersiz bir tanımlayıcı sağlayın.
- Yerel ayar(isteğe bağlı): İsteğe bağlı olarak kullanıcının tercih ettiği dili belirtebilirsiniz.
Bu alan,
RecommendationRequest
içindeMediaActionFeedEntity
gönderiyorsanız yararlıdır.
// 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();
Hizmet isteği aldığında tek bir işlemde aşağıdaki işlemler gerçekleşir:
- Geliştirici iş ortağının mevcut
RecommendationsCluster
verileri kaldırılır. - İstekten gelen veriler ayrıştırılır ve güncellenen
RecommendationsCluster
öğesinde depolanır. Hata olması 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 cihazlarda kullanılıp kullanılamayacağını kontrol eder. Önerinin çalışması için true olarak ayarlanması gerekir.
İzin alma
Medya uygulaması, cihazlar arası senkronizasyonu etkinleştirmek veya devre dışı bırakmak için net bir ayar sağlamalıdır. Kullanıcıya avantajları açıklayın ve kullanıcının tercihini bir kez saklayıp 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 geçiş yapma özelliğini etkinleştirdiğini doğrulayın.
Video keşfi verilerini silme
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. Hizmet, isteği aldıktan sonra hesap profili veya hesabın tamamı için mevcut tüm video keşfi verilerini siler.
DeleteReason
enum, 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(
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()
)
Varlık oluşturma
SDK, her öğe türünü temsil etmek için farklı öğeler tanımlamıştır. Öneri kümesi için aşağıdaki varlıklar desteklenir:
MediaActionFeedEntity
MovieEntity
TvShowEntity
Açıklama
Her öğe için kısa bir açıklama girin. Bu açıklama, kullanıcılar fare imlecini öğenin üzerine getirdiğinde gösterilerek onlara ek ayrıntılar sağlar.
Platforma özel oynatma URI'leri
Desteklenen her platform için oynatma URI'leri oluşturun: Android TV, Android veya iOS. 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 = new RatingSystem
.Builder()
.setAgencyName("MPAA")
.setRating("PG-13")
.build()
Poster resimleri
Afiş resimleri için bir URI ve piksel boyutları (yükseklik ve genişlik) gerekir. Birden fazla poster resmi sağlayarak farklı form faktörlerini hedefleyin ancak özellikle Google'ın Eğlence Alanı'nda "Öneriler" öğesinin 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.
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)
Öneri nedeni
İsteğe bağlı olarak, Google TV'nin kullanıcıya belirli bir filmi veya TV dizisini neden önerdiğini belirtmek 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
.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()
Görüntüleme zaman aralığı
Bir öğe yalnızca sınırlı bir süre için kullanılacaksa özel bir geçerlilik bitiş tarihi ayarlayın. Belirli bir geçerlilik bitiş süresi belirtilmezse öğeler 60 gün sonra otomatik olarak süresi dolacak ve silinecektir. Bu nedenle, yalnızca öğelerin geçerlilik süresinin daha erken sona ermesi gerektiğinde bir geçerlilik süresi ayarlayın. Bu tür birden fazla bilgi dokümanı aralığı belirtebilirsiniz.
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
Medya kataloğunuzu veya medya işlem feed'inizi Google TV ile entegre ettiyseniz Film veya TV dizisi için ayrı öğeler oluşturmanız gerekmez. Bunun yerine, gerekli DataFeedElementId alanını içeren bir MediaActionFeed öğesi oluşturabilirsiniz. Bu kimlik, beslenen feed içeriğini tanımlamaya ve medya içeriği aramaları yapmaya yardımcı olduğu için benzersiz olmalı ve Media Action Feed'deki kimlikle eşleşmelidir.
val id = "dataFeedEleemntId"
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.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
// Suppose the duration is 2 hours, it is 72000000 in milliseconds
.setDurationMills(72000000)
.build()
Tür, içerik derecelendirmesi, 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ülemeler 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.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
.build();
İsteğe bağlı olarak, Google TV tarafından gelişmiş görüntülemeler veya filtreleme amacıyla kullanılabilecek türler, içerik derecelendirmeleri, öneri nedeni, teklif fiyatı, sezon sayısı veya kullanılabilirlik zaman aralığı gibi ek veriler sağlayabilirsiniz.
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)
.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ülemeler 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()
Geliştiriciler bu adımları uygulayarak video içerik önerilerini Google TV'ye başarıyla entegre edebilir, kullanıcıların içerikleri keşfetme ve etkileşim kurma oranlarını artırabilir, tüm cihazlarında kullanıcılara tutarlı ve kişiselleştirilmiş bir izleme deneyimi sunabilir.