프로젝트에서 Video Stitcher API를 사용 설정하려면 계정 담당자 또는 영업팀에 문의하여 자세히 알아보세요.

커스텀 통합 사용

시작하기 전에

이 문서에서는 IMA DAI SDK가 없는 경우의 재생 안내만 다룹니다.

Google Ad Manager(GAM)와 VOD 애셋 통합 단계를 완료했는지 미리 확인하세요.

원하는 플랫폼에서 IMA SDK를 사용할 수 없으면 애플리케이션에서 필요한 API를 호출하고 광고 미디어 인증을 트리거하도록 해야 합니다.

이렇게 하려면 다음 정보가 필요합니다.

위치	The 라이브 구성이 생성된 Google Cloud 리전: `LOCATION`
프로젝트 번호	Video Stitcher API를 사용하는 Google Cloud 프로젝트의 프로젝트 번호: `PROJECT_NUMBER`
OAuth 토큰	Video Stitcher 사용자 역할이 포함된 서비스 계정의 단기 OAuth 토큰: `OAUTH_TOKEN` 단기 OAuth 토큰 만들기에 대해 자세히 알아보세요. 요점: OAuth 토큰은 만료되지 않은 한 여러 요청에서 재사용될 수 있습니다.
네트워크 코드	광고 요청에 사용되는 Ad Manager 네트워크 코드: `NETWORK_CODE`
VOD 구성 ID	VOD 스트림 이벤트를 만들 때 지정한 VOD 구성 ID입니다. `VOD_CONFIG_ID`

Ad Manager에 스트림 등록 요청 보내기

스트림 등록 엔드포인트에 POST 요청을 보냅니다. 그러면 매니페스트 조작 서버 및 연결된 Pod Serving API 엔드포인트로 전송할 스트림 ID가 포함된 JSON 응답이 수신됩니다.

API 엔드포인트

POST: /ondemand/pods/api/v1/network/NETWORK_CODE/stream_registration
Host: dai.google.com
Content-Type: application/json

경로 매개변수

NETWORK_CODE Google Ad Manager 360 네트워크 코드

JSON으로 인코딩된 본문 매개변수

targeting_parameters: 선택적 JSON으로 인코딩된 타겟팅 매개변수의 집합입니다.

응답 JSON

`media_verification_url`	재생 추적 이벤트를 핑하는 기준 URL입니다. 이 기준 URL에 광고 이벤트 ID를 추가하면 완전한 미디어 인증 URL이 구성됩니다. `MEDIA_VERIFICATION_URL`
`metadata_url`	광고 모음 메타데이터를 요청하는 URL입니다. `METADATA_URL`
`stream_id`	현재 스트림 세션을 식별하는 데 사용되는 문자열입니다. `STREAM_ID`
`valid_for`	현재 스트림 세션이 만료될 때까지 남은 시간입니다(`dhms`(일, 시간, 분, 초) 형식). 예를 들어 `2h0m0.000s`는 2시간 기간을 나타냅니다.
`valid_until`	현재 스트림 세션이 만료되는 시간으로, `yyyy-MM-dd'T'hh:mm:ss.sssssssss[+\|-]hh:mm` 형식의 ISO 8601 날짜/시간 문자열입니다.

요청 예시(cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

응답 예시

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

오류가 발생하면 JSON 응답 본문 없이 표준 HTTP 오류 코드가 반환됩니다.

JSON 응답을 파싱하고 관련 값을 저장합니다.

Cloud Video Stitcher VOD 세션 생성

VOD 세션 등록 엔드포인트에 POST 요청을 수행합니다. 그 대신 스트림 매니페스트 URI와 광고 시점, 광고, 광고 이벤트와 관련된 메타데이터가 포함된 JSON 응답이 수신됩니다.

API 엔드포인트

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

경로 매개변수

`PROJECT_NUMBER`	Google Cloud 프로젝트 번호입니다.
`LOCATION`	Google Cloud 리전입니다.
`NETWORK CODE`	Google Ad Manager 360 네트워크 코드입니다.

JSON으로 인코딩된 본문 매개변수

`vodConfig`	프로젝트 번호, 위치, VOD 구성 ID가 포함된 다음 형식의 문자열: `projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID`
`adTracking`	클라이언트 측 추적을 사용 설정하려면 `"CLIENT"`로 설정합니다.
`gamSettings`	네트워크 코드와 스트림 ID가 포함된 다음 형식의 객체: { "networkCode":"`NETWORK_CODE`", "streamId":"`STREAM_ID`" }

응답 JSON

`name`	세션 ID가 포함된 VOD 세션의 이름입니다.
`playUri`	재생할 동영상 플레이어에 로드할 병합된 스트림 매니페스트 URI입니다. `SESSION_PLAYBACK_URI`
`adTracking`	요청 본문에서 API에 전송된 객체와 동일한 `adTracking` 값입니다.
`vodConfig`	요청 본문에서 API에 전송된 문자열과 동일한 `vodConfig` 문자열입니다.
`gamSettings`	요청 본문에서 API에 전송된 객체와 동일한 `gamSettings` 객체입니다.

요청 예시(cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

응답 예시

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

응답이 수신된 후 응답 객체의 playUri 필드에서 URI를 참조하여 광고 병합 실시간 스트림을 재생할 수 있습니다.

Ad Manager에서 광고 모음 메타데이터 요청

Ad Manager에 스트림을 등록할 때 받은 metadata_url에 GET 요청을 수행합니다. 이 단계는 재생 URI에서 병합된 매니페스트를 수신한 후에 발생해야 합니다.

그러면 스트림의 광고 시점, 광고, 광고 이벤트를 설명하는 JSON 객체가 수신됩니다.

API 엔드포인트

GET: METADATA_URL
Host: dai.google.com

응답 JSON

`tags`	스트림 내에서 발생할 광고 미디어 이벤트를 설명하는 키-값 쌍 세트입니다. 각 키는 스트림의 ID3 메타데이터에 표시되는 광고 미디어 ID의 첫 17자나 `progress` 이벤트의 경우 전체 광고 미디어 ID로 구성됩니다. 각 값은 다음 속성을 가진 객체입니다. `ad`: 광고 미디어 이벤트가 포함된 광고의 ID입니다. `ad_break_id`: 광고 미디어 이벤트가 포함된 광고 시점의 ID입니다. `type`: 광고 미디어 이벤트 유형입니다. 값은 다음 중 하나입니다. `start` - 광고가 시작되었습니다. `firstquartile` - 광고가 25% 완료되었습니다. `midpoint` - 광고가 50% 완료되었습니다. `thirdquartile` - 광고가 75% 완료되었습니다. `complete` - 광고가 종료되었습니다. `progress` - 광고가 재생되는 동안 1초마다 실행됩니다.
`ads`	스트림 내에 표시될 광고를 설명하는 키-값 쌍 세트입니다. 각 키는 광고 ID입니다. 각 값은 다음 속성을 가진 객체입니다. `ad_break_id`: 광고 미디어 이벤트가 포함된 광고 시점의 ID입니다. `position`: 광고 시점 내 광고의 위치입니다. 광고 시점의 첫 번째 광고는 `1` 위치입니다. `duration`: 광고 길이(부동 소수점 초)입니다. `title`: VAST에 정의된 광고의 제목입니다. `description`: VAST에 정의된 광고의 설명입니다. `ad_system`: VAST에 정의된 광고 시스템입니다. `ad_system`: VAST에 정의된 광고 ID입니다. `ad_system`: VAST에 정의된 광고 소재 ID입니다. `clickthrough_url`: 사용자가 광고와 상호작용할 때 열리는 URL입니다. `universal_ad_id`: VAST에 정의된 범용 광고 ID를 나타내는 객체입니다.
`ad_breaks`	스트림 내에서 발생할 광고 시점을 설명하는 키-값 쌍 세트입니다. 각 키는 광고 시점 ID입니다. 각 값은 다음 속성을 가진 객체입니다. `type`: 광고 시점 유형입니다. 값은 다음 중 하나입니다. `pre`: 프리롤 광고를 나타냅니다. `mid`: 미드롤 광고를 나타냅니다. `post`: 포스트롤 광고를 나타냅니다. `duration`: 광고 시점 길이(부동 소수점 초)입니다. `expected_duration`: 광고 시점의 예상 기간(부동 소수점 초)입니다. `ads`: 광고 시점에 포함된 광고 수입니다.

요청 예시(cURL)

curl METADATA_URL

JSON 응답 예시

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

동영상 스트림 내에서 시간이 지정된 메타데이터 이벤트와 연결하려면 이 값을 저장하세요.

ID3 이벤트 리슨 및 재생 이벤트 추적

동영상 스트림에서 특정 이벤트가 발생했는지 확인하려면 다음 단계를 수행하여 ID3 이벤트를 처리합니다.

미디어 이벤트를 큐에 저장하고 플레이어에 표시되는 경우 각 미디어 ID를 타임스탬프와 함께 저장합니다.
플레이어의 업데이트마다 또는 설정된 빈도(500ms 권장)로 이벤트 타임스탬프를 플레이헤드와 비교하여 미디어 이벤트 큐에서 최근 재생된 이벤트를 확인합니다.
재생된 것으로 확인된 미디어 이벤트의 경우 저장된 광고 시점 태그에서 미디어 ID를 조회하여 유형을 확인합니다. 광고 시점 태그 객체에는 google_ 프리픽스 뒤의 첫 10자리로 제한된 미디어 ID의 잘린 버전만 포함되므로 ID3 미디어 확인 ID와 태그 객체의 키가 직접 일치하지 않습니다. 이는 ID3 이벤트가 도착하기 전에 이벤트 확인 핑이 전송되는 것을 방지하기 위함입니다. 광고 이벤트의 전체 미디어 인증 URL을 생성하려면 전체 광고 이벤트 ID를 스트림 생성 응답의 media_verification_url 값에 추가합니다.
'progress' 이벤트를 사용하여 사용자가 광고 시점 내에 있는지 추적합니다. HTTP 오류 코드를 방지하려면 이러한 이벤트를 미디어 인증 엔드포인트로 전송하지 마세요. 다른 이벤트 유형의 경우 미디어 ID를 미디어 인증 URL에 추가하고 GET 요청을 보내 재생을 추적합니다.
큐에서 미디어 이벤트를 삭제합니다.

API 엔드포인트

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

경로 매개변수

`MEDIA_VERIFICATION_URL`	스트림 등록 엔드포인트에서 반환한 `media_verification_url` 필드 값: `MEDIA_VERIFICATION_URL`
`AD_MEDIA_ID`	스트림의 ID3 메타데이터에 표시되는 전체 광고 미디어 ID: `AD_MEDIA_ID`

예상 반환 값

`HTTP/1.1 204 No Content`	성공적인 빈 응답입니다.
`HTTP/1.1 404 Not Found`	미디어 확인 ID가 인식되지 않습니다.
`HTTP/1.1 409 Conflict`	미디어 확인 ID가 이미 전송되었습니다.

요청 예시(cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

응답 예시

HTTP/1.1 204 No Content

제한사항

WebView 내에서 API를 사용하면 타겟팅과 관련하여 다음 제한사항이 적용됩니다.

UserAgent: 사용자 에이전트 매개변수가 기본 플랫폼 대신 브라우저별 값으로 전달됩니다.
rdid, idtype, is_lat: 기기 ID가 올바르게 전달되지 않아 다음 기능 작동이 제한됩니다.
- 최대 게재빈도 설정
- 순차적 광고 로테이션
- 잠재고객 분류 및 타겟팅

개요