시작하기 전에
이 가이드에서는 IMA DAI SDK가 없는 경우의 재생 안내만 다룹니다.
사전에 Google Ad Manager(GAM)와 라이브 스트림 통합 단계를 완료했는지 확인합니다.
원하는 플랫폼에서 IMA SDK를 사용할 수 없으면 애플리케이션에서 필요한 API를 호출하고 광고 노출 자체를 트리거하도록 해야 합니다.
이렇게 하려면 다음 정보가 필요합니다.
| 위치 |
The
라이브 구성이 생성된 Google Cloud 리전:
LOCATION
|
| 프로젝트 번호 |
Video Stitcher API를 사용하는 Google Cloud 프로젝트의 프로젝트 번호:
PROJECT_NUMBER
|
| OAuth 토큰 |
Video Stitcher 사용자 역할이 포함된 서비스 계정의 단기 OAuth 토큰:
OAUTH_TOKEN 단기 OAuth 토큰 만들기에 대해 자세히 알아보세요. |
| 네트워크 코드 |
광고 요청에 사용되는 Ad Manager 네트워크 코드:
NETWORK_CODE
|
| 라이브 구성 ID |
라이브 스트림 이벤트를 만들 때 지정한 라이브 구성 ID:
LIVE_CONFIG_ID
|
| 커스텀 애셋 키 |
Video Stitcher API를 사용하여 라이브 스트림 이벤트 구성을 만드는 프로세스에서 생성된 Ad Manager 커스텀 애셋 키:
CUSTOM_ASSET_KEY
|
Ad Manager에 스트림 등록 요청 보내기
스트림 등록 엔드포인트에 POST 요청을 보냅니다. 그러면 동영상 병합 API로 전송할 스트림 ID가 포함된 JSON 응답이 수신됩니다.
API 엔드포인트
POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
경로 매개변수
NETWORK_CODE |
Google Ad Manager 360 네트워크 코드:
NETWORK_CODE
|
CUSTOM_ASSET_KEY |
Google Ad Manager에서 이 이벤트와 연결된 커스텀 식별자:
CUSTOM_ASSET_KEY
|
양식으로 인코딩된 본문 매개변수
양식으로 인코딩된 타겟팅 매개변수의 선택적 집합입니다.
응답 JSON
media_verification_url |
재생 추적 이벤트를 핑하는 기준 URL입니다. 이 기준 URL에 광고 이벤트 ID를 추가하면 완전한 미디어 인증 URL이 구성됩니다.
MEDIA_VERIFICATION_URL
|
metadata_url |
광고 모음 메타데이터를 요청하는 URL입니다.
METADATA_URL
|
polling_frequency |
`metadata_url`을 폴링할 권장 빈도(밀리초)입니다.
POLLING_FREQUENCY
|
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/x-www-form-urlencoded" \
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream응답 예시
{
"stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
"media_verification_url":"https://dai.google.com/.../media/",
"metadata_url":"https://dai.google.com/.../metadata",
"session_update_url":"https://dai.google.com/.../session",
"polling_frequency":10
}
오류가 발생하면 JSON 응답 본문 없이 표준 HTTP 오류 코드가 반환됩니다.
JSON 응답을 파싱하고 관련 값을 저장합니다.
세션 재생 URI 생성
Video Stitcher API의 /livesessions 엔드포인트에 POST 요청을 보내 새 라이브 세션을 만듭니다. 그러면 동영상 플레이어에 로드할 스트림 매니페스트가 포함된 JSON 응답이 수신됩니다.
API 엔드포인트
POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json
경로 매개변수
PROJECT_NUMBER |
Video Stitcher API를 사용하는 Google Cloud 프로젝트의 프로젝트 번호:
PROJECT_NUMBER
|
LOCATION |
The
라이브 구성이 생성된 Google Cloud 리전:
LOCATION
|
승인 헤더 매개변수
OAUTH_TOKEN |
Video Stitcher 사용자 역할이 포함된 서비스 계정의 단기 OAuth 토큰:
OAUTH_TOKEN |
JSON으로 인코딩된 본문 매개변수
liveConfig |
A 프로젝트 번호, 위치, 라이브 구성 ID가 포함된 다음 형식의 문자열:
projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
|
adTracking |
클라이언트 측 추적을 사용 설정하려면 "CLIENT"로 설정합니다. |
gamSettings |
스트림 ID가 포함된 다음 형식의 객체:
{"streamId":"STREAM_ID"}
|
응답 JSON
name |
세션 ID가 포함된 라이브 세션의 이름입니다. |
playUri |
재생할 동영상 플레이어에 로드할 병합된 스트림 매니페스트 URI입니다.
PLAY_URI
|
liveConfig |
요청 본문에서 API에 전송된 문자열과 동일한 liveConfig 문자열입니다.
|
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/liveSessionsrequest.json
{
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
"adTracking": "CLIENT",
"gamSettings": {
"streamId": "STREAM_ID"
}
}
응답 예시
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
"playUri": PLAY_URI,
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
"gamSettings": {
"streamId": STREAM_ID
}
}
응답이 수신된 후에 응답 객체의 playUri 필드에서 세션 재생 URI를 참조하여 광고 병합 라이브 스트림을 재생할 수 있습니다.
Video Stitcher API는 요청마다 고유한 세션 ID를 생성하며 응답 객체의 name 필드 마지막 섹션에서 이 ID를 검색할 수 있습니다.
유휴 상태 세션은 5분 후에 만료됩니다. 일정 기간 내에 매니페스트 가져오기가 수행되지 않으면 세션은 유휴 상태로 간주됩니다.
새 AdBreak 메타데이터 폴링
애플리케이션은 각 광고 시점의 메타데이터를 검색할 책임이 있으므로 트리거해야 하는 노출을 파악합니다. 이를 위해 DAI API metadata_url에서 새로운 광고 정보를 정기적으로 폴링하는 타이머를 설정합니다. 폴링 간격은 스트림 등록 응답의 polling_frequency 필드에 지정됩니다.
그러면 다음 매개변수가 포함된 JSON 객체가 수신됩니다.
tags |
스트림 내에서 발생할 광고 미디어 이벤트를 설명하는 키-값 쌍 세트입니다. 각 키는 스트림의 ID3 메타데이터에 표시되는 광고 미디어 ID의 첫 17자나 `progress` 이벤트의 경우 전체 광고 미디어 ID로 구성됩니다. 각 값은 다음 속성을 가진 객체입니다.
|
ads |
스트림 내에 표시될 광고를 설명하는 키-값 쌍 세트입니다. 각 키는 광고 ID입니다. 각 값은 다음 속성을 가진 객체입니다.
|
ad_breaks |
스트림 내에서 발생할 광고 시점을 설명하는 키-값 쌍 세트입니다. 각 키는 광고 시점 ID입니다. 각 값은 다음 속성을 가진 객체입니다.
|
각 폴링 후에 이러한 값을 저장하여 동영상 스트림 내에서 시간 표시 메타데이터 이벤트를 연결합니다.
요청 예시(cURL)
curl https://dai.google.com/.../metadata/응답 예시
{
"tags":{
"google_0492266569":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"firstquartile"
},
"google_1560331148":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"thirdquartile"
},
"google_1877686714378797835":{
"ad":"0000229836_slate",
"ad_break_id":"0000229836",
"type":"progress"
},
"google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"progress"
},
"google_2032765498":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"midpoint"
},
...
"google_5646900623":{
"ad":"0000229837_ad1",
"ad_break_id":"0000229837",
"type":"complete"
}
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15.01,
"title":"truman-e2e-creativeset4",
"description":"truman-e2e-creativeset4 ad",
"ad_system":"GDFP",
"ad_id":"39066884",
"creative_id":"58092079124",
"clickthrough_url":"https://pubads.g.doubleclick.net/...",
"universal_ad_id":{
"id_value":"58092079124",
"id_registry":"GDFP"
}
},
"0000229834_slate":{
"ad_break_id":"0000229834",
"position":-1,
"duration":14.974977777,
"slate":true
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15.01,
"expected_duration":29.984977776999997,
"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가 올바르게 전달되지 않아 다음 기능 작동이 제한됩니다.
- 최대 게재빈도 설정
- 순차적 광고 로테이션
- 잠재고객 분류 및 타겟팅