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

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

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şlangıç kılavuzundaki Ön hazırlık talimatlarını tamamlayın.

  1. Abonelik bilgilerini aşağıdaki etkinliklerde yayınlayın:
    1. Kullanıcı, uygulamanıza giriş yapar.
    2. Kullanıcı, profiller arasında geçiş yapıyorsa (profiller destekleniyorsa).
    3. Kullanıcı yeni bir abonelik satın aldığında
    4. Kullanıcı, mevcut bir aboneliği yükseltir.
    5. Kullanıcı aboneliğinin süresi dolar.

Entegrasyon

Bu bölümde, çeşitli abonelik türlerini yönetmek için SubscriptionEntity'yı uygulamak üzere gerekli kod örnekleri ve talimatlar verilmektedir.

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:

  1. SubscriptionType: 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 var.
    • SUBSCRIPTION_TYPE_INACTIVE: Kullanıcının hesabı var ancak etkin aboneliği veya deneme süresi yok.

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

  3. ProviderPackageName: Aboneliği işleyen 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ş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 hak aşağıdaki alanlara sahiptir:

  1. Identifier: Bu hak için zorunlu tanımlayıcı dize. Bu, Google TV'de yayınlanan medya sağlayıcının feed'inde sağlanan yetki tanımlayıcılarından biriyle eşleşmelidir (Bunun kimlik alanı olmadığını unutmayın).
  2. Name: Bu, ek 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.
  3. ExpirationTimeMillis: Abonelik son kullanma tarihinden farklıysa bu hak için isteğe bağlı olarak son kullanma zamanını milisaniye cinsinden belirtin. Varsayılan olarak, hak aboneliğin süresi dolduğunda 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 alındığı 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 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 bir SubscriptionCluster nesnesi yayınlayın.AppEngagePublishClient

İstemciyi başlattığınızdan ve hizmetin kullanılabilirliğini Başlangıç Kılavuzu'nda açıklandığı şekilde kontrol ettiğinizden emin olun.

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

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

  2. Sürekli doğruluk için düzenli doğrulama sağlamak üzere en az ayda bir kez publishSubscriptionCluster işlevini çağırın.

  3. Video keşfi verilerini silmek için standart 60 günlük saklama süresi dolmadan önce kullanıcının verilerini Google TV sunucusundan manuel olarak silmek üzere client.deleteClusters yöntemini kullanın. Bu işlem, hesaba verilen DeleteReason'a bağlı olarak hesap profili veya hesabın tamamı için mevcut tüm video keşfi verilerini siler.

    Aşağıdaki kod snippet'inde, kullanıcı aboneliğinin nasıl kaldırılacağı gösterilmektedir:

    // 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)
  .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
  .build()
  )

    Aşağıdaki kod snippet'inde, kullanıcı izni iptal ettiğinde kullanıcı aboneliğinin nasıl kaldırılacağı gösterilmektedir:

    // 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)
    .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

    Aşağıdaki kod, kullanıcı profili silindiğinde abonelik verilerinin nasıl kaldırılacağını gösterir.

    // 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)
  .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 düzgün işlevselliğini doğrulayın.

Entegrasyonu yayınlama kontrol listesi

  1. Yayınlama, uygulama ön planda olduğunda ve kullanıcı uygulamayla etkin olarak etkileşimde bulunduğunda gerçekleşmelidir.

  2. 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 dolar.

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

  4. 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.

  5. 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 doğrulama uygulamasını kullanın.

  1. Etkinliklerin her biri için uygulamanın publishSubscription API'sini çağırıp çağırmadığını kontrol edin. Yayınlanan verileri doğrulama uygulamasında doğrulayın. Doğrulama uygulamasında her şeyin yeşil olduğunu doğrulayın

  2. Tüm varlık bilgilerinin doğru olması durumunda, tüm varlıklarda "Her Şey Yolunda" anlamına gelen yeşil bir onay işareti gösterilir.

    Doğrulama Uygulaması Başarı Ekran Görüntüsü
    Şekil 1. Başarılı abonelik

  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. 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. Şekil 3'te gösterildiği gibi sorunlar 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.

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

  5. 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.

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