LMS Callbacks

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: LMS callback

How to Reset Callback

To disable or reset an existing LMS callback configuration, follow the steps below:

1. In the Kollus VOD Console, go to [Channels] > Left Channel List [More (⋮)] > [Callback Settings] > [LMS] tab.
2. Scroll down to the bottom of the page and clear all values entered in [LMS Callback Data].
3. Click [Save] to reset the LMS callback settings.

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 to 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.

• Condition: 0–10 sec playback section, 2x speed, 1 loop, 5 sec pause

Term	Playback speed	Section Repeat	Pause	Calculation example
play_time	×	◯	×	10s + 10s repeat = 20s
real_playtime	×	×	×	10s
runtime	◯	◯	◯	(10s ÷ 2x) + (10s repeat ÷ 2x) + 5s pause = 15s
showtime	◯	◯	×	(10s ÷ 2x) + (10s repeat ÷ 2x) = 10s

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 time including section repeats (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 & Keys)
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	Length of playback section (sec) Example: 0–10s section played at 2x speed → 10s
playtime	integer	Cumulative playback time including section repeats (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 time including speed multiplier, section repeats, and pauses (sec)
showtime	integer	Cumulative playback time including speed multiplier and section repeats (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 to 100)
play_status	string	Playback status (available only in Kollus secure player) play: Playing pause: Paused stop: Stopped

Custom fields (uservalues)

Field	Type	Description
uservalue0 to uservalue99	string	Custom variables

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.