Page tree
Skip to end of metadata
Go to start of metadata
 Version History

작성일

문서버전

비고

2016.05.03

v1.0

문서 초안 작성

2017.02.09

v1.1

seekable_end, disable_playrate 추가

2017.03.09

v1.2

live.url, live.poster_url 추가

2017.03.23

v1.3

title 추가

2017.06.26

v1.4

cdn, auth_type, use_ip_validation, use_kollus_token 추가

2017.09.06

v1.5

pc_skin 추가

2017.12.19

v1.6

Live spec에 kollus 인증 추가

2018.02.08

v1.7

thumbnail 추가

2018.08.20

v1.8

subtitle_policy, drm_policy 추가

live jwt payload 항목 추가

2018.10.29

v1.9

video_watermarking_code_policy 추가

2018.11.06

v1.10

play_section 추가

2019.01.07

v.1.11

video_watermarking_code_policy.enable_html5_player 추가

2019.03.06

v.1.12

live chatting 옵션 추가, live payload key 추가 및 레가시 처리

2019.07.11

v.1.13

Live spec 에 video_watermarking_code_policy 추가

2019.07.18

v.1.14

disable_nscreen 추가

2019.09.20

v.1.15

live jwt 에 play_expt 추가

2019.12.05

v.1.16

scroll_event 추가

개요

기존 Kollus 시스템에서 Media Token은 고객사가 Videogateway로 컨텐츠 재생 요청을 전달할 때 요청 내용을 은닉(암호화)하고, 직접 url에 대한 유효 기간을 설정하기 위해 사용했습니다. 하지만 Media Token을 사용하기 위해서는 Kollus에서 제공하는 모듈을 서버에 직접 설치해야 하고, 모듈이 서버를 지원하지 않는 경우엔 Kollus API를 호출하여 Media Token을 원격으로 생성해 사용해야 하거나, Media Token의 스펙이 변경될 때마다 서버에 모듈을 재 설치해야 하는 등 문제가 많았습니다. 이에 암호학적으로 안전하고 구현이 간단한 JSON Webtoken을 이용하여 Kollus 모듈에 대한 의존성을 줄이고 좀 더 유연하게 스펙 변경에 대응할 수 있도록 합니다.

유의사항

  1. JSON Webtoken(이하 JWT)에 대해선 http://jwt.io 사이트를 참조해주세요.
  2. JWT의 Payload 부분에 다음에 기술된, 먼저 등록된 Claim들을 사용해선 안됩니다. (https://tools.ietf.org/html/rfc7519#section-4) 이 경우 기대했던 대로 동작하지 않을 수 있습니다.
  3. 암호화 알고리즘은 HMAC SHA256 (HS256) 만을 지원합니다

JWT Request

용어

  • 보안 키 (Security Key)
    • 보안 키는 JWT를 signing 하기 위해 Kollus와 고객사만이 공유하는 비밀 키 입니다. 보안 키는 “설정 > 서비스 계정” 페이지에서 확인할 수 있습니다. 이 값은 고객이 희망하면 언제든 변경 가능하며, 변경 즉시 기존에 사용하던 보안 키는 폐기됩니다. 따라서 보안 키는 고객사의 정기점검 시간을 이용하여 변경하는 것을 권장합니다
  • 사용자 키 (Custom Key)
    • 사용자 키는 평문 보안 키를 암호화한 키입니다. JWT를 이용하여 Videogateway에 요청시 JWT와 함께 전달되어야 합니다.

JWT 생성 방법

암호화 알고리즘은 HMAC SHA256 (HS256) 으로 하고, Secret key는 보안 키, Payload에는 아래 Payload Spec에 맞춘 JSON String을 추가하여 JWT를 생성합니다.

생성한 JWT를 이용하여 Videogateway에 요청하기

생성한 JWT와 사용자 키를 다음과 같은 형식의 url로 생성하여 호출합니다.

http://v.kr.kollus.com/s?jwt=생성한 JWT&custom_key=사용자 키

JWT Payload Spec

jwt PayLoad의 형식은 다음과 같은 JSON 문자열입니다.

{
	"cuid": "CLIENT_USER_ID",
	"awtc": “AUDIO_WATERMARKING_CODE”,
            "video_watermarking_code_policy": {
                       "code_kind":"client_user_id",
                       "font_size":7,
                      "font_color":"FFFFFF",
                      "show_time":1,
                      "hide_time":500,
                     "alpha":50,
                     "enable_html5_player": false,
            },
	"expt": EXPIRE_TIME,
	"pc_skin": {
		"skin_path": "http://file.kr.dev.kollus.com/public/custom/skin2.zip",
		"skin_sha1sum": "B2B688123F68BFA7DB4B1F89EC292C0835086D9B"
	},
	"mc": [{
		"mckey": “MEDIA_CONTENT_KEY”,
		"mcpf": “MEDIA_CONTENT_PROFILE_KEY”,
		"tilte": “TITLE”,
		"intr": IS_INTRO,
                   “scroll_event”: SCROLL_EVENT,
		"seek": IS_SEEKABLE,
		"seekable_end": SEEKABLE_END,
		"disable_playrate": DISABLE_PLAYRATE,
                   “disable_nscreen”: DISABLE_NSCREEN,
                   "play_section": {
                              "start_time": PLAY_SECTION_START_TIME,
                              "end_time": PLAY_SECTION_END_TIME
                         }
                         "thumbnail": {
                             "enable": IS_ENABLE,
                             "thread": IS_THREAD,
                             "type": "TYPE"
                         },
                         "subtitle_policy" : {
                             "filter": {
                                 "name": "SUBTITLE_NAME",
                                 "language_code": "SUBTITLE_LANGUAGE_CODE",
                             },
                            "show_by_filter" : false,
                            "is_showable": true,
                         },
                         "drm_policy" : {
                             "kind" : "DRM_KIND",
                             "streaming_type": "hls",
                             "data" : "..."
                         }
	}]
}


Payload 항목

이름

Datatype

필수 여부

내용

Mediatype

cuid
(CLIENT_USER_ID)

String

필수

컨텐츠에 억세스하려는 고객사의 사용자 아이디. 북마크나 NScreen 데이터의 Key로 사용됩니다.

VOD/LIVE

awtc

(AUDIO_WATERMARKING_CODE)

String

선택

(기본값: null)

Kollus 오디오 워터마킹 기능을 이용하려고 할 때에 사용하는 워터마킹 코드. 워터마킹 코드는 API를 호출하여 획득하며, 자세한 내용은 기술 담당자에게 문의 바랍니다.

사용하지 않으면 해당 Entry를 삭제하거나, null로 입력하면 됩니다.

VOD

expt

(EXPIRE_TIME)

Integer

필수

JWT가 유효한 시간. Unix timestamp 형식으로 입력합니다. 고객사 서버와의 시간이 정확하게 일치하지 않을 수도 있으므로, 최대 1분 정도는 유효기간이 지났더라도 접근할 수 있습니다.

VOD/LIVE

pc_skin

(PC_EX_PLAYER_SKIN)

Array

선택

V2 PC Player 스킨을 고객이 지정하기 위한 용도로 사용합니다. 설정할 스킨이 없는 경우는 필드 자체를 생략할 수 있으나, 이 필드를 추가했을때는 반드시 하위 필드인 skin_path, skin_sha1sum 값이 정확히 입력되어야 합니다.

V2 Player

skin_path

String

필수

V2 PC Player 스킨 정보를 담고 있는 압축 파일의 URL

V2 Player

skin_sha1sum

String

필수

V2 PC Player 스킨 정보를 담고 있는 압축 파일에 대한 sha1 checksum 값

V2 Player

mc

Array

필수

재생할 컨텐츠의 재생정보를 담고 있는 Object 타입의 Entry를 배열로 담고 있는 배열입니다.

VOD/LIVE

mckey

(MEDIA_CONTENT_KEY)

String

필수

재생할 컨텐츠의 식별 키. 확장 미디어 컨텐츠 키 형식도 동일하게 사용할 수 있습니다.

VOD/LIVE

mcpf

(MEDIA_CONTENT_PROFILE_KEY)

String

선택


(기본값: null)

재생할 컨텐츠의 식별 키. 확장 미디어 컨텐츠 키 형식도 동일하게 사용할 수 있습니다.

자동 선택하게 두려면 해당 Entry를 삭제하거나, null로 입력하면 됩니다.

VOD

title

(TITLE)

String

선택

(기본값: null)

컨텐츠의 기존 타이틀을 대체하는 문자열입니다. 

VOD/LIVE

intr

(IS_INTRO)

Boolean

선택

(기본값: false)

컨텐츠가 인트로인지 아닌지의 여부를 입력합니다. 인트로에 관한 내용은 하단의 예제를 참조하세요.

인트로가 아닌 정상 컨텐츠인 경우엔 해당 Entry를 삭제하거나, false를 입력하면 됩니다.

VOD

scroll_event

Boolean

(기본값: false)

화면을 scroll event 적용 여부

true일경우 화면의 높이기준으로 video 화면 영역을 맞추고 안보이는 영역은 scroll 가능

false일경우 기존 처럼 가로 기준으로 화면을 맞춘다.

VOD

seek

(IS_SEEKABLE)

Boolean

선택

(기본값: true)

컨텐츠의 seek를 허용할 것인지 아닌지의 여부를 입력합니다. 보통 인트로인 경우는 seek를 허용하지 않습니다. 

seek를 허용하는 경우엔 해당 Entry를 삭제하거나, true를 입력하면 됩니다.

VOD

seekable_end

(SEEKABLE_END)

Integer

선택

(기본값: -1)

seek 허용이 안된 컨텐츠도 시작 부터 입력 값까지의 구간은 seek가 가능하게 됩니다.

VOD

disable_playrate

(DISABLE_PLAYRATE)

Boolean

선택

(기본값: false)

배속컨트롤 사용 여부를 설정합니다.

VOD

disable_nscreen

(DISABLE_NSCREEN)

Boolean

선택

(기본값: false)

nscreen 사용 여부를 설정합니다.

VOD

play_section.start_time

Integer

선택 (기본값: null)

구간반복 시작시간을 설정합니다. (단위: 초)

VOD

play_section.end_time

integer

선택 (기본값: null)

구간반복 종료시간을 설정합니다. (단위: 초)

VOD

thumbnail.enable

Boolean

선택 (기본값: true)

썸네일 활성화 여부를 설정합니다.

해당옵션은 안드로이드만 지원합니다.

안드로이드 공용앱/SDK

thumbnail.thread

Boolean

선택 (기본값: false)

쓰레드 방식 여부를 설정합니다.

해당옵션은 안드로이드만 지원합니다.

안드로이드 공용앱/SDK

thumbnail.type

String

선택 (기본값: null)

썸네일 사이즈를 설정합니다. (big / small)

해당옵션은 안드로이드만 지원합니다.

안드로이드 공용앱/SDK

subtitle_policy.filter.name

String

선택

(기본값: null)

자막 필터를 자막 이름을 사용하도록 합니다. show_by_filter: true 가 되어야 동작합니다.

VOD

subtitle_policy.filter.language_code

String

선택
(기본값: null)

자막 필터를 언어 코드를 사용하도록 합니다.

show_by_filter: true 가 되어야 동작합니다.

VOD

subtitle_policy.show_by_filter

Boolean

선택
(기본값: false)

자막 정책 필터에 맞게 보여주는지 여부를 판단합니다.

VOD

subtitle_policy.is_showable

Boolean

선택

(기본값: true)

자막을 보이게 할것인지를 판단합니다.

VOD

drm_policy.kind

String

선택

(기본값: null)

drm 방식을 정합니다. 현재 가능한 DRM은 "inka" 입니다. (현재 "inka" 를 사용하면 third_party_info 에 "cid" 가 "skb_kollus" 설정을 해야 합니다.)

VOD

drm_policy.streaming_type

String

선택

(기본값: null)

hls, dash 으로 스트리밍을 제한합니다. "inka"를 했다면 스트리밍 타입을 정해야 합니다.

VOD

drm_policy.data

Object

선택
(기본값: null)

DRM 인증 데이타를 오브젝트(json) 방식으로 삽입합니다.
ex)
{
  "license_url": "https://tokyo.pallycon.com/ri/licenseManager.do",

  "certificate_url": "https://license.pallycon.com/ri/fpsKeyManager.do?siteId=XXXX",

  "custom_header": {

    "key": "pallycon-customdata-v2",

    "value": "eyJ0aW1lc3RhbXAiOiI5OTk5LTEyLTMxVDIzOjU5....cl9pZCI6bnVsbCwiY2lkIjoidGVzdCJ9"

  }

}


video_watermarking_code_policy.code_kind

String

선택

"client_user_id"를 제외한  다른 String 일시 그대로 출력


video_watermarking_code_policy.alpha

Integer

선택(기본 값: 200)

비디오워터마킹코드의 alpha 값을 정의 합니다. (16진수 0~255)


video_watermarking_code_policy.font_size

Integer

선택(기본값: 7)

비디오워터마킹코드의 font-size 값을 정의 합니다. (단위: px)


video_watermarking_code_policy.font_color

String

선택(기본값; 'FFFFFF')

비디오워터마킹코드의 font-color 값을 정의 합니다.


video_watermarking_code_policy.show_time

Integer

선택(기본값;1)

비디오워터마킹코드의 보여지는 시간을 정의 합니다. (단위: 초)


video_watermarking_code_policy.hide_time

Integer

선택(기본값;60)

비디오워터마킹코드의 보여진후 안보여지는 시간을 정의 합니다. (단위: 초)


video_watermarking_code_policy.enable_html5_player

Boolean

선택(기본 값:false)

비디오워터마킹코드의 HTML5 Player 의 사용여부를 확정합니다.


예제

일반 컨텐츠 재생을 위한 JWT Payload

catenoid 라는 아이디를 가진 사용자가 미디어 컨텐츠 키 vnCVPVyV 를 재생하는 경우

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “vnCVPVyV“
	}]
}

인트로가 포함된 컨텐츠 재생을 위한 JWT Payload

catenoid 라는 아이디를 가진 사용자가 인트로로 미디어 컨텐츠 키 gDV2B1ZG를 seek 불가능한 상태로, 본 컨텐츠로는 vnCVPVyV 를  재생하는 경우

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “gDV2B1ZG“,
		"intr": true,
		"seek": false,
	},{
		"mckey": “vnCVPVyV“
	}]
}

스킵 안되는 컨텐츠 재생시 시작부분 일부만 스킵 허용하기 위한 JWT Payload

catenoid 라는 아이디를 가진 사용자가 인트로로 미디어 컨텐츠 키 gDV2B1ZG를 seek 불가능한 상태로 재생하지만, 시작 부터 30초 구간은 스킵을 허용하는 경우

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “gDV2B1ZG“,
		"intr": true,
		"seek": false,
		"seekable_end": 30,
	}]
}

샘플 코드

 Json Web Tokens – Java

 Json Web Tokens – ruby

 Json Web Tokens – php

Download


샘플 코드

 Download – jsp

 Download – php

 Download – dotnet