Engage SDK'sını Kullanarak Uygulama Hak Sahipliklerini Google TV ile Paylaşma

Bu kılavuzda, geliştiricilerin Engage SDK'sını kullanarak uygulama aboneliği ve uygunluk verilerini Google TV ile paylaşma talimatları yer almaktadır. Kullanıcılar, izleme haklarına sahip oldukları içerikleri bulabilir ve Google TV'nin doğrudan TV, mobil cihaz ve tabletlerdeki Google TV deneyimlerinde kullanıcılara son derece alakalı içerik önerileri sunmasını sağlayabilir.

Ön koşullar

Cihaz uygunluğu API'sini kullanabilmeniz için medya işlemleri feed'ini kullanmaya başlamanız gerekir. Henüz yapmadıysanız medya işlemleri feed'i ilk katılım 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 üstünü hedeflediğini doğrulayın

  1. 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
  }

  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>

    TV apk için

    
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION">
</meta-data>

  3. APK'yı Google'a göndermeden önce AndroidManifest.xml dosyanızda Engage hizmet ortamını üretim olarak ayarlayın. Optimum performans ve gelecekteki uyumluluk için verileri yalnızca uygulama ön plandayken ve kullanıcı uygulamayla etkin bir şekilde etkileşimdeyken (ör. uygulama başlatma, giriş sonrası veya etkin kullanım sırasında) yayınlayın. Arka plan işlemlerinden yayın yapılması önerilmez.

  4. Aşağıdaki etkinliklerle ilgili abonelik bilgilerini yayınlama:

    1. Kullanıcı uygulamanıza giriş yapar.
    2. Kullanıcı profiller arasında geçiş yapar (profiller destekliyorsa).
    3. Kullanıcı yeni bir abonelik satın alır.
    4. Kullanıcı mevcut aboneliğini yükseltir.
    5. Kullanıcı aboneliğinin süresi dolar.

Entegrasyon

Bu bölümde, çeşitli abonelik türlerini yönetmek için AccountProfile ve SubscriptionEntity'i uygulamayla ilgili gerekli kod örnekleri ve talimatlar verilmiştir.

Kullanıcı hesabı ve profili

Google TV'de kişiselleştirilmiş özelliklere izin vermek için hesap bilgilerini sağlayın. Aşağıdakileri sağlamak için AccountProfile simgesini kullanın:

  1. Hesap kimliği: Kullanıcının hesabını temsil eden benzersiz bir 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 (ör. ücretli tüm içeriklere erişim sağlayan tek bir abonelik katmanı olan bir hizmet) için aşağıdaki temel bilgileri sağlayın:

  1. Abonelik türü: Kullanıcının abonelik planını açıkça belirtin.

    1. SUBSCRIPTION_TYPE_ACTIVE: Kullanıcının etkin bir ücretli aboneliği var.
    2. SUBSCRIPTION_TYPE_ACTIVE_TRIAL: Kullanıcının deneme aboneliği var.
    3. SUBSCRIPTION_TYPE_INACTIVE: Kullanıcının hesabı var ancak etkin aboneliği veya deneme sürümü yok.

  2. Son kullanma zamanı: İsteğe bağlı olarak milisaniye cinsinden süre. Aboneliğin ne zaman sona ereceğini belirtin.

  3. Sağlayıcı paket adı: Aboneliği yöneten uygulamanın paket adını belirtin.

Örnek medya sağlayıcı feed'i örneği.

"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şturulmaktadır:

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 aboneliği

Uygulama, ortak katmanın ötesinde genişletilmiş içerik veya özellikler içeren çok katmanlı premium abonelik paketleri sunuyorsa Abonelik'e bir veya daha fazla ayrıcalık ekleyerek bunu gösterin.

Bu hak aşağıdaki alanlara sahiptir:

  1. Tanımlayıcı: Bu hak için gerekli tanımlayıcı dizesi. Bu, medya sağlayıcının Google TV'de yayınlanan feed'inde sağlanan hak kazanma tanımlayıcılarından biriyle eşleşmelidir (bu, kimlik alanı değildir).
  2. Ad: Yardımcı bilgidir ve uygunluk eşleştirme için kullanılır. İsteğe bağlı olsa da kullanıcılar tarafından okunabilen bir ayrıcalık adı sağlamak hem geliştiriciler hem de destek ekipleri için kullanıcı ayrıcalıklarının anlaşılmasını kolaylaştırır. Örneğin: Sling Orange.
  3. Expiration TimeMillis: İsteğe bağlı olarak, abonelik süresinin sona erme tarihinden farklıysa bu hak için süre sonunu milisaniye cinsinden belirtin. Varsayılan olarak, aboneliğin süresi dolduktan sonra 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şturulmaktadır:

// 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 için abonelik

Abonelikler genellikle kaynak uygulamanın medya sağlayıcısına ait olsa da abonelik içinde bağlı hizmet paketi adı belirtilerek abonelik bağlı bir hizmet paketiyle ilişkilendirilebilir.

Aşağıdaki kod örneği, kullanıcı aboneliğinin nasıl oluşturulacağını gösterir.

// 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 yan hizmete ait başka bir aboneliği varsa başka bir abonelik ekleyin ve bağlı hizmet paketi 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();

İsteğe bağlı olarak, bağlı bir hizmet aboneliğine de ayrıcalık ekleyebilirsiniz.

Abonelik grubu sağlama

Uygulama ön plandayken içerik yayınlama işini çalıştırın.

SubscriptionCluster nesnesi yayınlamak için AppEngagePublishClient sınıfındaki publishSubscriptionCluster() yöntemini kullanın.

Hizmetin entegrasyon için uygun olup olmadığını kontrol etmek üzere 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() değerini kullanın.

Kullanıcının sıfır veya daha fazla bağlı aboneliği olmasını sağlamak için addLinkedSubscription()'ü ya da bağlı abonelik listesini kabul eden addLinkedSubscriptions()'ü 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 olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

Aboneliği güncel tutun

  1. Değişikliklerden sonra anında güncelleme sağlamak için kullanıcının abonelik durumu değiştiğinde (ör. etkinleştirme, devre dışı bırakma, yükseltme, düşürme) publishSubscriptionCluster() işlevini çağırın.

  2. Doğruluğu sürekli olarak doğrulamak için publishSubscriptionCluster()'yi en az ayda bir kez çağırın.

  3. 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 silin. client.deleteClusters() yöntemini kullanın. Bu işlem, belirtilen DeleteReason değerine bağlı olarak hesap profili veya 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 etmeyle ilgili adım adım bir kılavuz sağlanmaktadır. Lansmandan önce verilerin doğruluğunu ve düzgün işlevini doğrulayın.

Entegrasyonu yayınlama yapılacaklar listesi

  1. Yayınlama işlemi, uygulama ön plandayken ve kullanıcı uygulamayla etkin bir şekilde etkileşimde bulunurken gerçekleşmelidir.

  2. Şu durumlarda yayınla:

    • Kullanıcı ilk kez giriş yapar.
    • Kullanıcı profilini değiştirir (profiller destekliyorsa).
    • Kullanıcı yeni abonelik satın alır.
    • Kullanıcı aboneliğini yükseltir.
    • Kullanıcı aboneliğinin süresi dolar.

  3. Uygulamanın, yayınlama etkinliklerinde logcat'te isServiceAvailable() ve publishClusters() API'lerini doğru şekilde çağırıp çağırmadığını kontrol edin.

  4. Verilerin doğrulama uygulamasında görünür olduğunu doğrulayın. Doğrulama uygulaması, aboneliği ayrı bir satırda göstermelidir. Yayınlama API'si çağrıldığında veriler doğrulama uygulamasında gösterilir.

    • Engage Hizmet İşareti'nin, uygulamanın Android manifest dosyasında üretim olarak AYARLADIĞINI doğrulayın.
    • Engage Verification uygulamasını yükleyip açın.
    • Doğrulama uygulamasında isServiceAvailable değeri false ise true olarak ayarlamak için doğrulama uygulamasındaki Toggle düğmesini tıklayın.
    • Uygulamanın paket adını girin. Yayınlanan veriler otomatik olarak gösterilir.

  5. Uygulamaya gidin ve aşağıdaki işlemlerin her birini gerçekleştirin:

    • Oturum açın.
    • Profiller arasında geçiş yapabilirsiniz (destekleniyorsa).
    • Yeni bir abonelik satın alın.
    • Mevcut bir aboneliği yükseltebilirsiniz.
    • Aboneliğin süresinin dolması.

Entegrasyonu doğrulama

Entegrasyonunuzu test etmek için doğrulama uygulaması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 intent'leri yayınlamasına yardımcı olacak özellikler içerir. Lansmandan önce verilerin doğruluğunu ve işlevselliğin düzgün olduğunu doğrulamaya yardımcı olur.

  1. Etkinliklerin her biri için uygulamanın publishSubscription API'yi ç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

  2. Varlığın tüm bilgileri doğruysa tüm varlıklarda "Her şey yolunda" yeşil onay işareti gösterilir.

    Doğrulama Uygulaması Başarı Ekran Görüntüsü
    Şekil 1. Abonelik başarıyla yapıldı

  3. Sorunlar doğrulama uygulamasında da vurgulanır.

    Doğrulama Uygulaması Hatası Ekran Görüntüsü
    Şekil 2. Abonelik başarısız oldu

  4. Paket abonelikteki sorunları görmek için TV kumandasını kullanarak ilgili paket aboneliğe odaklanın ve sorunları görmek için tıklayın. Paket Aboneliği kartını bulmak için önce satıra odaklanıp sağa gitmeniz gerekebilir. Sorunlar, Şekil 3'te gösterildiği gibi kırmızı renkle vurgulanır. Ayrıca, uzaktan kumandayı kullanarak aşağı kaydırıp paket abonelikteki ayrıcalıklardaki sorunları görebilirsiniz.

    Doğrulama Uygulaması Hata Ayrıntıları Ekran Görüntüsü
    Şekil 3. Abonelik Hataları

  5. Kullanım hakkıyla ilgili sorunları görmek için TV kumandasını kullanarak ilgili kullanım hakkına odaklanın ve sorunları görmek için tıklayın. Sorunlar kırmızı renkle vurgulanır.

    Doğrulama Uygulaması Hatası Ekran Görüntüsü
    Şekil 4.Abonelik Hatası Ayrıntıları