광고 구성은 광고 통화, 비콘 및 기타 구성 옵션을 포함하여 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 OAuth 개요를 참조하십시오 .

운영

클라이언트 자격 증명을 요청할 때 원하는 계정 액세스 또는 작업 유형을 지정해야 합니다. 다음은 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": "http://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_config": {
  	"expected_ad_response": "vast_3_0",
  	"disable_server_beacons": false,
    "round_up_cue_points": false,
  	"template_url": {
  		"template": "http://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": [ "*" ]
  }
}

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

계정의 경우 구성 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_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
        "template": "http://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": "http://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 }}"
    }
  }
}

구성 필드 세부 정보

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

광고 변수

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

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

시스템 변수

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

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

URL 변수

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

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

메타데이터 변수

메타데이터 변수는 비디오 클라우드 및 동적 전송 데이터 소스에서 파생된 콘텐츠 비디오를 설명하는 변수입니다. 값은 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가 포함된광고 오류 비콘문서를 참조하십시오.