REST API kullanarak "İzlemeye devam et" özelliğini entegre etme

Engage SDK, iOS ve Roku TV gibi Android platformu dışındaki platformlarda tutarlı bir izlemeye devam etme deneyimi sunmak için REST API sağlar. API, geliştiricilerin Android platformu dışındaki platformlardan kaydolan kullanıcılar için "İzlemeye Devam Et" durumunu güncellemesine olanak tanır.

Ön koşullar

  • Öncelikle cihaz üzerinde Engage SDK tabanlı entegrasyonu tamamlamanız gerekir. Bu önemli adım, Google'ın kullanıcı kimliği ile uygulamanızın AccountProfile arasında gerekli ilişkilendirmeyi oluşturur.
  • API Erişimi ve Kimlik Doğrulama: Google Cloud projenizde API'yi görüntülemek ve etkinleştirmek için izin verilenler listesi sürecinden geçmeniz gerekir. Tüm API istekleri için kimlik doğrulama gerekir.

Erişim kazanın

Google Cloud Console'da API'yi görüntüleme ve etkinleştirme erişimi elde etmek için hesabınızın kayıtlı olması gerekir.

  1. Google Workspace müşteri kimliği kullanılabilir olmalıdır. Kullanılamıyorsa bir Google Workspace hesabı ve API'yi çağırmak için kullanmak istediğiniz Google Hesaplarını oluşturmanız gerekebilir.
  2. Google Workspace ile ilişkili bir e-posta adresi kullanarak Google Cloud Console'da hesap oluşturun.
  3. Yeni proje oluşturun.
  4. API kimlik doğrulaması için bir hizmet hesabı oluşturun. Hizmet hesabını oluşturduktan sonra iki öğeniz olur:
    • Hizmet hesabı kimliği.
    • Hizmet hesabı anahtarınızı içeren bir JSON dosyası. Bu dosyayı güvende tutun. Bu anahtarı daha sonra istemcinizin API'de kimliğini doğrulamak için kullanacaksınız.
  5. Workspace ve ilişkili Google Hesapları artık REST API'leri kullanabilir. Değişiklik uygulandıktan sonra API'nin hizmet hesaplarınız tarafından çağrılmaya hazır olup olmadığı size bildirilir.
  6. Yetki verilmiş API çağrısı yapmaya hazırlanmak için bu adımları uygulayın.

Devam Kümesini Yayınlama

Engage verilerini yayınlamak için aşağıdaki söz dizimini kullanarak publishContinuationCluster API'sine bir POST isteği gönderin.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

Nerede:

  • package_name: Medya sağlayıcı paket adı
  • accountId: Kullanıcının sisteminizdeki hesabının benzersiz kimliği. Cihaz üzerindeki yolda kullanılan accountId ile eşleşmelidir.
  • profileId: Sisteminizdeki hesapta kullanıcının profili için benzersiz kimlik. Cihaz üzerindeki yolda kullanılan profileId ile eşleşmelidir.

Profilsiz hesabın URL'si:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

İsteğin yükü entities alanında gösterilir. entities, şu öğelerden bir veya daha fazlasından oluşabilen içerik varlıklarının listesini temsil eder: MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity veya VideoClipEntity. Bu alanının doldurulması zorunludur.

İstek içeriği

Field

Tür

Zorunlu

Açıklama

varlıklar

MediaEntity nesnelerinin listesi

Evet

En fazla 5 içerik öğesi içeren liste. Yalnızca ilk beş öğe korunur ve geri kalanı silinir. Kullanıcının tüm öğeleri izlemeyi bitirdiğini belirtmek için boş bir listeye izin verilir.

entities alanı, her bir movieEntity, tvEpisodeEntity, liveStreamingVideoEntity ve videoClipEntity değerini içerir.

Field

Tür

Açıklama

movieEntity

MovieEntity

ContinuationCluster içindeki bir filmi temsil eden nesne.

tvEpisodeEntity

TvEpisodeEntity

ContinuationCluster içinde bir TV bölümünü temsil eden nesne.

liveStreamingVideoEntity

LiveStreamingVideoEntity

ContinuationCluster içinde canlı video yayınını temsil eden bir nesne.

videoClipEntity

VideoClipEntity

ContinuationCluster içindeki bir video klibi temsil eden nesne.

Varlıklar dizisindeki her nesne, mevcut MediaEntity türlerinden biri (MovieEntity, TvEpisodeEntity, LiveStreamingVideoEntity veya VideoClipEntity) olmalı ve ortak ve türe özgü alanlar içermelidir.

Aşağıdaki kod snippet'inde, publishContinuationCluster API'nin istek gövdesi yükü gösterilmektedir.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/movie_entity_uri_for_android",
          "platforms": [
            "PLATFORM_ANDROID_TV",
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/movie_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/movie1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Movie 1 HD poster"
          },
          {
            "url": "http://www.example.com/movie1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Movie 1 SD poster"
          }
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_mobile",
          "platforms": [
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_tv",
          "platforms": [
            "PLATFORM_ANDROID_TV"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/episode1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Episode 1 HD poster"
          },
          {
            "url": "http://www.example.com/episode1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Episode 1 SD poster"
          }
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    },
    {
      "liveStreamingVideoEntity": {
        "name": "Live Sports Championship",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 1800000,
        "duration_millis": 7200000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/live_streaming_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/live_stream_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Live Sports Championship Cover Image"
          }
        ],
        "start_time_epoch_millis": 1780976484000,
        "broadcaster": "Global Sports Network",
        "broadcaster_icon": {
          "url": "https://www.example.com/gsports.jpg",
          "width": 512,
          "height": 512,
          "accessibility_text": "Global Sports Network Logo"
        }
      }
    },
    {
      "videoClipEntity": {
        "name": "How to Brew the Perfect Espresso",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 120000,
        "duration_millis": 600000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/video_clip_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/video_clip_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Espresso Tutorial Cover Image"
          }
        ],
        "created_time_epoch_millis": 1780900000000,
        "creator": "Coffee Enthusiast John",
        "creator_image": {
          "url": "https://www.example.com/image/thumb/creators/john_avatar.jpg",
          "width": 256,
          "height": 256,
          "accessibility_text": "John's Avatar"
        }
      }
    }
  ]
}

Etkileşim verilerini silme

Engage verilerini kaldırmak için clearCluster API'sini kullanın.

Devam kümesi verilerini silmek için aşağıdaki söz dizimini kullanarak clearCluster API'sine bir POST isteği gönderin.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearCluster

Nerede:

  • package_name: Medya sağlayıcı paket adı.
  • accountId: Kullanıcının sisteminizdeki hesabının benzersiz kimliği. Cihaz üzerindeki yolda kullanılan accountId ile eşleşmelidir.
  • profileId: Sisteminizdeki hesapta kullanıcının profili için benzersiz kimlik. Cihaz üzerindeki yolda kullanılan profileId ile eşleşmelidir.

Profilsiz hesabın URL'si:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/clearCluster

clearCluster API'sinin yükü, verilerin kaldırılma nedenini belirten bir DeleteReason içeren tek bir alan (reason) içerir.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Test

Verileri başarıyla yayınladıktan sonra, beklenen içeriğin Google TV ve Android ile iOS Google TV mobil uygulamaları gibi hedef Google platformlarındaki izlemeye devam et satırında göründüğünü doğrulamak için bir kullanıcı test hesabı kullanın.

Test sırasında, birkaç dakikalık makul bir yayılma gecikmesine izin verin ve izleme koşullarına (ör. bir filmin bir bölümünü izleme veya bir bölümü bitirme) uyun. Ayrıntılar için Uygulama geliştiriciler için Sıradaki Video yönergelerine bakın.