Skip to main content

플레이 콜백

Kollus VOD는 콘텐츠 보안 및 권한 관리를 위해 플레이어 재생 시작 시점에 고객사 서버의 승인을 받는 플레이 콜백(Play Callback) 기능을 지원합니다. 시청자가 재생 버튼을 클릭할 때 실시간으로 호출되며, 고객사 서버로부터 유효한 승인 응답을 수신한 경우에만 콘텐츠 재생이 활성화됩니다.

유의 사항​

  • 채널별 제어 정책: 콜백 URL이 설정된 채널은 모든 재생 요청에 대해 서버 승인이 필수입니다. (미설정 시 승인 없이 즉시 재생)
  • 식별자 필수 포함: 재생용 JWT 생성 시 client_user_id 파라미터를 반드시 포함합니다.
  • 오프라인 재생 제한: 디바이스에 저장된 콘텐츠의 재생 제어는 DRM 다운로드 콜백에서 처리합니다.

콜백 설정 방법​

콜백 URL은 Kollus VOD 콘솔에서 설정할 수 있습니다.

콜백 흐름​

주의
  • 응답 규격: 콜백 서버의 응답 데이터는 반드시 JWT(JSON Web Token) 형식으로 반환되어야 합니다.
  • 헤더 인증: HTTP 응답 헤더에 X-KOLLUS-USERKEY: {CUSTOM_KEY}를 반드시 포함해야 합니다.
  • 데이터 타입: JSON 내 모든 정수형 필드(expiration_date, result, content_expired 등)는 integer 타입으로 전달해야 합니다. ("1"과 같이 string 타입으로 전송 시 처리 실패)

콜백 유형​

플레이 콜백은 호출 시점과 목적에 따라 두 가지 유형으로 구분됩니다.

  • kind1 (재생 만료 설정): 재생 시작 전, 시청자의 재생 가능 기한을 동적으로 할당합니다.
  • kind3 (최종 재생 승인): 플레이어 준비 완료 직후, 현재 시점의 재생 권한을 최종 확인합니다.

요청 규격​

전송 방식​

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Data Format: FormData

요청 파라미터​

파라미터타입필수 여부설명
kindinteger◯플레이 콜백 유형
  • 1: 재생 만료 설정
  • 3: 최종 재생 승인
client_user_idstring◯시청자 ID (JWT 생성 시 입력한 client_user_id)
player_idstring◯Kollus 플레이어 고유 ID
hardware_idstring-하드웨어 ID (Windows 환경 등 식별 가능한 값이 존재하는 경우 제공)
device_namestring-디바이스 모델명
media_content_keystring◯미디어 콘텐츠 키
localtimeinteger-디바이스 기준 UTC 시간
uservaluesJSON string-커스텀 변수 (uservalue0~uservalue99)

uservalues 예시​

{
  "uservalue0": "class_code_01",
  "uservalue1": "product_code_02",
  "uservalue99": "custom_code_03"
}

응답 규격​

kind1 응답 필드​

kind1 응답은 시청자의 권한을 정의하고, 보안 옵션(캡처 차단, 가상머신 환경 탐지 등)을 동적으로 제어하는 데 사용됩니다.

data 항목​

주의

만료 일시(expiration_date)는 Kollus 시스템에 기록된 후 수정 또는 회수가 불가능합니다. 반드시 정확한 Unix Timestamp 값을 할당하세요.

필드타입필수 여부설명
expiration_dateinteger◯재생 만료 일시 (Unix Timestamp)
  • 최댓값: 2145916799 (2037-12-31 23:59:59)
resultinteger◯승인 결과
  • 0: 비정상 (재생 차단)
  • 1: 정상 (재생 허용)
messagestring-재생 차단(result: 0) 시 플레이어 화면에 노출할 안내 메시지
  • PC는 재생 URL에 loadcheck=0 파라미터를 포함해야 메시지가 노출됩니다.
    • 예: http://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?loadcheck=0
vmcheckinteger-(HTML5 Player for PC 전용) 가상머신(VM) 환경 재생 허용 여부
  • 0: 허용
  • 1: 가상머신 환경 탐지 및 차단 (기본값)
disable_tvoutinteger-외부 디스플레이 출력 허용 여부 (채널 기본 정책보다 우선 적용)
  • 0: 허용 (App Player for iOS 사용 시 캡처 차단 기능이 비활성화될 수 있음)
  • 1: 차단
expiration_playtimeinteger-재생 제한 시간 (sec)
  • 0 또는 null: 제한 없음
cpcheckinteger-캡처 프로그램 감지 기능 활성화 여부 (PC)
  • 0: 비활성화
  • 1: 활성화 (기본값)

exp 항목​

필드타입필수 여부설명
expinteger-JWT 만료 일시 (Unix Timestamp)

kind1 응답 예시​

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

kind3 응답 필드​

kind3 응답은 재생 직전 사용자의 현재 권한 상태를 최종 확인하는 용도로 사용됩니다.

data 항목​

필드타입필수 여부설명
content_expiredinteger-재생 만료 여부
  • 0: 재생 가능
  • 1: 재생 차단 (만료)
resultinteger◯승인 결과 (result 값이 content_expired 설정보다 우선 적용됩니다.)
  • 0: 비정상 (재생 차단)
  • 1: 정상 (재생 허용)
messagestring-재생 차단(result: 0 또는 content_expired: 1) 시 플레이어에 노출할 안내 메시지
  • PC는 재생 URL에 loadcheck=0 파라미터를 포함해야 메시지가 노출됩니다.
    • 예: http://v.kr.kollus.com/{MEDIA_CONTENT_KEY}?loadcheck=0

exp 항목​

필드타입필수 여부설명
expinteger-JWT 만료 일시 (Unix Timestamp)

kind3 응답 예시​

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