LMS Callback

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

Kollus VOD supports a feature that collects viewing data generated during content playback in real time and sends it to the customer's Learning Management System(LMS) server. This enables advanced educational management logic, such as determining course completion, analyzing viewing patterns, and saving the last playback position.

---

Key features

• Asynchronous transmission: The player sends data without waiting for a server response, ensuring uninterrupted playback.
• Automatic retry policy: If a customer server or network failure occurs, data is temporarily stored on the client and retransmitted sequentially once communication is restored.
• Privacy protection: LMS callback data does not include sensitive information such as MAC Address or IP Address.

---

Callback configuration

The callback URL can be configured in the Kollus VOD console.

• Guide: Callback Integration - LMS Callback

---

Callback flow

This is the complete process from LMS data collection to transmission to the customer server.

1. Callback configuration: Define the callback URL and collection specifications per channel in the Kollus VOD console.
2. Playback request: When a user clicks on content, the customer server calls the Video Gateway.
3. Configuration delivery: The Video Gateway delivers playback information, callback policy, and custom variables (uservalue0–uservalue99) to the player.
4. Real-time data transmission: The player collects viewing data and sends it to the customer's endpoint.

Callback invocation policy

Since the LMS server must reconstruct the user's learning history from the received parameters, design your logic in accordance with the following transmission policy.

• Periodic call: Data is delivered at every configured transfer interval (period).
• Event call: Data is delivered immediately upon pause or playback end, regardless of the interval.
• Retry policy: If a network failure occurs, data is temporarily stored on the client and retransmitted as soon as communication is restored.

Identifying data from the same session

Callback data from the same user may be received multiple times due to the transfer interval and events. The system must combine the client_user_id (user ID) and start_at (session start time) values to identify the last record of a single playback session and update the data accordingly.

• Identification logic: Group records where client_user_id and start_at match, then confirm the most recently received data as the final viewing history.

---

Data calculation specifications

These are the measurement criteria for playback progress rate and playback duration, which are the core of LMS data.

Playback block

A block is a logical unit that divides the entire video into equal segments. The player records whether each block has been viewed individually to calculate the playback progress rate.

Item	Detailed Specifications	Notes
Configuration range	Integer between 1–100	Automatically fixed to 100 if a value exceeding 100 is entered
Minimum unit	1 (single block for entire video)	Treated as 1 if a value of 0 or below is entered
Recommended setting	Set to no more than the content length	No more than 1 block per second is generated

• Example 1: If the number of blocks is set to 10 for a 300-second video, each block will be 30 seconds long.
• Example 2: Even if the number of blocks is set to 100 for a 30-second video, only 30 blocks of data are generated and transmitted, calculated at 1 block per second.

playback duration term definitions

Since each metric is calculated differently, refer to the table below when implementing your system.

Term	Playback speed	Loop section	Pause	Example: 0–10 sec playback section, 2x speed, 1 loop, 5 sec pause
play_time	◯	◯	×	(10 sec ÷ 2x speed) + (10 sec loop ÷ 2x speed) = 10 sec
real_playtime	◯	×	×	(10 sec ÷ 2x speed) = 5 sec
runtime	×	◯	◯	10 sec + 10 sec loop + 5 sec pause = 25 sec
showtime	×	◯	×	10 sec + 10 sec loop = 20 sec

---

Callback configuration information

delivery method

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

Configuration parameters

These are the basic LMS policy parameters configured in the Kollus VOD console.

Parameter	Type	Description
Block count (block_count)	integer	Number of logical segments the video is divided into
Transfer interval (period)	integer	Time interval for sending data to the server (sec)
Block information included (enable_blocks)	integer	Whether to include block information in block_info 0: Not included 1: Included
Session information included (enable_sessions)	integer	Whether to include session information in block_info 0: Not included 1: Included
Callback URL (callback_url)	string	Customer server address to receive LMS data

plugin options

Configure the detailed items to be included in the LMS callback request. Selected options are included as parameters in the callback request.

Parameter	Type	Description
json_data	JSON	JSON object containing all playback information (includes user_info, content_info, block_info)
client_user_id	string	User ID (the client_user_id entered when generating JWT)
start_at	integer	Transmission request time (Video Gateway call time, Unix timestamp) For downloaded content, the device time at the point of playback
play_time	integer	Cumulative playback duration including playback speed and loop section (sec)
playtime_percent	integer	Playback ratio relative to the total content length (%, decimal truncated) Example: 2 plays → 200%
last_play_at	integer	Last playback position (sec)
duration	integer	Total content length (sec)
media_content_key	string	Media content key
encoding_profile_key	string	Encoding profile key
block_cnt	integer	Configured number of blocks
play_block_json	JSON	Full block playback information (same as json_data.block_info)
host_name	string	Domain of the content link request Example: catenoid.video.kr.kollus.com
player_id	string	Kollus Player unique ID
hash	string	Hash value for data tampering prevention (not supported in HTML5 Player)

Hash (integrity verification) generation rules

To prevent data tampering, generate a Hash value according to the following steps and verify the integrity of the received data.

1. hash_1 = md5(post_data)
2. hash_2 = md5(hash_1+service_account)
3. Compare the generated hash_2 value with the hash value in the request parameters to verify

Note

• + refers to String Concatenation, not an arithmetic operation.
• The + symbol itself must be included in the string, as shown in the example below.

Hash generation example

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

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

LMS callback data format

The complete format of the callback configuration delivered by the Video Gateway to the player.

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

LMS callback data examples

Example 1 (basic configuration)

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

Example 2 (including JSON data)

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}

---

Transmission data (JSON_data) structure

JSON_DATA contains the entirety of the playback information.

User information (user_info)

Field	Type	Description
content_provider_key	string	Service account key (See Also: Authentication and Key Information)
client_user_id	string	User ID (the client_user_id entered when generating JWT)
player_id	string	Kollus Player unique ID
hardware_id	string	Hardware ID
host_name	string	Content request domain
device	string	Device model name

Content information (content_info)

Field	Type	Description
duration	integer	Total content length (sec)
encoding_profile	string	Encoding profile key
media_content_key	string	Media content key
channel_key	string	Identification key of the channel the content is registered in
real_playtime	integer	Cumulative playback duration including playback speed and excluding loop section (sec) Example: Playback of 0–10 sec at 2x speed → 5 sec
playtime	integer	Cumulative playback duration including playback speed and loop section (sec)
playtime_percent	integer	Playback ratio relative to the total content length (%, decimal truncated) Example: 2 plays → 200%
start_at	integer	Transmission request time (Video Gateway call time, Unix timestamp) For downloaded content, the device time at the point of playback
last_play_at	integer	Last playback position (sec)
runtime	integer	Cumulative playback duration including loop section and pause (sec)
showtime	integer	Cumulative playback duration including loop section (sec)
serial	integer	LMS send order (incrementing sequentially from 0)

Block information (block_info)

Field	Type	Description
block_count	integer	Number of logical segments the video is divided into
blocks	object	Playback data per block (milestone-based summary information)
sessions	array	Detailed playback session history (cumulative data array including previous session data)

Block_info.blocks

Provides detailed data for each block index ({n}). Block indices start from 0 and repeat up to the number of block_count.

Field Pattern	Type	Description
b{n}	string	Whether the block was played 0: Not played 1: Played
t{n}	string	Block playback duration including playback speed (sec)
p{n}	string	Block playback ratio (%, decimal truncated) Example: 2 plays → 200%

Example

• b0=1, t0=15, p0=100 → Block 0 was viewed for a total of 15 seconds, completing 100% of that section
• b1=0, t1=0, p1=0 → Block 1 has no viewing history

Block_info.sessions

Field	Type	Description	Example
block	integer	Block index where this data is included (starting from 0)
start_time	integer	Playback start time of the session (Unix timestamp → localtime)
play_time	integer	Playback duration of the session (sec)

Example

This is the JSON structure for the case where block 0 starts playing at time 1761531042 and plays for 1 second.

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

Player status (player_status)

Field	Type	Description
playback_rate	integer	Playback speed
volume_level	integer	Volume level (0–100)
play_status	string	Playback status (available only in Kollus secure player) play: Playing pause: Paused stop: Stopped

Custom fields (uservalues)

Field	Type	Description
uservalue{0~99}	string	Custom variables (uservalue0–uservalue99)

Caution

• Size limit: The total size of all uservalue items must be 1KB or less.
• Encoding: If the value contains Korean characters, special characters, or spaces, the value must be UTF-8 URL encoded before transmission.