비디오 클라우드 SSAI API

광고 구성은 광고 통화, 비콘 및 기타 구성 옵션을 포함하여 SSAI 재생의 다양한 측면을 정의합니다. 계정에는 여러 구성이 있을 수 있으며 현재 구성을 계정 간에 공유할 수 없습니다.

일반 정보

다음 정보는 모든 SSAI API 요청과 관련이 있습니다.

기본 URL

SSAIAPI의 기본 URL은 다음과 같습니다.

https://ssai.api.brightcove.com/v1

계정 경로

모든 경우에 특정 Video Cloud 계정에 대한 요청이 이루어집니다. 따라서 항상 기본 URL에 용어accounts뒤에 계정 ID를 추가해야 합니다.

https://ssai.api.brightcove.com/v1/accounts/your account id

인증

요청에 대한 인증에는 권한 부여 헤더가 필요합니다.

Authorization: Bearer your access token

access_token는 브라이트코브 OAuth 서비스에서 가져와야 하는 임시 OAuth2 액세스 토큰입니다. 클라이언트 자격 증명을 얻고 이를 사용하여 액세스 토큰을 검색하는 방법에 대한 자세한 내용은 Brightcove API 요청에 대한 인증을 참조하십시오.

운영

클라이언트 자격 증명을 요청할 때 원하는 계정 액세스 또는 작업 유형을 지정해야 합니다. 다음은 SSAI API에 대해 현재 지원되는 작업 목록입니다.

• SSAI의 데이터:

  video-cloud/ssai/read
video-cloud/ssai/all

광고 구성 관리

API는 다음과 같은 GET 및 PUT 요청을 지원합니다.

• 광고 구성 나열
• 광고 구성 만들기
• 광고 구성 세부 정보 가져오기
• 광고 구성 업데이트

광고 구성 나열

계정에 대해 정의된 광고 구성을 나열합니다.

샘플 응답:

[
  {
    "name": "VMAP Ad Server",
    "vmap_response_namespace": "bc",
    "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
    "account_id": "57838016001",
    "created_timestamp": "2017-07-24T19:28:34.976878586Z",
    "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_config": {
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "template_url": {
          "template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
      }
    }
  }
]

필드 정의는 구성 필드 세부 정보 섹션을 참조하십시오.

광고 구성 만들기

계정에 대한 광고 구성을 만듭니다.

샘플 본문:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_tracking_sample_percentage": 100,
  "ad_config": {
    "expected_ad_response": "vast_3_0",
    "disable_server_beacons": false,
    "round_up_cue_points": false,
    "template_url": {
      "template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  },
  "discontinuities": {
    "hls": [ "*" ]
  }
}

필드 정의는 구성 필드 세부 정보 섹션을 참조하십시오.

참고 사항

• ad_tracking_sample_percentage기록될 세션의 백분율을 결정합니다. 0(로깅 비활성화)에서 100(모든 세션 로그) 사이의 값을 사용할 수 있습니다.

광고 구성 세부 정보 가져오기

계정의 경우 구성 ID별로 광고 구성 세부 정보를 가져옵니다.

	{
		"name": "VMAP Ad Server",
		"vmap_response_namespace": "bc",
		"config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
		"account_id": "57838016001",
		"created_timestamp": "2017-07-24T19:28:34.976878586Z",
		"updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_tracking_sample_percentage": 100,
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
					"template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
			}
		},
		"beacon_templates": [
				{
					"type": "content_start",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "content_midpoint",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "ad_start",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "content_complete",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				}
			],
			"discontinuities": {
				"dash": [
					"*"
				],
				"hls": [
					"*"
				]
			},
			"extend_beacon_guard_ttl": true
		}
	}

필드 정의는 구성 필드 세부 정보 섹션을 참조하십시오.

광고 구성 업데이트

구성 ID로 광고 구성을 업데이트하십시오.

{
    "name": "VMAP Ad Server - updated"
}

	{
		"name": "VMAP Ad Server - updated",
		"vmap_response_namespace": "bc",
		"config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
		"account_id": "57838016001",
		"created_timestamp": "2017-07-24T19:28:34.976878586Z",
		"updated_timestamp": "2017-07-24T19:28:34.976878586Z",
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
				"template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
			}
		}
	}

필드 정의는 구성 필드 세부 정보 섹션을 참조하십시오.

구성 필드 세부 정보

이 표는 요청의 본문 섹션 내에서 사용되는 광고 구성 필드를 정의합니다.

광고 응답 유형

다음은 위 표에 나와 있는ad_config.expected_ad_response유형 작업에 대한 몇 가지 추가 정보입니다. 값:

• vast_3_0 - 디지털 동영상 광고 서빙 템플릿 (VAST)
• dfp_vmap - 동영상 멀티플 광고 플레이리스트 (VMAP)
• dfp_ad_rules - 구글 광고 매니저 (GAM) 로 리브랜딩된 구글 DFP 전용 포맷
• smart_xml - 프리휠을 위한 전용 포맷

프로세스 흐름

SSAI 광고 구성을 생성할 때 다음 프로세스 참고 사항에 유의하십시오.

VMAP

SSAI 구성의 광고 응답 유형이 DFP VMAP인 경우:

• 비디오로 구성된 모든 큐 포인트는 무시됩니다.
• SSAI는 정의된 위치의 모든 광고가 포함된 광고 공급자의 VMAP XML 파일을 구문 분석합니다.

VAST

SSAI 구성의 광고 응답 유형이 VAST 3.0인 경우:

• 비디오에서 큐 포인트를 정의합니다. SSAI는 광고 시점을 구성하기 위해 비디오의 각 큐 포인트에 대해 요청을 합니다.
• 동영상에 큐 포인트가 구성되지 않은 경우 기본적으로 프리롤 광고가 삽입됩니다.

광고 변수

템플릿 URL의 변수는 변수 경로 앞뒤에 선택적 공백이 있는 이중 중괄호 ( {{ … }} ) 로 식별됩니다. 모든 변수에는 세 개의 네임스페이스 중 하나가 접두사로 붙어있습니다.

• 시스템
• url
• 메타데이터

시스템 변수

시스템 변수는 SSAI에서 제공하며 임의의 값을 생성하기 위한 최종 사용자 또는 도우미 변수에 대한 정보일 수 있습니다. 값은 URL 템플릿에 삽입되기 전에 URI로 인코딩되어야 합니다.

시스템 변수는 다음과 같이 식별됩니다. {{system.*}}

URL 변수

진입점 VMap/매니페스트에 제공된 쿼리 매개 변수는url네임스페이스에서 사용할 수 있습니다. 다른 네임 스페이스의 변수와 달리 이러한 매개 변수는 템플릿에 삽입 할 때 URL이 인코딩되지 않습니다. 변수 값이 광고 공급자로가는 URL로 인코딩되어야하는 경우 진입 점 URL에 이중 URL로 인코딩되어야합니다.

URL 변수는 다음과 같이 식별됩니다. {{url.*}}

다음과 같이 사용자 지정 통합을 사용하여 URL 변수를 교체해야 합니다.

1. Playback API에 요청하는 코드를 작성합니다.
2. API 요청에서 반환된 데이터를 가로채십시오.
3. 소스 URL의 모든{{url.*}}토큰을 교체합니다.
4. 데이터/소스를 플레이어에 로드(웹용 Brightcove Player 또는 기본 SDK)

메타데이터 변수

메타데이터 변수는 비디오 클라우드 및 동적 전송 데이터 소스에서 파생된 콘텐츠 비디오를 설명하는 변수입니다. 값 (제외ad_keys )은 URL 템플릿에 삽입되기 전에 URL로 인코딩됩니다.

메타데이터 변수는 다음과 같이 식별됩니다. {{metadata.*}}

진입점 URL 매개 변수

몇 가지 동작을 조정하기 위해 SSAI의 진입점 URL (VMAP 또는 매니페스트) 에 추가할 수 있는 몇 가지 쿼리 매개 변수가 있습니다.

구성 참고 사항

1. SSAI를 사용하여 광고를 미리 로드하면 안 됩니다. 그 이유는 미리 로드하면 플레이어가 광고 노출과 동영상이 재생되기 전에 첫 번째 사분위수 비콘을 보고하기 때문입니다. 이로 인해 광고 분석이 부정확할 수 있습니다. Studio에서 SSAI를 구성하면 이 작업이 자동으로 수행되지만 수동으로 SSAI를 설정하는 경우에는 이 문제를 알고 있어야 합니다.
2. 웹 플레이어가 SSAI를 사용하고 있고 이를 위한 동기 중 하나가 광고 차단기를 해결하는 것이라면 서버 측 비콘을 사용해야 합니다. 클라이언트 측 비콘은 차단되므로 사용해서는 안 됩니다.

클라이언트 측 매크로

클라이언트측 광고 매크로를 사용하려는 경우page접두사를 사용하십시오. 이러한 매크로를 사용하면 VMAP 및 서버 URL의 변수를 사용할 수 있습니다. 광고 매크로에 대한 자세한 내용은 IMA3 플러그인을 사용한광고 문서의 광고 매크로 및 ServerURL섹션을 참조하십시오.

클라이언트 측 매크로에는 다음과 같은 접두사가 붙습니다. {{page.*}}

예를 들어document.referrer및pageVariable DOM 창 변수를 추가하려면 다음과 같이 광고page템플릿에서 접두사를 붙입니다.

https://adserver.com/{{page.document.referrer}}/{{page.pageVariable.whateverIwant}}

재생 API가document.referrer반환되고 VMAP 및 SRC URL에pageVariable.whateverIwant추가됩니다. 그런 다음 브라이트코브 플레이어는 요청을 보내기 전에 클라이언트 측 매크로 교체 논리를 실행하여 적절한 값을 바꿉니다.

https://bolt-prefix/blah.vmap?document.referrer={document.referrer}&pageVariable.whateverIwant={pageVariable.whateverIwant}

광고 오류 비콘

SSAI를 사용할 때 발생하는 BAST 광고 오류 비콘은 광고 워크플로와 관련된 문제를 사전에 찾고 해결하는 데 도움이 될 수 있습니다. 자세한 내용은 SSAI가 포함된광고 오류 비콘문서를 참조하십시오.