Play 콜백

Kollus 전용플레이어에서 재생을 할때 고객사에서 정의한 URL을 호출(Callback)하는 기능을 정의한 문서입니다.

Expire option

설정 항목의 data-type이나 값이 범위를 벗어나는 경우 컨텐츠 이용에 문제가 발생할 수 있으며, 잘못된 설정 값에 대한 사용 제한을 회수하는 방법은 존재하지 않습니다.

• Expire date : 컨텐츠 만료 시간

  • data-type : integer, unixtime stamp

  • 컨텐츠 재생이 만료될 시간

    • 컨텐츠 재생이 만료될 시간

      ex) 2014. 3. 3. 5시 45분 30초 GMT → 1393825531

    • 0 : unlimited (무제한)

    • 최대값 : 2029년 12월 31일 23시 59분 59초 (1893455999)

Play callback

Play callback(이하 콜백)을 사용하기 위해서는 CMS의 관리 화면에서 관리자 이상의 권한을 소유한 로그인 계정으로 채널 속성에 Play 콜백 항목에 고객사에서 콜백을 응답받기 위해 정의된 URL을 등록하셔야 합니다.

Play 콜백이 정의되지 않은 채널은 콜백의 응답과 관계없이 재생을 진행합니다. 콜백이 정의된 채널을 통해 서비스되는 콘텐츠는 콜백에 대한 응답을 확인 후 재생하기 때문에 고객사에서 정의한 콜백 URL은 항상 응답상태를 유지하셔야 원활한 서비스를 받으실 수 있습니다.

주의:

1. 고객사의 회원 아이디를 포함한 미디어 토큰(Media token)을 생성하여 요청된 경우에 Play 콜백이 호출됩니다. (미디어 토큰 생성은 별도 문서를 참고해 주십시오.)

2. Play 콜백 URL이 응답하지 않으면 재생 되지 않습니다.

3. Play 콜백은 다운로드된 콘텐츠에 대한 DRM 콜백과 다르게 동작합니다. 다운로드된 콘텐츠는 Play 콜백이 아닌 DRM 콜백으로 동작하게 됩니다. 필요에 따라 Play 콜백과 DRM 콜백 URL을 동일하게 등록하면 다운로드와 스트리밍시에 재생에 대한 응답을 동일하게 받으실 수 있습니다.

Callback flow

1. 채널에 Play 콜백 URL을 설정합니다.

   • ex> http://www.foo.com/auth.php 가 고객사 Play 콜백 서버인 경우

2. JSON 데이터를 생성 후 JWT로 인코딩 한다.

3. Kollus mobile player가 http://www.foo.com/auth.php 에 다음의 정보를 POST 전송 합니다.

   • kind : 1, 3

   • client_user_id : 고객사 회원 아이디

     • Media token 생성시 포함된 아이디입니다.

   • player_id : 고객사 회원이 가지고 있는 단말 아이디

   • device_name : 고객사 회원이 가지고 있는 단말명

   • media_content_key : 현재 재생하려는 콘텐츠 key 입니다.

     • 채널에 등록된 컨텐츠에 부여된 고유 키입니다.

     • 업로드된 컨텐츠를 여러채널에 등록하면 media_content_key는 모두 다르게 생성됩니다.

4. 고객사 Play 콜백 서버는 전달 받은 위 정보를 바탕으로 다음의 json 포멧의 data를 JWT의 payload ​에 ​추가하여 Encoding ​하고 ​헤더에 ​지정된 “시용자키(X-KOLLUS-USERKEY)"를 함께 ​전송합니다.

   (고객사가 인증 정보를 플레이어로 전달할 때 모든 데이터의 자료형은 반드시 기술된대로 integer 형이여야만 합니다.)

Response JSON spec.

Json Tag	Description
expiration_date	unixtime stamp (만료될 시간의 unixtime stamp) 최대값 : 2029년 12월 31일 23시 59분 59초 (1893455999)
result	반환 결과가 정상인 경우 1, 비정상인 경우 0을 반환하도록 합니다.
content_expired	DRM 컨텐츠를 강제로 expire 시킵니다.

Callback Kind

Play 콜백이 호출되는 상황은 아래 3가지 경우입니다.

콘텐츠의 Expire 정보를 요청하는 경우 (kind:1)

Request

구분	Description
POST	Http POST로 요청합니다. (parameter가 아닙니다.)
kind	1
client_user_id	고객사 사용자 ID, media_token 생성시 사용된 client_user_id와 동일합니다.
player_id	고객사 사용자가 가지고 있는 단말의 아이디
hardware_id	단말의 hardware 아이디(PC, 입력값이 있으면)
device_name	고객사 사용자가 가지고 있는 단말의 모델명
media_content_key	Kollus 컨텐츠 unique key
uservalues	JSON format (VideoGateway 호출시 사용된 uservalue0~9)

• uservalues sample

  • uservalues={"uservalue0":"강의코드01","uservalue1":"상품코드02","uservalue9":" 생성코드03"}

  • VideoGateway(http://v.kr.kollus.com )호출시 사용된 uservalue0~9 정보를 함께 전달 받습니다.

Response

카테고리	구분	필수	Description
Data	(int) expiration_date	O	만료될 시간의 unixtime stamp 최대값 : 2029년 12월 31일 23시 59분 59초 (1893455999)
	(int) result	O	0 (비정상), 1 (정상)
	(string) message		result == 0 (비정상)의 경우 message를 추가하면 지정 한 메시지가 표출됩니다. PC 플레이의 경우 재생 URL에 loadcheck=0 파라미터를 추가 해 주셔야 지정 한 메시지가 표출됩니다. EX. http://v.kr.kollus.com/{미디어 컨텐츠 키}?loadcheck=0
	(int) vmcheck		0 (사용안함), 1 (사용함, default) virtural machine 체크 여부, PC(v3)용에서만 사용 가능
	(int) disable_tvout		0 (tvout 차단 안함), 1 (tvout 차단) 이 항목이 없으면 채널에 있는 disable_tvout정책이 적용됩니다.
	(int) expiration_playtime		이 항목이 없거나 0이면 재생 시간을 사용하지 않고 0보다 크면 해당 값의 초만큼만 재생 후 종료합니다.
	(int) cpcheck		0 (사용안함), 1 (사용함, default) 캡쳐프로그램 체크 여부, PC용에서만 사용 가능
exp	(int)		사용 가능 시간 unixtime stamp(옵션)

Example

{
    “data” : {
        "expiration_date": 1402444800,
        "vmcheck": 1,
        "disable_tvout": 1,
        "expiration_playtime": 1800,
        "result": 1
    },
    “exp” : 1477558242
}

콘텐츠를 재생하는 경우 (kind:3)

주의) 콘텐츠 재생을 위해 반드시 응답해야 합니다. Play 콜백에 대한 응답을 확인 후에 재생을 시작합니다.

Request

구분	Description
POST	Http POST로 요청합니다. (parameter가 아닙니다.)
kind	3
client_user_id	고객사 사용자 ID, media_token 생성시 사용된 client_user_id와 동일합니다.
player_id	고객사 사용자가 가지고 있는 단말의 아이디
device_name	고객사 사용자가 가지고 있는 단말의 모델명
media_content_key	Kollus 컨텐츠 unique key
uservalues	JSON format (VideoGateway 호출시 사용된 uservalue0~9)

Response

카테고리	구분	필수	Description
data	(int) content_expired		0 (재생가능), 1 (재생 제한) 재생을 차단합니다. DRM 콜백과 동일한 스펙 유지를 위해 동일한 항목으로 유지됩니다.
	(int) result	O	0 (비정상), 1 (정상) 0 인 경우 재생되지 않습니다. 이때 conent_expired가 1이어도 expire가 수행되지 않습니다.
	(string) message		result == 0 (비정상)의 경우나 content_expired이 1(재생 제한)의 경우 message를 추가하면 지정 한 메시지가 표출됩니다. PC 플레이의 경우 재생 URL에 loadcheck=0 파라미터를 추가 해 주셔야 지정 한 메시지가 표출됩니다. EX. http://v.kr.kollus.com/{미디어 컨텐츠 키}?loadcheck=0
exp	(int) expiration_date		사용 가능 시간 unixtime stamp(옵션) 최대값 : 2029년 12월 31일 23시 59분 59초 (1893455999)

Example

{
    “data” : {
        "content_expired": 1,
        "result": 1
    },
    "exp" : 1477558242
}

Sample

• Play callback url

  • http://www.foo.com/auth.php

• 컨텐츠 만료 시간 : 2014년 6월 10일 자정 종료

  • DATE (M/D/Y @ h : m : s): 6 / 10 / 2014 @ 24:0:0 UTC

  • Unix time stamp : 1402444800

  • http://www.epochconverter.com 를 이용해 1402444800 값을 변경해 볼 수 있습니다. GMT가 아닌 UTC입니다.

kind1 : request expire option

request

• URL : http://www.foo.com/auth.php

• post data

  • kind=1

  • client_user_id=guest1

  • media_content_key=VXBW1VdY

  • uservalues={"uservalue0":"강의코드01","uservalue1":"상품코드02","uservalue9":" 생성코드03"}

response

{
    “data” : {
        "expiration_date": 1402444800,
        "result": 1
    },
    "exp" : 1477558242
}

kind3 : play content (expire content)

request

• URL : http://www.foo.com/auth.php

• post data

  • kind=3

  • client_user_id=guest1

  • media_content_key=VXBW1VdY

  • uservalues={"uservalue0":"강의코드01","uservalue1":"상품코드02","uservalue9":" 생성코드03"}

response

{
    “data” : {
        "content_expired": 1,
        "result": 1
    },
    "exp" : 1477558242
}

Code sample

https://github.com/kollus-service/kollus-playcallback-dotnet

https://github.com/kollus-service/kollus-samples-jsp

https://github.com/kollus-service/kollus-drm-callback-php

https://github.com/kollus-service/kollus-samples-php