새 플레이어 관리 API 레지스트리 안내

목차

들어가기

브라이트코브의 (비디오) 플레이어 관리 API 는 퍼블리셔를 위한 리소스로 플레이어를 생성, 편집 및 관리하는 기능을 수행합니다. 관리 API의 REST API는 플레이어 인스턴스를 생성 및 구성하고 미리 보기와 게시 할 수 있는 엔드포인트(endpoint)를 제공합니다. 브라이트코브는 Public API에 혁신적이나 이전 버전과 호환되지 않는 변경사항을 추가하기 위해 다음 버전을 위한 새 엔드포인트를 추가하였습니다.

문제점

대다수의 브라이트코브 플레이어들은 플레이백 플러그인 구성(configuration)을 위해 스크립트와 스타일시트를 사용합니다. 이 스크립트와 스타일시트는 서드파티 통합(third party integration)을 위한 커스텀 스크립트를 사용하거나 이미 브라이트코브 스튜디오에 준비된 플러그인 스크립트를 사용할 수 있습니다. 스튜디오가 플레이어 관리 API에 가장 많은 요청을 보낼 뿐만 아니라 많은 인기 플러그인 (광고소셜 미디어재생목록, 등)을 사용할 수 있게 하기 때문에 이러한 플러그인들과 관련된 스크립트와 스타일시트는 퍼블리셔 구성(configuration)에 매우 흔하게 사용됩니다.

그러나 스튜디오가 API를 통해 플레이어에 추가한 스크립트와 스타일시트는 구 버전과 호환되지 않는 변경사항을 고려하지 않았습니다. 단순히 각 플러그인의 최신 코드를 위한 정적(static) URL을 제공했을 뿐입니다. 또한 비(非) 스튜디오 API 사용자의 경우 스스로 스크립트와 스타일시트를 직접 관리해야하며URL이 플러그인 문서(document) 사이에 흩어져 있다는 문제점이 있습니다.

퍼블리셔가 소셜 미디어 플러그인을 추가한 후 스튜디오에 의해 생성된 플레이어 구성 스니펫(snippet) 예시는 아래와 같습니다.

{
 "scripts": [ "//players.brightcove.net/videojs-social/3/videojs-social.min.js" ],
 "stylesheets": [ "//players.brightcove.net/videojs-social/3/videojs-social.css" ],
 "plugins": [ { "name": "social" } ]
}

스튜디오가 추가한 이러한 스크립트와 스타일시트는 다음과 같은 이유로 인해 문제가 될 수 있습니다:

  1. 플레이어 버전과 플러그인 스크립트와 스타일시트 간의 호환성이 전혀 고려되지 않았습니다

새로운 브라이트코브 플레이어 버전이 출시되거나 퍼블리셔가 스튜디오 내 플레이어를 업데이트함에 따라 스튜디오가 삽입한 정적 URL이 더 이상 호환되지 않을 가능성이 커집니다.

  1. URL에 의해 명시된 리소스가 새로운 브라이트코브 소셜 미디어 플러그인이 출시됨에 따라 변경될 것입니다

브라이트코드 도메인에 저장되는 방식으로 인해 플러그인 스크립트와 스타일시트가 /3/ 을 URL 경로에 명시하면 소셜미디어 플러그인 주요 버전3과 호환 가능한 최신 코드로 이동합니다. 새로운 버전이 출시 때마다 새 플레이어의 게시(publish) 요청은 최신 기능을 자동적으로 받기 위해 업데이트된 코드를 가져옵니다. 그리고 이는 버전 유지를 위해 스튜디오 내“수동 업데이트 모드”를 사용하는 퍼블리셔에 영향을 끼칩니다. 플레이어를 리퍼블리싱 하는 것은 별도의 구성 변경없이 새로운 플러그인 코드를 포함시키는 결과를 불러일으킬 수 있습니다.

  1. 주요 버전 내 기존 스크립트와 스타일시트 URL를 업데이트하는 방안이 없습니다

유의적버전(semver) 호환을 위해 플러그인 코드를 구(舊) 버전과 호환 되지 않게 변경하는 것은 스크립트와 스타일시트의 새 주요 버전과 그에 상응하는 URL을 필요로 합니다. 그러나 스튜디오에 정적 URL 수정 기능이 없을뿐더러 스튜디오를 사용하지 않고 플레이어를 퍼블리셔에서 가장 최근 URL로 안전하게 이동할 수 있는 방법은 존재하지 않습니다.  

문제 해결: 플러그인 레지스트리(plugin registry)

플레이어 관리 API최신 버전은 플러그인 레지스트리라는 새로운 구성요소를 통해 이러한 문제를 해결합니다. 플러그인 레지스트리는 스튜디오가 현재 사용하는 플러그인들의 다양한 버전들을 잘 정리된 목록으로 제공합니다.

브라이트코브의 소셜미디어 플러그인 registry_id 를 적절한 주(主) 버전과 조합하면 위의 플레이어 구성 스니펫을 다음과 같이 변경할 수 있습니다:

{
 "scripts": [],
 "stylesheets": [],
 "plugins": [ { "registry_id": "@brightcove/videojs-social", "version": "3.x" } ]
}

플레이어 배열 앨레먼트(element) 내 플레이어 관리 registry_id 와 version 의 조합은 플레이어 관리 API에 이 플러그인 관리를 위해 플러그인 레지스트리를 사용하라고 지시를 내리는 것과 같습니다. 플레이어가 퍼블리시 될 때 직접 지정하지 않아도 플레이어 게시 간 해당 스크립트와 스타일시트가 플레이어 구성에 삽입됩니다.

만약 플러그인 version을 세부적으로 설정하고자 한다면, 다음과 같이 명시할 수 있습니다:

{
 "scripts": [],
 "stylesheets": [],
 "plugins": [ { "registry_id": "@brightcove/videojs-social", "version": "3.6.0" } ]
}

이제 플레이어는 모든 향후 퍼블리싱 리퀘스트에 대해 소셜 미디어 플러그인 버전 3.6.0의 스크립트와 스타일시트를 받아 볼 수 있습니다.

문제 해결: Before & After

플러그인 레지스트리의 중요성을 보다 강조하기 위해 스튜디오 플러그인 스크립트와 스타일시트를 관리하는 기존 시스템에서 찾은 문제를 다시 한번 살펴보겠습니다.

1.    (Before)플레이어 버전과 플러그인 스크립트와 스타일시트 간의 호환성이 전혀 고려되지 않았습니다

(After)이제 이 호환성 문제는 플레이어 생성, 편집 및 게시 간 플레이어 관리 API에 의해 자동적으로 관리됩니다. 플레이어 버전과 호환 되지 않는 플러그인 version 속성(property) 지정을 시도하면 적절한 에러 메시지와 함께 API에 의해 거절 됩니다.

덧붙여, 이제 스튜디오는 플레이어 버전과 호환 가능한 플러그인을 요청을 위해 플러그인 레지스트리를 사용합니다. 이는 새로운 버전이 출시될 때 마다 플레이어와 플러그인들이 서로 상호 호환 가능하게 합니다.

2.    (Before)URI에 의해 명시된 리소스는 새로운 브라이트코브 소셜미디어 플러그인 버전이 출시됨에 따라 변경될 것 입니다.

(After)플러그인 version 속성을 기반을 하여 퍼블리싱 시간에 플레이어로 삽입되기 때문에 플러그인을 위한 스크립트와 스타일시트는 더 이상 이러한 URL을 참조할 필요 없습니다.

추가로 “수동 업데이트 모드”로 특정 버전에 플레이어를 고정하면 플러그인 버전 역시 고정됩니다. 이는 플레이어가 플러그인 주 버전을 지정하면 향후 게시 요청을 보내도 버전이 고정된 바로 그 시간에 상응하는 플러그인 버전이 유지됩니다.

3.    (Before)주요 버전 내 기존 스크립트와 스타일시트 URL를 업데이트하는 방안이 없습니다

(After)플러그인의 새 version 속성은 과거, 현재 또는 심지어 향후 그 어떤 플러그인 버전이라도 지정할 수 있습니다!

플레이어 관리 API 버전 분리

기존 플레이어 구성에서 새 플러그인 레지스트리 호환 포맷으로 이동하면 문제를 바로 해결할 수 있으나 플레이어 관리 API 현 사용자들에게 실현가능 하지 않습니다. 대부분의 서드파티 통합(thirty party integration)은 플레이어 구성이 지정한 플러그인이 registry_id 및 version 속성 보다 name 속성을 가지고 있을 것이라 예상합니다.

그렇기에 플레이어 관리 API 현 버전에서 새로운 플러그인 레지스트리를 활용할 수 없다면 새로운 주 버전을 택한다는 한가지 방법 밖에 없습니다!

우리는 플레이어 관리 API /v2/ 에서 API 서드파티 사용자와의 기존 인터랙션에 구애 받지 않기에 기존 플러그인 레지스트리와 호환 가능한 새 포멧으로 돌아 갈 수 있습니다. 이러한 통합은 플러그인 레지스트리의 이점 활용을 위해 업데이트 되어야 합니다.

전환 방법과 원리

플레이어 관리 API /v1/ 으로 가는 요청 처리를 즉시 중단하지는 않을 예정이며 아직 /v1/ 과 /v2/ 모두 유효한 엔드포인트로 사용할 수 있습니다. 물론 이는 서로 다른 포맷을 지원하면서 API 주요 버전 간의 플레이어 상호운용성을 유지해야 한다는 문제가 발생합니다.

문제 해결을 위해 기존 플레이어 구성을 새로운 플러그인 레지스트리 호환 포맷으로 이동하는 한편 API를 통해 플레이어 구성 변경을 위한 트랜스레이션 레이어(translation layer)를 추가했습니다. /v1/ 엔드포인트와 부합하는 플레이어 구성을 위한 모든 읽기 요청은 registry_id 와 version속성을 보유한 플러그인 제거 후 해당 배열 내 알맞은 스크립트와 스타일시트 URL로 교체될 수 있게 변경됩니다.

동일한 절차가 /v1/ 엔드포인트에서 플레어 구성 변경을 위해 역으로 발생합니다. 레지스트리에 저장된 플러그인과 일치하는 스크립트와 스타일시트를 포함한 플레이어 구성은 새로운 포맷으로 자동적으로 이동됩니다. 예를 들어 /v1/ 엔드포인트에서 플레이어 구성을 다음과 같이 생성 또는 변경하면…

{
  "scripts": [ "//players.brightcove.net/videojs-social/3/videojs-social.min.js" ],
  "stylesheets": [ "//players.brightcove.net/videojs-social/3/videojs-social.css" ],
  "plugins": [ { "name": "social" } ]
}

…아래와 같은 /v2/ 엔드포인트에서 이용 가능한 플레이어 구성을 도출합니다:

{
  "scripts": [],
  "stylesheets": [],
  "plugins": [ { "registry_id": "@brightcove/videojs-social", "version": "3.x" } ]
}

/v1/ 엔드포인트에서 플레이어 구성 요청 사항은 스크립트와 스타일시트가 인풋과 일치하기에 변경되지 않을 것 입니다. 사실 이 절차는 레지스트리 플러그인 주요 및 특정 버전과 일치하는 스크립트와 스타일시트를 위한 것입니다. 레지스트리 플러그인과 일치하지 않는 스크립트와 스타일시트는 영향을 받지 습니다. 다만 /v2/ 엔드포인트에서 트랜스레이션이 발생하지 않을 수 있기 때문에 구(舊) 포맷을 사용하지 않는 것을 권합니다. 스튜디오가 새로운 포맷을 예상하고 있기에 구형 포맷을 사용한다면 문제가 발생할 수 있습니다.

트랜스레이션 절차의 이해를 위해 다음의 그림을 참조하십시오:

v2 blog (1).png

이 절차는 내부 플레이어 구성 스토리지를 위해 플러그인 엔트리의 단일 포맷을 유지하고 플레이어 관리 API가 두 주요 버전 엔드포인트 간 유동성을 유지할 수 있게 합니다. 

Inlining Scripts & Stylesheets

플러그인 레지스트리 뿐만 아니라 플레이어 관리 API /v2/ 는 플러그인 배열 원소 내 플러그인 스크립트와 스타일시트 인라이닝을 직접 지원합니다. 이는 가독성과 플레이어 구성 논리 구조에 도움이 되며 구성 에러를 방지하는데 도움이 됩니다.

아래와 같은 플레이어 구성 스니펫은 스크팁트와 스타일시트를 인라이닝한 커스텀 플러그인을 보여줍니다:

{ 
  "plugins": [ 
    {
      "name": "helloPlugin",
       "scripts": [ "http://solutions.brightcove.com/truggles/helloPlugin.js" ],
       "stylesheets": [ "http://solutions.brightcove.com/truggles/hello.css" ]
    }
  ]
}

마무리

플레이어 관리 API 플러그인 레지스트리는 플러그인의 버전 관리를 직관적으로 유지하고 안전하게 자동적으로 만들어 줍니다. 트랜스레이션 레이어는 현 브라이트코브 API 사용자들이 새로운 데이터 포맷으로 쉽게 전환할 수 있게 합니다. 플러그인 레지스트리는 기존 플러그인의 향후 버전 지원뿐만 아니라 완전히 다른 새 플러그인 추가를 지원할 수 있게 디자인 되었습니다. 점점 추가되는 플러그인들을 통해 플레이어 구성이 더 쉬워집니다.

FAQs

Q. 플레이어 관리 API /v1/ 은 언제 공식적으로 중단되나요?

A. 2018년 3월 31일 중단됩니다. 그 시점이 오면 서드파티 통합을 포함한 모든 API 사용자들은 반드시 /v2/ 엔드포인트를 사용해야 합니다.

Q. 위의 내용이 커스텀 플러그인에 영향을 주나요?

A. 아닙니다. 레지스트리에 명시된 플러그인들만 새 포맷에서 사용 가능 합니다. 레지스트리 내 플러그인의 트랜스레이션은 커스텀 플러그인에 지장을 주지 않습니다.

Q. 이러한 변경사항이 플레이어 실행 시 플러그인 시행 순서를 변경하나요?

A. 레지스트리 플러그인을 위한 스크립트와 스타일시트는 플레이어가 게시 (publish) 될 때 각 배열 시작 부분에 삽입됩니다. 이는 모든 커스텀 플러그인들이 플레이어 구성 registry_id 에 의해 명시된 브라이트코브 플러그인 시행 이후에 작동 한다는 뜻입니다.

Q. 현재 레지스트리에 어떤 플러그인들이 있는지 어떻게 확인하나요?

A. 플러그인 레지스트리 기록은 레지스트리에 저장된 플러그인에 대한 접근 방법을 설명합니다.