Как интегрировать функцию "Продолжить просмотр" с помощью REST API

Engage SDK предлагает REST API, который позволяет обеспечить единообразный интерфейс продолжения просмотра на платформах, отличных от Android, например iOS и Roku TV. API позволяет разработчикам обновлять статус "Продолжить просмотр" для пользователей, которые дали согласие на это на платформах, отличных от платформы Android.

Требования

  • Сначала необходимо завершить интеграцию Engage SDK на устройстве. Это важный шаг, который позволяет установить связь между идентификатором пользователя Google и AccountProfile вашего приложения.
  • Доступ к API и аутентификация. Чтобы посмотреть и включить API в облачном проекте Google Cloud, необходимо пройти процедуру добавления в белый список. Все запросы к API требуют аутентификации.

Получить доступ

Чтобы получить доступ к API и включить его в консоли Google Cloud, необходимо зарегистрировать аккаунт.

  1. Идентификатор клиента Google Workspace должен быть доступен. Если у вас нет такого аккаунта, вам может потребоваться настроить Google Workspace, а также аккаунты Google, которые вы хотите использовать для вызова API.
  2. Настройте аккаунт в консоли Google Cloud, используя адрес электронной почты, связанный с Google Workspace.
  3. Создайте проект.
  4. Создайте сервисный аккаунт для аутентификации API. После создания сервисного аккаунта у вас будет два объекта:
    • идентификатор сервисного аккаунта;
    • JSON-файл с ключом сервисного аккаунта. Храните этот файл в безопасном месте. Он понадобится вам позже для аутентификации клиента в API.
  5. Теперь REST API можно использовать в Workspace и связанных аккаунтах Google. Когда изменения вступят в силу, вы получите уведомление о том, что API готов к вызовам из сервисных аккаунтов.
  6. Чтобы подготовиться к делегированному вызову API, выполните эти действия.

Как опубликовать кластер продолжения действий

Чтобы опубликовать данные Engage, выполните запрос POST к API publishContinuationCluster, используя следующий синтаксис:

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

Место:

  • package_name – название пакета поставщика медиаконтента.
  • accountId – уникальный идентификатор аккаунта пользователя в вашей системе. Оно должно совпадать со значением accountId, которое используется в пути на устройстве.
  • profileId – уникальный идентификатор профиля пользователя в аккаунте в вашей системе. Должен совпадать с profileId, используемым в пути на устройстве.

URL аккаунта без профиля:

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

Полезная нагрузка запроса представлена в поле entities. entities – список объектов контента, который может состоять из одного или нескольких следующих элементов: MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity или VideoClipEntity. Это обязательное поле.

Тело запроса

Поле

Категория

Обязательно

Описание

объекты

Список объектов MediaEntity

Да

Список объектов контента (не более пяти). Остальные будут удалены. Пустой список означает, что пользователь посмотрел все объекты.

Поле entities содержит отдельные поля movieEntity, tvEpisodeEntity, liveStreamingVideoEntity и videoClipEntity.

Поле

Категория

Описание

movieEntity

MovieEntity

Объект, представляющий фильм в ContinuationCluster.

tvEpisodeEntity

TvEpisodeEntity

Объект, представляющий серию телесериала в ContinuationCluster.

liveStreamingVideoEntity

LiveStreamingVideoEntity

Объект, представляющий видео со стримов в ContinuationCluster.

videoClipEntity

VideoClipEntity

Объект, представляющий видеоклип в ContinuationCluster.

Каждый объект в массиве entities должен относиться к одному из доступных типов MediaEntity, а именно MovieEntity, TvEpisodeEntity, LiveStreamingVideoEntity или VideoClipEntity, и содержать общие и относящиеся к типу поля.

В приведенном ниже фрагменте кода показана полезная нагрузка тела запроса для publishContinuationCluster API.

{
  "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"
        }
      }
    }
  ]
}

Удалить данные Engage

Удалите данные Engage с помощью clearCluster API.

Чтобы удалить данные кластера продолжения, выполните запрос POST к API clearCluster, используя следующий синтаксис.

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

Место:

  • package_name – название пакета поставщика медиаконтента.
  • accountId – уникальный идентификатор аккаунта пользователя в вашей системе. Оно должно совпадать со значением accountId, которое используется в пути на устройстве.
  • profileId – уникальный идентификатор профиля пользователя в аккаунте в вашей системе. Должен совпадать с profileId, используемым в пути на устройстве.

URL аккаунта без профиля:

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

Полезная нагрузка для API clearCluster содержит только одно поле – reason, в котором содержится DeleteReason, указывающий причину удаления данных.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Тестирование

После успешной публикации данных используйте тестовый аккаунт пользователя, чтобы убедиться, что ожидаемый контент появляется в строке "Продолжить просмотр" на целевых платформах Google, таких как Google TV и мобильные приложения Google TV для Android и iOS.

При тестировании учитывайте задержку в несколько минут и соблюдайте требования к просмотру, например посмотрите часть фильма или серию до конца. Подробную информацию можно найти в рекомендациях для разработчиков приложений.