Bu sayfa, Cloud Translation API ile çevrilmiştir.

TV entegrasyonu kılavuzu için Engage SDK'sı
Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

İzlemeye Devam Et özelliği, devam kümesinden yararlanarak tek bir kullanıcı arayüzü gruplandırmasında birden fazla uygulamadan izlenmemiş videoları ve aynı TV sezonunun sonraki bölümlerini gösterir. Bu devam kümesinde öğelerini öne çıkarabilirsiniz. Engage SDK'sını kullanarak İzlemeye Devam deneyimiyle kullanıcı etkileşimini nasıl artıracağınızı öğrenmek için bu kılavuzu inceleyin.

1. adım: Ö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ğinden emin olun

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
```
  dependencies {
    implementation 'com.google.android.engage:engage-core:1.5.5
  }
```
TV
```
  dependencies {
    implementation 'com.google.android.engage:engage-tv:1.0.2
  }
```
AndroidManifest.xml dosyasında Engage hizmet ortamını üretim olarak ayarlayın.

Önemli: Bu işlem yalnızca bir sürüm derlemesi oluşturmadan önce yapılmalıdır. Doğrulama uygulamasıyla yerel testiniz için bunu kaldırın.
Mobil
```
<meta-data
      android:name="com.google.android.engage.service.ENV"
      android:value="PRODUCTION">
</meta-data>
```
TV
```
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION">
</meta-data>
```

TV apk için WRITE_EPG_DATA izni ekleme

  <uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

Planlama için androidx.work gibi bir arka plan hizmeti kullanarak güvenilir içerik yayınlama işlemini gerçekleştirin.
Sorunsuz bir izleme deneyimi sunmak için aşağıdaki etkinlikler gerçekleştiğinde izlemeye devam etme verilerini yayınlayın:
1. İlk Giriş: Kullanıcı ilk kez giriş yaptığında verilerinin yayınlanması, izleme geçmişinin hemen kullanılabilir olmasını sağlar.
2. Profil Oluşturma veya Geçiş Yapma (Çok Profilli Uygulamalar): Uygulamanız birden fazla profili destekliyorsa kullanıcı profil oluştururken veya profil değiştirirken verileri yayınlayın. Bu sayede her kullanıcı kişiselleştirilmiş bir deneyim yaşar.
3. Video Oynatma Kesintisi: Kullanıcıların kalkıştıkları yerden devam etmelerine yardımcı olmak için bir videoyu duraklattıklarında veya durdurduklarında ya da uygulama oynatma sırasında çıktığında verileri yayınlayın.
4. İzlemeye Devam Tepsisi Güncellemeleri (Destekleniyorsa): Kullanıcılar İzlemeye Devam tepsisindeki bir öğeyi kaldırdığında güncel verileri yayınlayarak bu değişikliği yansıtın. Bu sayede, tepsinin alakalı ve kişiselleştirilmiş kalması sağlanır.
5. Videoyu tamamlama:
  1. Filmler için, tamamlanan filmi İzlemeye Devam et tepsisinden kaldırın. Film bir serinin parçasıysa kullanıcının ilgisini canlı tutmak için bir sonraki filmi ekleyin.
  2. İzleyicilerin izlemeye devam etmesini sağlamak için tamamlanan bölümleri kaldırın ve varsa serinin sonraki bölümünü ekleyin.

Entegrasyon

AccountProfile

Google TV'de kişiselleştirilmiş bir "izlemeye devam et" deneyimi sunmak için hesap ve profil bilgilerini sağlayın. Aşağıdakileri sağlamak için AccountProfile'i 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ı (yine gerçek veya karartılmış) sağlayın.

// If your app only supports account
val accountProfile = AccountProfile.Builder()
      .setAccountId("your_users_account_id")
      .build()
// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
      .setAccountId("your_users_account_id")
      .setProfileId("your_users_profile_id")
.build()

Varlık oluşturma

SDK, her öğe türünü temsil etmek için farklı öğeler tanımlamıştır. Devam kümesi aşağıdaki varlıkları destekler:

Bu öğeler için platforma özel URI'leri ve poster resimlerini belirtin.

Ayrıca, henüz yapmadıysanız her platform için oynatma URI'leri (ör. Android TV, Android veya iOS) oluşturun. Bu nedenle, kullanıcı her platformda izlemeye devam ettiğinde uygulama, video içeriğini oynatmak için hedeflenen bir oynatma URI'si kullanır.

// Required. Set this when you want continue watching 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()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
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 continue watching 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)

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 "İzlemeye Devam Et" öğ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ğundan emin olun. 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)

MovieEntity

Bu örnekte, gerekli tüm alanlara sahip bir MovieEntity öğesinin nasıl oluşturulacağı gösterilmektedir:

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

Tür ve içerik derecelendirmeleri gibi ayrıntıları paylaşarak Google TV'nin içeriğinizi daha dinamik şekillerde göstermesini ve doğru izleyicilerle buluşmasını sağlayabilirsiniz.

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build();
val contentRatings = Arrays.asList(rating1);
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

Daha kısa bir süre sonu belirtmediğiniz sürece öğeler otomatik olarak 60 gün boyunca kullanılabilir durumda kalır. Özel bir geçerlilik bitiş tarihi yalnızca öğenin bu varsayılan dönemden önce kaldırılması gerekiyorsa ayarlanmalıdır.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = new DisplayTimeWindow.Builder()
             .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()

TvEpisodeEntity

Bu örnekte, gerekli tüm alanlara sahip bir TvEpisodeEntity öğesinin nasıl oluşturulacağı gösterilmektedir:

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build();

Bölüm numarası dizesi (ör. "2") ve sezon numarası dizesi (ör. "1"), izlemeye devam kartı üzerinde gösterilmeden önce uygun forma genişletilir. Bu değerlerin sayısal dize olması gerektiğini unutmayın. "e2", "bölüm 2", "s1" veya "sezon 1" gibi değerler girmeyin.

Belirli bir TV programının tek bir sezonu varsa sezon numarasını 1 olarak ayarlayın.

İzleyicilerin içeriğinizi Google TV'de bulma olasılığını en üst düzeye çıkarmak için türler, içerik derecelendirmeleri ve yayın zaman aralıkları gibi ek veriler sağlayabilirsiniz. Bu ayrıntılar, görüntüleme ve filtreleme seçeneklerini iyileştirebilir.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title)
    .build();

VideoClipEntity

Aşağıda, zorunlu alanların tümünü içeren bir VideoClipEntity oluşturmaya dair bir örnek verilmiştir.

VideoClipEntity, YouTube videosu gibi kullanıcı tarafından oluşturulan bir klibi temsil eder.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build();

İsteğe bağlı olarak içerik üreticiyi, içerik üretici resmini, oluşturulma zamanını milisaniye cinsinden veya kullanılabilirlik zaman aralığını ayarlayabilirsiniz .

LiveStreamingVideoEntity

Aşağıda, tüm zorunlu alanları içeren bir LiveStreamingVideoEntity oluşturmaya dair bir örnek verilmiştir.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build();

İsteğe bağlı olarak canlı yayın öğesinin başlangıç zamanını, yayıncısını, yayıncı simgesini veya yayın süresini ayarlayabilirsiniz.

Özellikler ve koşullar hakkında ayrıntılı bilgi için API referansı bölümüne bakın.

Devam kümesi verilerini sağlama

AppEngagePublishClient, Devam kümesini yayınlamaktan sorumludur. ContinuationCluster nesnesini yayınlamak için publishContinuationCluster() yöntemini kullanırsınız.

Öncelikle, hizmetin entegrasyon için kullanılabilir olup olmadığını kontrol etmek üzere isServiceAvailable() işlevini kullanmanız gerekir.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster
                .Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .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 ContinuationCluster verileri kaldırılır.
İstekten gelen veriler ayrıştırılır ve güncellenen ContinuationCluster öğesinde depolanır.

Hata durumunda, isteğin tamamı reddedilir ve mevcut durum korunur.

Yayınlama API'leri, mevcut içeriği değiştiren güncelleme API'leridir. ContinuationCluster'da belirli bir öğeyi güncellemeniz gerekiyorsa tüm öğeleri yeniden yayınlamanız gerekir.

ContinuationCluster verileri yalnızca yetişkin hesapları için sağlanmalıdır. Yalnızca AccountProfile bir yetişkine ait olduğunda yayınlanır.

Cihazlar arası senkronizasyon

SyncAcrossDevices İşareti

Bu işaret, kullanıcının ContinuationCluster verilerinin cihazları (TV, telefon, tablet vb.) arasında senkronize edilip edilmeyeceğini kontrol eder. Varsayılan olarak yanlış değerine ayarlanır. Bu, cihazlar arası senkronizasyonun varsayılan olarak devre dışı olduğu anlamına gelir.

Değerler:

true: Sorunsuz bir izleme deneyimi için ContinuationCluster verileri kullanıcının tüm cihazlarında paylaşılır. Cihazlar arası en iyi deneyim için bu seçeneği kullanmanızı önemle tavsiye ederiz.
false: ContinuationCluster verileri geçerli cihazla kısıtlanmıştır.

İzin alma:

Medya uygulaması, cihazlar arası senkronizasyonu etkinleştirmek/devre dışı bırakmak için net bir ayar sağlamalıdır. Kullanıcıya sunulan avantajları açıklayın ve kullanıcının tercihini bir kez saklayıp publishContinuationCluster'da uygun şekilde uygulayın.

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster
                .Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build();
        )
        .build();
)

Cihazlar arası özelliğimizden en iyi şekilde yararlanmak için uygulamanızın kullanıcı izni aldığından emin olun ve SyncAcrossDevices değerini true olarak ayarlayın. Bu sayede içerikler cihazlar arasında sorunsuz bir şekilde senkronize edilebilir. Bu da daha iyi bir kullanıcı deneyimi ve daha fazla etkileşim sağlar. Örneğin, bu özelliği uygulayan bir iş ortağı, içeriği birden fazla cihazda gösterildiği için "izlemeye devam et" tıklamalarında% 40 artış elde etti.

Video keşfi 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. 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ışta izlemeye devam etme verilerini kaldırır.


// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Test

Engage SDK entegrasyonunuzun düzgün çalıştığından emin olmak için doğrulama uygulamasını kullanın. Bu Android uygulaması, verilerinizi doğrulamanıza ve yayın intent'lerinin düzgün şekilde işlendiğini onaylamanıza yardımcı olacak araçlar sağlar.

publish API'yi çağırdıktan sonra doğrulama uygulamasını kontrol ederek verilerinizin doğru şekilde yayınlandığını onaylayın. Devam kümeniz, uygulamanın arayüzünde ayrı bir satır olarak gösterilir.

Engage Service Flag'in, uygulamanızın Android Manifest dosyasında üretim olarak AYARLANMADIĞINDAN emin olun.
Engage Verify uygulamasını yükleyip açma
isServiceAvailable false ise etkinleştirmek için "Aç/Kapat" düğmesini tıklayın.
Yayınlamaya başladıktan sonra yayınlanan verileri otomatik olarak görüntülemek için uygulamanızın paket adını girin.
Uygulamanızda aşağıdaki işlemleri test edin:
- Oturum açın.
- Profiller arasında geçiş yapın(varsa).
- Videoyu başlatıp duraklatın veya ana sayfaya dönün.
- Video oynatılırken uygulamayı kapatın.
- "İzlemeye Devam Et" satırından bir öğeyi kaldırın (destekleniyorsa).
Her işlemden sonra, uygulamanızın publishContinuationClusters API'yi çağırdığını ve verilerin doğrulama uygulamasında doğru şekilde gösterildiğini onaylayın.
Doğru şekilde uygulanan öğeler için doğrulama uygulamasında yeşil "Sorun yok" işareti gösterilir.

Şekil 1. Doğrulama Uygulama Başarısı
Doğrulama uygulaması, sorunlu varlıkları işaretler.

Şekil 2. Doğrulama Uygulaması Hatası
Hata içeren öğelerle ilgili sorunları gidermek için TV uzaktan kumandanızı kullanarak doğrulama uygulamasında öğeyi seçip tıklayın. Belirli sorunlar gösterilir ve incelemeniz için kırmızıyla vurgulanır (aşağıdaki örneğe bakın).

3.şekil Doğrulama Uygulaması Hata Ayrıntıları