LMS 콜백

Kollus VOD는 콘텐츠의 업로드부터 재생까지 전체 워크플로우에 대해 콜백(Callback) 연동을 지원합니다.
고객사는 콜백 기능을 사용하여 주요 이벤트 발생 시 지정된 URL로 실시간 HTTP 알림을 수신할 수 있으며, 이를 통해 외부 시스템과의 데이터를 동기화하거나 업무 프로세스를 자동화할 수 있습니다.

LMS 콜백(LMS Callback)은 시청자의 재생 데이터를 실시간으로 수집하여 학습 관리 시스템(LMS) 서버로 전송하는 기능입니다. 이를 통해 학습 진도(Progress) 체크, 시청 패턴 분석, 마지막 시청 지점 저장 등 고도화된 교육 관리 로직을 구현할 수 있습니다.

주요 특징

비동기 전송(Asychronous): 플레이어는 서버의 응답을 기다리지 않고 데이터를 전송하여 재생 흐름을 방해하지 않습니다.
자동 재전송 정책(Retry Policy): 고객사 서버 또는 네트워크 장애로 전송에 실패할 경우, 데이터를 클라이언트에 임시 보관한 후 통신이 복구되는 시점에 순차적으로 재전송합니다.

제공 정보

LMS 콜백은 콘텐츠 재생 중 발생하는 데이터를 수집하여 전송합니다. 이를 통해 사용자별 상세 학습 이력을 재구성할 수 있습니다.

재생 종료 시각
구간별(블록 단위) 재생 데이터
사용자 정보
콘텐츠 정보
클라이언트(PC) 환경 정보

콜백 설정 방법

콜백 URL은 Kollus VOD 콘솔에서 설정할 수 있습니다.
상세한 설정 위치는 콜백 설정 - LMS 콜백 문서를 참고하세요.

각 설정 항목에 대한 상세 설명은 아래 콜백 설정 정보 섹션을 참고하세요.

콜백 흐름

LMS 데이터가 전송되는 전체 프로세스는 다음과 같습니다.

콜백 정보 등록
- Kollus VOD 콘솔에서 채널별로 콜백 URL과 수집 항목(블록 수, 전송 주기 등)을 설정합니다.
재생 요청
- 최종 사용자(End User)가 콘텐츠 재생을 요청하면, 고객사 서버는 VideoGateway를 호출합니다.
설정 전달
- VideoGateway는 플레이어에 재생 정보, 콜백 설정 값, 고객사 정의 값(uservalue0~uservalue99)을 함께 전달합니다.
LMS 콜백 전송
- 플레이어는 시청 데이터를 수집하여 고객사 서버의 콜백 URL로 전송합니다.
- 전송 시점: 지정된 주기(period)가 되었을 때, 시청자가 영상을 일시정지했을 때, 또는 시청을 종료했을 때 발생합니다.
- 재전송 정책: 네트워크 장애로 전송이 실패할 경우, 데이터를 임시 보관하며, 연결이 복구되는 즉시 자동으로 재전송을 수행합니다.

주의 사항

재생 블록(Block) 수 제한

설정 범위: 블록 수는 1에서 100 사이의 정수로 설정해야 합니다.
예외 처리
- 입력값이 100을 초과하면 시스템이 자동으로 100으로 고정합니다.
- 입력값이 0 이하이면 자동으로 1로 처리됩니다.
권장 사항
- 블록 수는 콘텐츠 전체 길이보다 작거나 같게 설정하는 것을 권장합니다.
- 예: 30초 길이의 영상에서 블록 수를 100으로 설정하더라도, 실제로는 1초당 1개씩 계산되어 총 30개의 블록 데이터만 생성됩니다.

콜백 호출 시점

정기 호출: 설정된 전송 주기(period)마다 일정한 간격으로 호출됩니다.
이벤트 호출: 주기에 상관없이 시청자가 일시정지하거나 재생을 종료할 때 즉시 호출됩니다.
데이터 식별: 동일한 시청자의 연속적인 콜백 데이터는 client_user_id와 start_at(세션 시작 시각) 값을 기준으로 결합하여 최종 상태를 판별할 수 있습니다.

콜백 설정 정보

전송 방식

HTTP Method: POST
Content-Type: application/x-www-form-urlencoded
Data Format: 모든 데이터는 Form Data 형식으로 전달됩니다.

설정 파라미터

Kollus VOD 콘솔에서 설정하는 기본 LMS 정책 파라미터입니다.

파라미터	타입	설명
블록 수(`block_count`)	integer	재생 구간을 분할하는 블록의 수 예: 300초 영상의 블록 수를 10으로 설정하면, 각 블록의 길이는 30초가 됩니다.
전송 주기(`period`)	integer	정보 전송 주기(단위: 초) 지정한 주기 및 플레이어 일시정지 및 종료 시 콜백이 호출됩니다.
블록 정보 포함(`enable_blocks`)	integer	`block_info` 내 블록 정보 포함 여부 `0`: 미포함 `1`: 포함
세션 정보 포함(`enable_sessions`)	integer	`block_info` 내 세션 정보 포함 여부 `0`: 미포함 `1`: 포함
콜백 URL(`callback_url`)	string	LMS 콜백 데이터를 수신할 고객사 서버 URL

플러그인 옵션

LMS 콜백 요청 시 함께 전달될 세부 항목을 설정합니다. 선택된 옵션은 콜백 요청의 파라미터로 포함됩니다.

파라미터	타입	설명
`json_data`	JSON	모든 재생 정보를 포함한 JSON 객체 (`user_info`, `content_info`, `block_info` 포함)
`client_user_id`	string	시청자 ID(JWT 생성 시 입력한 `client_user_id`와 동일)
`start_at`	integer	전송 요청 시각(VideoGateway 호출 시점의 Unix Timestamp) 다운로드된 콘텐츠의 경우, 재생 시 기기의 Unix Timestamp
`play_time`	integer	누적 재생 시간(배속 및 구간 반복 포함, 단위: 초) 예: 2배속으로 10초 재생 → 누적 재생 시간 20초
`playtime_percent`	integer	콘텐츠 전체 길이(`duration`) 대비 재생 비율(단위: %, 소수점 이하 절삭) 예: 콘텐츠를 2회 재생한 경우 → 200
`last_play_at`	integer	마지막 재생 위치(단위: 초)
`duration`	integer	콘텐츠 전체 길이(단위: 초)
`media_content_key`	string	미디어 콘텐츠 키
`encoding_profile_key`	string	인코딩 프로파일 키
`block_cnt`	integer	설정된 블록 수
`play_block_json`	JSON	블록 전체 재생 정보(`json_data.block_info`와 동일)
`host_name`	string	콘텐츠 링크 요청 도메인 예: `catenoid.video.kr.kollus.com`
`player_id`	string	Kollus 플레이어의 고유 ID(플레이어 설치 시 생성)
`hash`	string	데이터 변조 방지용 Hash 값(HTML5 Player 미지원)

Hash(무결성 검증) 생성 규칙

데이터 변조 방지를 위해 다음 단계로 Hash 값을 생성하여 검증하세요.

hash_1 = md5(post_data)
hash_2 = md5(hash_1+service_account)
생성된 hash_2 값을 hash 파라미터로 전송합니다.

ℹ️참고

+는 산술 더하기가 아닌 문자열 결합(String Concatenation)을 의미합니다.
아래 Hash 생성 예시와 같이 + 기호 자체를 문자열에 포함해야 합니다.

Hash 생성 예시

hash_1 = "abc123"
service_account = "kollus-test"

hash_2 = md5("abc123+kollus-test")

LMS 콜백 데이터 포맷

VideoGateway가 플레이어에 전달하는 콜백 설정의 전체 포맷입니다.

[block_count]:[period]:[enable_blocks]:[enable_sessions]:[callback_url]?{플러그인 옵션}

LMS 콜백 데이터 예시

예시 1

10:30:1:0:https://domain.com/check.asp?id={CLIENT_USER_ID}&start={START_AT}&uservalue0={USERVALUE0}

예시 2

20:180:0:1:https://another_domain.com/another_check.php?id={CLIENT_USER_ID}&start={START_AT}&json_data={JSON_DATA}&uservalue0={USERVALUE0}

전송 데이터(JSON_DATA) 구조

JSON_DATA는 재생 정보 전체를 포함합니다.

user_info

필드	타입	설명
`content_provider_key`	string	서비스 계정 키
`client_user_id`	string	시청자 ID(JWT 생성 시 입력한 `client_user_id`와 동일)
`player_id`	string	기기 고유 식별자
`hardware_id`	string	기기 시리얼 넘버
`host_name`	string	콘텐츠 링크를 요청한 도메인
`device`	string	기기 모델명

content_info

필드	타입	설명
`duration`	integer	콘텐츠 전체 길이(단위: 초)
`encoding_profile`	string	인코딩 프로파일 키
`media_content_key`	string	미디어 콘텐츠 키
`channel_key`	string	채널 키
`real_playtime`	integer	누적 재생 시간(배속 포함, 구간 반복 미포함, 단위: 초) 예: 2배속으로 10초 재생 → 실제 재생 시간 20초
`playtime`	integer	누적 재생 시간(배속 및 구간 반복 포함, 단위: 초) 예: 2배속으로 10초 재생 → 실제 재생 시간 20초
`playtime_percent`	integer	콘텐츠 전체 길이(`duration`) 대비 재생 비율(단위: %, 소수점 이하 절삭) 예: 콘텐츠를 2회 재생한 경우 → 200
`start_at`	integer	전송 요청 시각(VideoGateway 호출 시점의 Unix Timestamp) 다운로드된 콘텐츠의 경우, 재생 시 기기의 Unix Timestamp
`last_play_at`	integer	마지막 재생 위치(단위: 초)
`runtime`	integer	누적 재생 시간(일시정시 포함, 단위: 초)
`showtime`	integer	누적 재생 시간(단위: 초)
`serial`	integer	LMS 발송 순서(0부터 시작)

block_info

필드	타입	설명
`block_count`	integer	재생 구간을 분할하는 블록의 수 예: 300초 영상의 블록 수를 10으로 설정하면, 각 블록의 길이는 30초가 됩니다.
`blocks`	object	블록별 재생 데이터(마일스톤)
`sessions`	array	상세 재생 세션 이력(이전에 전송된 세션 데이터를 포함한 누적 데이터 배열)

block_info.blocks

각 블록 인덱스({n})를 기준으로 상세 데이터를 제공합니다. 블록 인덱스는 0부터 시작하며, block_count 수만큼 반복됩니다.

필드 패턴	타입	설명	예시
`b{n}`	string	블록 재생 여부 `0`: 재생하지 않음 `1`: 해당 블록 재생	`"b0": "1", "b1": "0"`
`t{n}`	string	블록 재생 시간(단위: 초)	`"t0": "1", "t1": "0"`
`p{n}`	string	블록 재생 비율(단위: %) 예: 콘텐츠를 2회 재생한 경우 → 200	`"p0": "100", "p1": "0"`

예시

b0=1, t0=1, p0=100 → 0번 블록이 재생되었으며, 1초간 재생되었고, 100% 재생됨
b1=0, t1=0, p1=0 → 1번 블록은 재생되지 않음

ℹ️참고

플레이어의 배속 기능을 사용해 재생한 경우, 블록 재생 시간(t{n})은 배속을 반영하여 계산됩니다.
예: 3초 길이의 블록을 2회 재생한 경우, 해당 블록의 재생 시간(t{n})은 6초로 기록됩니다.

block_info.sessions

필드	타입	설명	예시
`block`	integer	블록 인덱스(0부터 시작)	`0`
`start_time`	integer	해당 블록 재생 시작 시각(Unix Timestamp → localtime)	`1761531042`
`play_time`	integer	해당 블록 재생 시간(단위: 초)	`1`

예시

0번 블록을, 1761531042 시각에 재생 시작하여, 1초 동안 재생한 경우

[
    {
        "block": 0, 
        "start_time": 1761531042, 
        "play_time": 1
    }
]

player_status

필드	타입	설명
`playback_rate`	integer	재생속도(배속)
`volume_level`	integer	음량(0~100)
`play_status`	string	재생 상태(Kollus 전용 플레이어에서만 사용 가능) `play`: 재생 중 `pause`: 일시정지 `stop`: 종료

uservalues

필드	타입	설명
`{uservalue0~9}`	string	사용자 정의 변수(`uservalue0`~`uservalue9`)

ℹ️참고

모든 uservalue 항목의 합계 크기는 1 KB 이하여야 합니다.
영문 및 숫자를 제외한 모든 문자(한글, 한자, 일본어, 특수문자 등)는 반드시 UTF-8 URL 인코딩하여 전달해야 합니다.

재생 시간 용어 정의

각 지표의 계산 방식이 다르므로 아래 표를 참고하여 시스템을 구현하십시오.

구분	설명	예시
`play_time`	배속 및 구간 반복 포함 재생 시간	2배속 × 10초 + 구간 반복 2배속 × 10초 = 40초
`real_playtime`	배속 포함, 구간 반복 미포함 재생 시간	2배속 × 10초 = 20초
`runtime`	일시정지 포함 재생 시간	10초 + 구간 반복 10초 + 10초 일시정지 = 30초
`showtime`	재생 시간	10초 + 구간 반복 10초 = 20초

주요 특징​

제공 정보​

콜백 설정 방법​

콜백 흐름​

주의 사항​

재생 블록(Block) 수 제한​

콜백 호출 시점​

콜백 설정 정보​

전송 방식​

설정 파라미터​

플러그인 옵션​

Hash(무결성 검증) 생성 규칙​

Hash 생성 예시​

LMS 콜백 데이터 포맷​

LMS 콜백 데이터 예시​

예시 1​

예시 2​

전송 데이터(JSON_DATA) 구조​

user_info​

content_info​

block_info​

block_info.blocks​

예시​

block_info.sessions​

예시​

player_status​

uservalues​

재생 시간 용어 정의​

주요 특징

제공 정보

콜백 설정 방법

콜백 흐름

주의 사항

재생 블록(Block) 수 제한

콜백 호출 시점

콜백 설정 정보

전송 방식

설정 파라미터

플러그인 옵션

Hash(무결성 검증) 생성 규칙

Hash 생성 예시

LMS 콜백 데이터 포맷

LMS 콜백 데이터 예시

예시 1

예시 2

전송 데이터(JSON_DATA) 구조

user_info

content_info

block_info

block_info.blocks

예시

block_info.sessions

예시

player_status

uservalues

재생 시간 용어 정의