광고 모음 게재 리디렉션을 위해 클라이언트 준비

이 가이드에서는 포드 게재 API와 매니페스트 조작기를 사용하여 HLS 또는 DASH 라이브 스트림을 로드하는 클라이언트 애플리케이션을 개발하는 방법을 설명합니다.

기본 요건

계속하려면 다음이 필요합니다.

• Pod serving redirect DAI 유형으로 구성된 라이브 스트림 이벤트의 맞춤 애셋 키입니다. 이 키를 가져오려면 다음 단계를 따르세요.

  • DAI용 라이브 스트림을 설정합니다.

  • SOAP API 클라이언트 라이브러리를 사용하여 LiveStreamEvent 객체와 dynamicAdInsertionType 속성이 POD_SERVING_REDIRECT enum 값으로 설정된 LiveStreamEventService.createLiveStreamEvents 메서드를 호출합니다. 모든 클라이언트 라이브러리의 경우 클라이언트 라이브러리 및 예시 코드를 참고하세요.

• 플랫폼에서 양방향 미디어 광고 (IMA) SDK를 사용할 수 있는지 확인합니다. IMA SDK를 사용하여 수익을 늘리는 것이 좋습니다. 자세한 내용은 DAI용 IMA SDK 설정을 참고하세요.

스트림 요청하기

사용자가 스트림을 선택하면 다음을 실행합니다.

1. 라이브 스트림 서비스 메서드에 POST 요청을 실행합니다. 자세한 내용은 메서드: 스트림을 참고하세요.

2. application/x-www-form-urlencoded 또는 application/json 형식으로 광고 타겟팅 매개변수를 전달합니다. 이 요청은 Google DAI에 스트림 세션을 등록합니다.

   다음 예에서는 스트림 요청을 수행합니다.

   양식 인코딩

   const url = `https://dai.google.com/ssai/pods/api/v1/` +
         `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
   
   const params = new URLSearchParams({
           cust_params: 'section=sports&page=golf,tennis'
   }).toString();
   
   const response = await fetch(url, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/x-www-form-urlencoded'
           },
           body: params
   });
   
   console.log(await response.json());
   

   JSON 인코딩

   const url = `https://dai.google.com/ssai/pods/api/v1/` +
         `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
   
   const response = await fetch(url, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json'
           },
           body: JSON.stringify({
             cust_params: {
               section: 'sports',
               page: 'golf,tennis'
             }
           })
   });
   
   console.log(await response.json());
   

   성공하면 다음과 비슷한 출력이 표시됩니다.

   {
   "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
   "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
   "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
   "session_update_url": "https://dai.google.com/linear/.../session",
   "polling_frequency": 10
   }
   

3. JSON 응답에서 스트림 세션 ID를 찾아 후속 단계를 위해 다른 데이터를 저장합니다.

광고 메타데이터 폴링

광고 메타데이터를 폴링하려면 다음 단계를 따르세요.

1. 스트림 등록 응답에서 metadata_url 값을 읽습니다.

2. metadata_url 엔드포인트에 초기 GET 요청을 수행합니다.

   • delta_token 쿼리 매개변수를 생략합니다. 이 프로세스를 통해 서버는 스트림의 디지털 동영상 녹화기 (DVR) 창에 대한 전체 메타데이터를 반환할 수 있습니다. DVR 창에는 시청자가 되감기하고 재생할 수 있는 방송 기간이 표시됩니다. 응답에는 next_delta_token 필드가 포함됩니다.

3. 대역폭을 최적화하려면 가장 최근 응답의 next_delta_token 값을 저장하세요.

4. 다음 요청에서 이 값을 delta_token 쿼리 매개변수로 전송합니다. 서버는 토큰이 생성된 이후 변경된 메타데이터만 반환합니다. 항상 수신한 최신 토큰을 전송합니다. 토큰을 파싱하거나 수정하거나 구성하려고 하지 마세요. 자세한 내용은 메서드: 메타데이터를 참고하세요.

   다음 예에서는 광고 메타데이터를 가져옵니다.

   // Initial request (returns full metadata and next_delta_token)
   let response = await fetch(metadata_url);
   let metadata = await response.json();
   let deltaToken = metadata.next_delta_token;
   
   // Subsequent request (returns only changes since deltaToken)
   if (deltaToken) {
     const url = new URL(metadata_url);
     url.searchParams.append('delta_token', deltaToken);
     response = await fetch(url.toString());
     const deltaMetadata = await response.json();
     // Merge deltaMetadata into your local cache
     mergeMetadata(metadata, deltaMetadata);
     deltaToken = deltaMetadata.next_delta_token;
   }
   

   성공하면 PodMetadata 응답이 수신됩니다. delta_token 매개변수를 제공하면 서버가 토큰을 생성한 이후 서버에서 추가하거나 업데이트한 광고, 광고 시점, 태그만 응답에 포함됩니다. 응답에는 새 next_delta_token 값도 포함됩니다. 오래된 광고 시점이 있으면 응답에 캐시에서 삭제할 광고 시점의 obsolete_ad_break_ids 목록도 포함됩니다.

   {
     "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
     "obsolete_ad_break_ids": ["0003069407"],
     "tags":{
       "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
       },
       ...
     },
     "ads":{
       "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         "clickthrough_url":"https://.../",
         ...
       },
       ...
     },
     "ad_breaks":{
       "0003069408":{
         "type":"mid",
         "duration":30,
         "ads":3
       },
       ...
     }
   }
   

5. tags 객체를 저장하고 업데이트를 로컬 캐시에 병합합니다. obsolete_ad_break_ids 매개변수가 있으면 캐시에서 해당 광고 시점과 연결된 광고 및 태그를 삭제합니다.

6. polling_frequency 값을 사용하여 정기적으로 메타데이터를 요청하는 타이머를 설정합니다. 각 폴링에서 최신 메타데이터 응답에 반환된 next_delta_token 값을 delta_token 쿼리 매개변수로 전송합니다.

동영상 플레이어에 스트림 로드

등록 응답에서 세션 ID를 가져온 후 ID를 매니페스트 조작기에 전달하거나 매니페스트 URL을 구성하여 스트림을 동영상 플레이어에 로드합니다.

세션 ID를 전달하려면 매니페스트 조작기 문서를 참고하세요. 매니페스트 조작기를 개발하는 경우 라이브 스트림용 매니페스트 조작기를 참고하세요.

다음 예에서는 매니페스트 URL을 어셈블합니다.

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

플레이어가 준비되면 재생을 시작합니다.

광고 이벤트 수신 대기

스트림의 컨테이너 형식에서 시간 제한 메타데이터를 확인합니다.

• 전송 스트림 (TS) 컨테이너가 있는 HLS 스트림은 시간 제한 ID3 태그를 사용하여 시간 제한 메타데이터를 전달합니다. 자세한 내용은 HTTP 라이브 스트리밍(HLS)을 사용하는 Common Media Application Format 정보를 참고하세요.

• DASH 스트림은 EventStream 요소를 사용하여 매니페스트의 이벤트를 지정합니다.

• 세그먼트에 ID3 태그를 비롯한 페이로드 데이터의 이벤트 메시지 (emsg) 상자가 포함된 경우 DASH 스트림은 InbandEventStream 요소를 사용합니다. 자세한 내용은 InbandEventStream을 참고하세요.

• DASH 및 HLS를 비롯한 CMAF 스트림은 ID3 태그가 포함된 emsg 상자를 사용합니다.

스트림에서 ID3 태그를 가져오려면 동영상 플레이어 가이드를 참고하세요. 자세한 내용은 시간이 지정된 메타데이터 처리 가이드를 참고하세요.

ID3 태그에서 광고 이벤트 ID를 가져오려면 다음 단계를 따르세요.

1. urn:google:dai:2018 또는 https://aomedia.org/emsg/ID3로 scheme_id_uri별로 이벤트를 필터링합니다.

2. message_data 필드에서 바이트 배열을 추출합니다.

   다음 예시에서는 emsg 데이터를 JSON으로 디코딩합니다.

   {
     "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
     "presentation_time": 27554,
     "timescale": 1000,
     "message_data": "ID3TXXXgoogle_1022389921",
     ...
   }
   

3. TXXXgoogle_{ad_event_ID} 형식으로 ID3 태그를 필터링합니다.

   TXXXgoogle_1022389921
   

광고 이벤트 데이터 표시

TagSegment 객체를 찾으려면 다음 단계를 따르세요.

1. 광고 메타데이터 폴링에서 광고 메타데이터 tags 객체를 가져옵니다. tags 객체는 TagSegment 객체의 배열입니다.

2. 전체 광고 이벤트 ID를 사용하여 유형이 progress인 TagSegment 객체를 찾습니다.

3. 광고 이벤트 ID의 처음 17자를 사용하여 다른 유형의 TagSegment 객체를 찾습니다.

   클라이언트 앱이 광고 메타데이터를 주기적으로 폴링하므로 동영상 플레이어가 스트림에서 ID3 태그를 발견한 시점과 연결된 메타데이터를 사용할 수 있는 시점 사이에 지연이 발생할 수 있습니다. 클라이언트 앱이 저장된 태그에서 ID3 태그를 찾지 못하면 태그를 큐에 유지하고 다음 메타데이터 폴링 후 태그를 다시 처리합니다. 처리가 완료될 때까지 태그를 대기열에 유지합니다.

4. TagSegment를 가져온 후 ad_break_id 속성을 키로 사용하여 광고 메타데이터 ad_breaks 객체에서 AdBreak 객체를 찾습니다.

   다음 예에서는 AdBreak 객체를 찾습니다.

   {
     "type":"mid",
     "duration":15,
     "ads":1
   }
   

5. TagSegment 및 AdBreak 데이터를 사용하여 광고 시점의 광고 위치에 관한 정보를 표시합니다. 예를 들면 Ad 1 of 3입니다.

미디어 확인 핑 전송

progress 유형을 제외한 모든 광고 이벤트에 대해 미디어 확인 핑을 전송합니다. Google DAI는 progress 이벤트를 삭제하며 이러한 이벤트를 자주 전송하면 앱 성능에 영향을 미칠 수 있습니다.

광고 이벤트의 전체 미디어 인증 URL을 생성하려면 다음 단계를 따르세요.

1. 스트림 응답에서 전체 광고 이벤트 ID를 media_verification_url 값에 추가합니다.

2. 전체 URL로 GET 요청을 수행합니다.

   // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
   const completeUrl = `${media_verification_url}google_1022389921`;
   
   const response = await fetch(completeUrl);
   

   성공하면 코드 상태 202 응답이 수신됩니다. 그렇지 않으면 404 오류 코드가 표시됩니다.

라이브 스트림 활동 모니터링 도구 (SAM)를 사용하여 모든 광고 이벤트의 기록 로그를 검사할 수 있습니다. 자세한 내용은 라이브 스트림 모니터링 및 문제 해결을 참고하세요.