Bu kılavuzda, geliştiricilerin Engage SDK'yı kullanarak uygulama aboneliği ve hak verilerini Google TV ile paylaşmasıyla ilgili talimatlar yer almaktadır. Kullanıcılar, hak kazandıkları içerikleri bulabilir ve Google TV'nin TV, mobil cihaz ve tabletteki Google TV deneyimlerinde doğrudan kullanıcılara son derece alakalı içerik önerileri sunmasını sağlayabilir.
Ön koşullar
Cihaz yetkilendirme API'sini kullanabilmeniz için medya işlemleri feed'inin ilk katılım sürecini tamamlamanız gerekir. Henüz yapmadıysanız medya işlemleri feed'i erişim izni verme sürecini tamamlayın.
Ön çalışma
Başlamadan önce aşağıdaki adımları tamamlayın: Uygulamanızın bu entegrasyon için API düzeyi 19 veya sonraki sürümleri hedeflediğini doğrulayın.
Uygulamanıza
com.google.android.engagekitaplığını ekleyin:Entegrasyonda kullanılacak ayrı SDK'lar vardır: biri mobil uygulamalar, diğeri ise TV uygulamaları için.
Mobil cihazlar 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.xmldosyasında Engage hizmet ortamını üretime ayarlayın.Mobil APK için
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>TV için APK
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>APK'yı Google'a göndermeden önce AndroidManifest.xml dosyanızda Engage hizmeti ortamını üretime ayarlayın. Optimum performans ve gelecekteki uyumluluk için verileri yalnızca uygulama ön planda olduğunda ve kullanıcı uygulamayla aktif olarak etkileşimde bulunduğunda (ör. uygulama başlatma, giriş sonrası veya aktif kullanım sırasında) yayınlayın. Arka plan işlemlerinden yayınlama önerilmez.
Aşağıdaki etkinliklerde abonelik bilgilerini yayınlayın:
- Kullanıcı uygulamanıza giriş yapar.
- Kullanıcı, profiller arasında geçiş yapıyorsa (profiller destekleniyorsa).
- Kullanıcı yeni bir abonelik satın aldığında
- Kullanıcı, mevcut bir aboneliği yükseltir.
- Kullanıcı aboneliğinin süresi dolduğunda
Entegrasyon
Bu bölümde, çeşitli abonelik türlerini yönetmek için AccountProfile ve SubscriptionEntity'yi uygulamak üzere gerekli kod örnekleri ve talimatlar verilmiştir.
Kullanıcı hesabı ve profili
Google TV'de kişiselleştirilmiş özelliklere izin vermek için hesap bilgilerinizi girin. AccountProfile kullanarak şunları sağlayabilirsiniz:
- Hesap kimliği: Kullanıcının hesabını temsil eden benzersiz tanımlayıcı. Bu, gerçek hesap kimliği veya uygun şekilde karartılmış bir sürüm olabilir.
// Set the account ID to which the subscription applies.
// Don't set the profile ID because subscription applies to account level.
val accountProfile = AccountProfile.Builder()
.setAccountId("user_account_id")
.setProfileId("user_profile id")
.build();
Ortak katman aboneliği
Medya sağlayıcı hizmetlerine temel abonelikleri olan kullanıcılar için (ör. tüm ücretli içeriklere erişim sağlayan tek bir abonelik katmanı olan bir hizmet) şu temel bilgileri sağlayın:
Abonelik türü: Kullanıcının sahip olduğu abonelik planını net bir şekilde belirtin.
SUBSCRIPTION_TYPE_ACTIVE: Kullanıcının etkin bir ücretli aboneliği olmalıdır.SUBSCRIPTION_TYPE_ACTIVE_TRIAL: Kullanıcının deneme aboneliği vardır.SUBSCRIPTION_TYPE_INACTIVE: Kullanıcının hesabı var ancak etkin aboneliği veya deneme süresi yok.
Geçerlilik süresi: İsteğe bağlı süre (milisaniye cinsinden). Aboneliğin ne zaman sona ereceğini belirtin.
Sağlayıcı paket adı: Aboneliği işleyen uygulamanın paket adını belirtin.
Örnek: Örnek medya sağlayıcı feed'i için.
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Basic common name",
"commonTier": true
}
Aşağıdaki örnekte, bir kullanıcı için SubscriptionEntity oluşturuluyor:
val subscription = SubscriptionEntity
.Builder()
setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build();
Premium abonelik
Uygulama, ortak katmanın ötesinde genişletilmiş içerik veya özellikler içeren çok katmanlı premium abonelik paketleri sunuyorsa bunu, aboneliğe bir veya daha fazla hak ekleyerek gösterin.
Bu yararlanma hakkı aşağıdaki alanlara sahiptir:
- Tanımlayıcı: Bu hak için gerekli tanımlayıcı dizesi. Bu değer, Google TV'de yayınlanan medya sağlayıcının feed'inde sağlanan hak tanımlayıcılardan biriyle eşleşmelidir (Bunun kimlik alanı olmadığını unutmayın).
- Ad: Bu, yardımcı bir bilgidir ve hak eşleştirme için kullanılır. İsteğe bağlı olsa da kullanıcı tarafından okunabilir bir hak adı sağlamak, hem geliştiriciler hem de destek ekipleri için kullanıcı haklarının anlaşılmasını kolaylaştırır. Örneğin: Sling Orange.
- ExpirationTimeMillis: Abonelik sona erme süresinden farklıysa bu hak için isteğe bağlı olarak sona erme süresini milisaniye cinsinden belirtin. Varsayılan olarak, aboneliğin süresi dolduğunda hak da sona erer.
Aşağıdaki örnek medya sağlayıcı feed snippet'i için:
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Example entitlement name",
"commonTier": false,
// match this identifier in your API. This is the crucial
// entitlement identifier used for recommendation purpose.
"identifier": "example.com:entitlementString1"
}
Aşağıdaki örnekte, abone olan bir kullanıcı için SubscriptionEntity oluşturuluyor:
// Subscription with entitlements.
// The entitlement expires at the same time as its subscription.
val subscription = SubscriptionEntity
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
// matches with the identifier in media provider feed
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
.build()
)
.build();
// Subscription with entitlements
// The entitement has different expiration time from its subscription
val subscription = SubscriptionEntity
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
// You may set the expiration time for entitlement
// December 15, 2025 10:00:00 AM in milliseconds
.setExpirationTimeMillis(1765792800000)
.build())
.build();
Bağlı hizmet paketi aboneliği
Abonelikler genellikle aboneliğin başlatıldığı uygulamanın medya sağlayıcısına ait olsa da abonelikte bağlı hizmet paketi adı belirtilerek abonelik, bağlı bir hizmet paketine atanabilir.
Aşağıdaki kod örneğinde, kullanıcı aboneliğinin nasıl oluşturulacağı gösterilmektedir.
// Subscription for linked service package
val subscription = SubscriptionEntity
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build();
Ayrıca, kullanıcının bir bağlı kuruluş hizmetine başka bir aboneliği varsa başka bir abonelik ekleyin ve bağlı hizmet paket adını buna göre ayarlayın.
// Subscription for linked service package
val linkedSubscription = Subscription
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("linked service package name")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.addBundledSubscription(
BundledSubscription.Builder()
.setBundledSubscriptionProviderPackageName(
"bundled-subscription-package-name"
)
.setSubscriptionType(SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE)
.setExpirationTimeMillis(111)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setExpirationTimeMillis(111)
.setDisplayName("Silver subscription")
.setEntitlementId("subscription.tier.platinum")
.build()
)
.build()
)
.build();
Dilerseniz bağlı hizmet aboneliğine de haklar ekleyebilirsiniz.
Abonelik grubu sağlama
Uygulama ön plandayken içerik yayınlama işini çalıştırın.
publishSubscriptionCluster() sınıfındaki publishSubscriptionCluster() yöntemini kullanarak SubscriptionCluster nesnesi yayınlayın.AppEngagePublishClient
Hizmetin entegrasyona uygun olup olmadığını kontrol etmek için isServiceAvailable simgesini kullanın.
client.publishSubscription(
PublishSubscriptionRequest.Builder()
.setAccountProfile(accountProfile)
.setSubscription(subscription)
.build();
)
Kullanıcının hizmete yalnızca bir aboneliği olması gerektiğini doğrulamak için setSubscription() kullanın.
Kullanıcının sıfır veya daha fazla bağlı aboneliği olmasını sağlamak için bağlı aboneliklerin listesini kabul eden addLinkedSubscription() veya addLinkedSubscriptions() işlevini kullanın.
Hizmet isteği aldığında yeni bir giriş oluşturulur ve eski giriş 60 gün sonra otomatik olarak silinir. Sistem her zaman en son girişi kullanır. Hata durumunda isteğin tamamı reddedilir ve mevcut durum korunur.
Aboneliği güncel tutma
- Değişiklikler olduğunda anında güncelleme sağlamak için
publishSubscriptionCluster()yöntemini, kullanıcının abonelik durumu her değiştiğinde (etkinleştirme, devre dışı bırakma, yükseltme, düşürme gibi) çağırın. Sürekli doğruluk için düzenli doğrulama sağlamak üzere en az ayda bir kez
publishSubscriptionCluster()işlevini çağırın.Video keşfi verilerini silmek için standart 60 günlük saklama süresinden önce kullanıcının verilerini Google TV sunucusundan manuel olarak silmek üzere
client.deleteClusters()yöntemini kullanın. Bu işlem, hesap profili veya verilenDeleteReason'ye bağlı olarak hesabın tamamı için mevcut tüm video keşfi verilerini siler.Kullanıcı aboneliğini kaldırmak için kod snippet'i
// If the user logs out from your media app, you must make the following call // to remove subscription and other video discovery data from the current // google TV device. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile( AccountProfile .Builder() .setAccountId() .setProfileId() .build() ) .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT) .build() ) ``` Following code snippet demonstrates removal of user subscription when user revokes the consent. ```Kotlin // If the user revokes the consent to share across device, make the call // to remove subscription and other video discovery data from all google // TV devices. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile( AccountProfile .Builder() .setAccountId() .setProfileId() .build() ) .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT) .build() ) ``` Following code demonstrates how to remove subscription data on user profile deletion. ```Kotlin // If the user delete a specific profile, you must make the following call // to remove subscription data and other video discovery data. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile( AccountProfile .Builder() .setAccountId() .setProfileId() .build() ) .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION) .build() )
Test
Bu bölümde, abonelik uygulamasını test etme ile ilgili adım adım talimatlar verilmektedir. Kullanıma sunmadan önce verilerin doğruluğunu ve işlevlerin düzgün çalıştığını doğrulayın.
Entegrasyonu yayınlama denetim listesi
Yayınlama, uygulama ön planda olduğunda ve kullanıcı uygulamayla aktif olarak etkileşimde bulunduğunda gerçekleşmelidir.
Yayınlama zamanı:
- Kullanıcı ilk kez oturum açtığında
- Kullanıcı profili değiştirir (profiller destekleniyorsa).
- Kullanıcı yeni bir abonelik satın alır.
- Kullanıcı, aboneliğini yükseltir.
- Kullanıcı aboneliğinin süresi dolduğunda
Yayınlama etkinliklerinde, logcat'te uygulamanın
isServiceAvailable()vepublishClusters()API'lerini doğru şekilde çağırıp çağırmadığını kontrol edin.Verilerin doğrulama uygulamasında göründüğünü doğrulayın. Doğrulama uygulamasında abonelik ayrı bir satır olarak gösterilmelidir. Yayınlama API'si çağrıldığında veriler doğrulama uygulamasında gösterilmelidir.
- Uygulamanın Android Manifest dosyasında Engage Service Flag'in üretim için AYARLANMADIĞINI doğrulayın.
- Engage Verification uygulamasını yükleyip açın.
- Doğrulama uygulamasında
isServiceAvailabledeğerifalseise doğrulama uygulamasındakiToggledüğmesini tıklayarak değeritrueolarak ayarlayın. - Uygulamanın paket adını girin. Yayınlanan veriler otomatik olarak gösterilir.
Uygulamaya gidin ve aşağıdaki işlemlerin her birini gerçekleştirin:
- Oturum açın.
- profiller arasında geçiş yapma (destekleniyorsa)
- Yeni bir abonelik satın alma
- Mevcut bir aboneliği yükseltme
- Aboneliğin süresini sona erdirin.
Entegrasyonu doğrulama
Entegrasyonunuzu test etmek için 'nı kullanın.
Doğrulama uygulaması, geliştiricilerin entegrasyonun çalıştığını doğrulamak için kullanabileceği bir Android uygulamasıdır. Uygulama, geliştiricilerin verileri doğrulamasına ve yayın amaçlarını yayınlamasına yardımcı olacak özellikler içerir. Bu, lansman öncesinde verilerin doğruluğunu ve işlevselliğini doğrulamanıza yardımcı olur.
- Etkinliklerin her biri için uygulamanın
publishSubscriptionAPI'sini çağırıp çağırmadığını kontrol edin. Doğrulama uygulamasında yayınlanan verileri doğrulayın. Doğrulama uygulamasında her şeyin yeşil olduğunu doğrulayın Tüm varlık bilgilerinin doğru olması durumunda, tüm varlıklarda "Her Şey Yolunda" şeklinde yeşil bir onay işareti gösterilir.
1. şekil. Başarılı abonelik Sorunlar doğrulama uygulamasında da vurgulanır.
Şekil 2. Abonelik başarısız oldu Paketlenmiş abonelikteki sorunları görmek için TV kumandasını kullanarak söz konusu paketlenmiş aboneliğe odaklanın ve sorunları görmek için tıklayın. Önce satıra odaklanıp sağa doğru ilerleyerek Paket Abonelik kartını bulmanız gerekebilir. Sorunlar, Şekil 3'te gösterildiği gibi kırmızı renkle vurgulanır. Ayrıca, paketlenmiş abonelikteki haklarla ilgili sorunları görmek için uzaktan kumandayı kullanarak aşağı kaydırın.
Şekil 3. Abonelik Hataları Hakla ilgili sorunları görmek için TV kumandasını kullanarak söz konusu hakka odaklanın ve sorunları görmek için tıklayın. Sorunlar kırmızı renkle vurgulanır.
Şekil 4. Abonelik Hatası Ayrıntıları
İndir
İndirmeden önce aşağıdaki hüküm ve koşulları kabul etmeniz gerekir.