REST API를 사용하여 이어보기 통합

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

Engage SDK는 iOS, Roku TV와 같은 Android가 아닌 플랫폼에서 일관된 이어서 시청하기 환경을 제공하는 REST API를 제공합니다. 이 API를 사용하면 개발자가 Android 이외의 플랫폼에서 선택한 사용자의 '이어서 시청하기' 상태를 업데이트할 수 있습니다.

기본 요건

먼저 온디바이스 Engage SDK 기반 통합을 완료해야 합니다. 이 중요한 단계를 통해 Google의 사용자 ID와 앱의 AccountProfile 간에 필요한 연결이 설정됩니다.
API 액세스 및 인증: Google Cloud 프로젝트에서 API를 보고 사용 설정하려면 허용 목록 프로세스를 거쳐야 합니다. 모든 API 요청에는 인증이 필요합니다.

액세스 권한 얻기

Google Cloud 콘솔에서 API를 보고 사용 설정하려면 계정이 등록되어 있어야 합니다.

Google Workspace 고객 ID를 사용할 수 있어야 합니다. 사용할 수 없는 경우 API를 호출하는 데 사용할 Google 계정뿐만 아니라 Google Workspace도 설정해야 할 수 있습니다.
Google Workspace와 연결된 이메일을 사용하여 Google Cloud 콘솔로 계정을 설정합니다.
새 프로젝트 만들기
API 인증을 위한 서비스 계정을 만듭니다. 서비스 계정을 만들면 다음 두 항목이 표시됩니다.
- 서비스 계정 ID
- 서비스 계정 키가 포함된 JSON 파일. 이 파일을 안전하게 보관하세요. 나중에 클라이언트를 API에 인증하는 데 필요합니다.
이제 Workspace 및 연결된 Google 계정에서 REST API를 사용할 수 있습니다. 변경사항이 전파되면 서비스 계정에서 API를 호출할 준비가 되었는지 알림이 전송됩니다.
위임된 API 호출을 준비하려면 다음 단계를 따르세요.

연속 클러스터 게시

동영상 디스커버리 데이터를 게시하려면 다음 구문을 사용하여 publishContinuationCluster API에 POST 요청을 실행합니다.

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

각각의 의미는 다음과 같습니다.

package_name: 미디어 제공업체 패키지 이름
accountId: 시스템에 있는 사용자 계정의 고유 ID입니다. 온디바이스 경로에 사용된 accountId와 일치해야 합니다.
profileId: 시스템에 있는 계정의 사용자 프로필에 대한 고유 ID입니다. 온디바이스 경로에 사용된 profileId와 일치해야 합니다.

프로필이 없는 계정의 URL은 다음과 같습니다.

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

요청 페이로드는 entities 필드에 표시됩니다. entities는 MovieEntity 또는 TVEpisodeEntity일 수 있는 콘텐츠 항목 목록을 나타냅니다. 필수 입력란입니다.

요청 본문

필드	유형	필수 항목	설명
entities	MediaEntity 객체 목록	예	콘텐츠 항목 목록(최대 5개) 상위 5개만 유지되고 나머지는 삭제됩니다. 사용자가 모든 항목을 시청했음을 나타내기 위해 빈 목록이 허용됩니다.

entities 필드에는 개별 movieEntity 및 tvEpisodeEntity가 포함됩니다.

필드	유형	필수 항목	설명
movieEntity	MovieEntity	예	ContinuationCluster 내의 영화를 나타내는 객체입니다.
tvEpisodeEntity	TvEpisodeEntity	예	ContinuationCluster 내의 TV 에피소드를 나타내는 객체입니다.

entities 배열의 각 객체는 공통 필드 및 유형별 필드와 함께 사용 가능한 MediaEntity 유형(MovieEntity 및 TvEpisodeEntity) 중 하나여야 합니다.

다음 코드 스니펫은 publishContinuationCluster API의 요청 본문 페이로드를 보여줍니다.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "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": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "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"
      }
    }
  ]
}

동영상 디스커버리 데이터 삭제

clearClusters API를 사용하여 동영상 디스커버리 데이터를 삭제합니다.

연속 클러스터 데이터를 삭제하려면 다음 구문을 사용하여 clearClusters API에 POST 요청을 실행합니다.

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

각각의 의미는 다음과 같습니다.

package_name: 미디어 제공업체 패키지 이름입니다.
accountId: 시스템에 있는 사용자 계정의 고유 ID입니다. 온디바이스 경로에 사용된 accountId와 일치해야 합니다.
profileId: 시스템에 있는 계정의 사용자 프로필에 대한 고유 ID입니다. 온디바이스 경로에 사용된 profileId와 일치해야 합니다.

clearClusters API의 페이로드에는 데이터 삭제 이유를 지정하는 DeleteReason가 포함된 reason 필드 하나만 포함됩니다.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

테스트

데이터를 성공적으로 게시한 후 사용자 테스트 계정을 사용하여 Google TV, Android 및 iOS Google TV 모바일 앱과 같은 타겟 Google 표시 경로의 '이어서 시청하기' 행에 예상 콘텐츠가 표시되는지 확인합니다.

테스트에서는 몇 분 정도의 적절한 전파 지연을 허용하고, 영화의 일부를 시청하거나 에피소드를 완료하는 등 시청 요구사항을 준수하세요. 자세한 내용은 앱 개발자를 위한 다음 볼만한 동영상 가이드라인을 참고하세요.