본문으로 건너뛰기

LMS 콜백

Kollus VOD는 콘텐츠 재생 중 발생하는 시청 데이터를 실시간으로 수집하여 고객사의 학습 관리 시스템(LMS) 서버로 전송하는 기능을 지원합니다. 이를 통해 수강 완료 여부 판별, 시청 패턴 분석, 마지막 시청 지점 저장 등 고도화된 교육 관리 로직을 구현할 수 있습니다.

주요 특징​

  • 비동기 전송: 플레이어는 서버 응답 대기 없이 데이터를 전송하여 재생 흐름을 방해하지 않습니다.
  • 자동 재전송 정책: 고객사 서버 또는 네트워크 장애 발생 시 클라이언트에 데이터를 임시 보관하며, 통신이 복구되는 시점에 순차적으로 재전송합니다.
  • 개인정보 보호: LMS 콜백 데이터에는 Mac Address, IP Address 등 민감 정보가 포함되지 않습니다.

콜백 설정 방법​

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

콜백 흐름​

LMS 데이터 수집부터 고객사 서버 전송까지의 전체 프로세스입니다.

  1. 콜백 설정: Kollus VOD 콘솔에서 채널별 콜백 URL 및 수집 규격을 정의합니다.
  2. 재생 요청: 시청자가 콘텐츠를 클릭하면 고객사 서버는 비디오 게이트웨이를 호출합니다.
  3. 설정 전달: 비디오 게이트웨이가 플레이어에 재생 정보, 콜백 정책, 커스텀 변수(uservalue0~uservalue99)을 전달합니다.
  4. 실시간 데이터 전송: 플레이어가 시청 데이터를 수집하여 고객사 엔드포인트로 전송합니다.

콜백 호출 정책​

LMS 서버는 수신된 파라미터를 통해 시청자의 학습 이력을 재구성해야 하므로 아래 전송 정책을 준수하여 로직을 설계하세요.

  • 정기 호출: 설정된 전송 주기(period)마다 데이터를 전달합니다.
  • 이벤트 호출: 주기에 상관없이 일시정지 또는 재생 종료 시 즉시 데이터를 전달합니다.
  • 재전송 정책: 네트워크 장애 발생 시 클라이언트에 데이터를 임시 보관하며, 통신 복구 즉시 재전송합니다.

동일 세션 데이터 식별​

전송 주기 및 이벤트에 의해 동일 사용자의 콜백 데이터가 여러 번 수신될 수 있습니다. 시스템은 client_user_id(시청자 ID)와 start_at(세션 시작 시각) 값을 결합하여 단일 재생 세션의 마지막 정보를 판별하고 데이터를 업데이트해야 합니다.

  • 판별 로직: client_user_id와 start_at이 일치하는 레코드들을 그룹화한 뒤, 가장 최근에 수신된 데이터를 최종 시청 이력으로 확정합니다.

데이터 산출 규격​

LMS 데이터의 핵심인 재생 진행률(진도율)과 재생 시간 측정 기준입니다.

재생 블록(Block)​

블록은 전체 영상을 균등하게 나눈 논리적 단위입니다. 플레이어는 각 블록의 시청 여부를 개별적으로 기록하여 재생 진행률(진도율)을 산출합니다.

항목상세 규격비고
설정 범위1~100 사이 정수100 초과 입력 시 100으로 자동 고정
최소 단위1 (전체 단일 블록)0 이하 입력 시 1로 처리
권장 설정콘텐츠 길이 이하로 설정초당 1블록을 초과하여 생성되지 않음
  • 예시 1: 300초 영상의 블록 수를 10으로 설정하면, 각 블록의 길이는 30초가 됩니다.
  • 예시 2: 30초 영상의 블록 수를 100으로 설정하더라도, 실제로는 1초당 1개씩 계산되어 총 30개의 블록 데이터만 생성 및 전송됩니다.

재생 시간 용어 정의​

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

용어배속구간 반복일시정지예: 0~10초 재생 구간, 2배속, 1회 반복, 5초 일시정지
play_time◯◯×(10초 ÷ 2배속) + (10초 반복 ÷ 2배속) = 10초
real_playtime◯××(10초 ÷ 2배속) = 5초
runtime×◯◯10초 + 10초 반복 + 5초 일시정지 = 25초
showtime×◯×10초 + 10초 반복 = 20초

콜백 설정 정보​

전송 방식​

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

설정 파라미터​

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

파라미터타입설명
블록 수 (block_count)integer영상을 분할하는 논리적 구간 수
전송 주기 (period)integer서버로 데이터를 전송할 시간 간격 (sec)
블록 정보 포함 (enable_blocks)integerblock_info 내 블록 정보 포함 여부
  • 0: 미포함
  • 1: 포함
세션 정보 포함 (enable_sessions)integerblock_info 내 세션 정보 포함 여부
  • 0: 미포함
  • 1: 포함
콜백 URL (callback_url)stringLMS 데이터를 수신할 고객사 측 서버 주소

플러그인 옵션​

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

파라미터타입설명
json_dataJSON모든 재생 정보를 포함한 JSON 객체
(user_info, content_info, block_info 포함)
client_user_idstring시청자 ID (JWT 생성 시 입력한 client_user_id)
start_atinteger전송 요청 시각 (비디오 게이트웨이 호출 시점, Unix timestamp)
  • 다운로드 콘텐츠는 재생 시점의 디바이스 시각
play_timeinteger배속 및 구간 반복을 포함한 누적 재생 시간 (sec)
playtime_percentinteger콘텐츠 전체 길이 대비 재생 비율 (%, 소수점 절삭)
  • 예: 2회 재생 → 200%
last_play_atinteger마지막 재생 위치 (sec)
durationinteger콘텐츠 전체 길이 (sec)
media_content_keystring미디어 콘텐츠 키
encoding_profile_keystring인코딩 프로파일 키
block_cntinteger설정된 블록 수
play_block_jsonJSON전체 블록 재생 정보 (json_data.block_info와 동일)
host_namestring콘텐츠 링크 요청 도메인
  • 예: catenoid.video.kr.kollus.com
player_idstringKollus 플레이어 고유 ID
hashstring데이터 변조 방지용 Hash 값 (HTML5 Player 지원 안 함)

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

데이터 변조 방지를 위해 다음 단계에 따라 Hash 값을 생성하여 수신 데이터의 무결성을 검증하세요.

  1. hash_1 = md5(post_data)
  2. hash_2 = md5(hash_1+service_account)
  3. 생성된 hash_2 값을 요청 파라미터의 hash 값과 비교하여 검증
참고
  • +는 산술 연산이 아닌 문자열 결합(String Concatenation)을 의미합니다.
  • 아래 예시와 같이 + 기호 자체를 문자열에 포함해야 합니다.
Hash 생성 예시​
hash_1 = "abc123"
service_account = "kollus-test"

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

LMS 콜백 데이터 포맷​

비디오 게이트웨이가 플레이어에 전달하는 콜백 설정의 전체 포맷입니다.

[block_count]:[period]:[enable_blocks]:[enable_sessions]:[callback_url]?{PLUGIN_OPTION}

LMS 콜백 데이터 예시​

예시 1 (기본 구성)​
10:30:1:0:https://domain.com/check.asp?id={CLIENT_USER_ID}&start={START_AT}&uservalue0={USERVALUE0}
예시 2 (JSON 데이터 포함)​
20:180:0:1:https://another_domain.com/another_check.php?id={CLIENT_USER_ID}&start={START_AT}&json_data={JSON_DATA}&uservalue0={USERVALUE0}&uservalue1={USERVALUE1}

전송 데이터(JSON_DATA) 구조​

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

시청자 정보 (user_info)​

필드타입설명
content_provider_keystring서비스 계정 키 (참고 문서: 인증 및 주요 키)
client_user_idstring시청자 ID (JWT 생성 시 입력한 client_user_id)
player_idstringKollus 플레이어 고유 ID
hardware_idstring하드웨어 ID
host_namestring콘텐츠 요청 도메인
devicestring디바이스 모델명

콘텐츠 정보 (content_info)​

필드타입설명
durationinteger콘텐츠 전체 길이 (sec)
encoding_profilestring인코딩 프로파일 키
media_content_keystring미디어 콘텐츠 키
channel_keystring콘텐츠가 등록된 채널 식별 키
real_playtimeinteger배속 포함 및 구간 반복 제외 누적 재생 시간 (sec)
  • 예: 0~10초 구간 2배속 재생 → 5초
playtimeinteger배속 및 구간 반복을 포함한 누적 재생 시간 (sec)
playtime_percentinteger콘텐츠 전체 길이 대비 재생 비율 (%, 소수점 절삭)
  • 예: 2회 재생 → 200%
start_atinteger전송 요청 시각 (비디오 게이트웨이 호출 시점, Unix timestamp)
  • 다운로드 콘텐츠는 재생 시점의 디바이스 시각
last_play_atinteger마지막 재생 위치 (sec)
runtimeinteger구간 반복 및 일시정지를 포함한 누적 재생 시간 (sec)
showtimeinteger구간 반복 포함 누적 재생 시간 (sec)
serialintegerLMS 발송 순서 (0부터 순차 증가)

블록 정보 (block_info)​

필드타입설명
block_countinteger영상을 분할하는 논리적 구간 수
blocksobject블록별 재생 데이터 (마일스톤 기반 요약 정보)
sessionsarray상세 재생 세션 이력 (이전 세션 데이터를 포함한 누적 데이터 배열)

block_info.blocks​

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

필드 패턴타입설명
b{n}string블록 재생 여부
  • 0: 재생하지 않음
  • 1: 재생
t{n}string배속 포함 블록 재생 시간 (sec)
p{n}string블록 재생 비율 (%, 소수점 절삭)
  • 예: 2회 재생 → 200%
예시​
  • b0=1, t0=15, p0=100 → 0번 블록을 총 15초간 시청하여 해당 구간 100% 학습 완료
  • b1=0, t1=0, p1=0 → 1번 블록은 시청 이력이 없는 상태

block_info.sessions​

필드타입설명예시
blockinteger해당 데이터가 포함된 블록 인덱스 (0부터 시작)
start_timeinteger해당 세션의 재생 시작 시각 (Unix timestamp → localtime)
play_timeinteger해당 세션의 재생 시간 (sec)
예시​

0번 블록을 1761531042 시각에 재생 시작하여 1초 동안 재생한 경우의 JSON 구조입니다.

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

플레이어 상태 (player_status)​

필드타입설명
playback_rateinteger배속
volume_levelinteger음량 수치 (0~100)
play_statusstring재생 상태 (Kollus 보안 플레이어에서만 사용 가능)
  • play: 재생 중
  • pause: 일시정지
  • stop: 종료

커스텀 필드 (uservalues)​

필드타입설명
uservalue{0~99}string커스텀 변수 (uservalue0~uservalue99)
주의
  • 크기 제한: 모든 uservalue 항목의 합계 크기는 1KB 이하여야 합니다.
  • 인코딩: 한글, 특수문자, 공백이 포함된 경우, 반드시 해당 값을 UTF-8 URL 인코딩 처리하여 전달해야 합니다.