How logging works
When a learner experiences a simulation, their activity is recorded as a stream of timestamped events. This page describes how that stream is organized, so the Event Reference and Attribute Reference make sense.
Core concepts
Event. A single occurrence at a point in time. Events are either learner generated, such as grabbing an object, or system generated, such as a scene finishing loading. Every event has a name and a timestamp.
Attribute. A key and value attached to an event. A grab event carries the name of the object grabbed. Attributes differ by event type, on top of a common set that every event carries.
Session. Begins when the learner opens the application and ends when they leave it. Identified by sessionId. One session can contain several runs.
Run. Begins when a simulation is loaded and ends when the learner leaves it. Identified by runId. This is the unit most analytics are built around, and the unit a replay covers.
Lesson attempt. When a simulation is played inside a lesson, the run is also tied to a lesson attempt through lessonAttemptId, which links simulation activity to course and classroom progress.
Platforms
The appName field identifies where a run happened.
hypermock-vr
VR headsets, Quest family and Pico
hypermock-desktop
Desktop application and the web build
hypermock-web
Spark, the conversational simulation player
hyperskill-android
Android
hyperskill-vision
Apple Vision Pro
hololens2, hyperskill-hl
Microsoft HoloLens 2
ios
iOS and iPadOS
career-pathway
Career Pathway assessment
activity-viewer
Lesson and activity player
Not every event appears on every platform. Controller and haptic attributes only appear where the hardware supports them. The Event Reference notes where this matters.
Identifying the learner
Three fields carry identity, and which are present depends on how the learner reached the simulation.
hs_user_id
The HyperSkill account. Present for signed in learners.
user_auth0
The sign in identity, for example google-oauth2 | 1234.... Present when the learner authenticated.
hs_anon_id
A generated identifier for a learner with no account.
userId
A display name, not a stable identifier
student_id, student_name
Supplied by an LMS on SCORM launches.
A run is anonymous when it carries neither hs_user_id nor a real user_auth0
Scores and skill values are recorded per run, so an anonymous run still produces results. They just cannot be attributed to a person.
Timestamps
Every event carries two times, and they answer different questions.
timestamp_client
When the event happened on the device.
timestamp_server
When the event arrived at our servers.
Both are Unix milliseconds in UTC.
Events are uploaded in batches, so several events can share a single timestamp_server even though they happened seconds apart. On a headset used offline, an entire session uploads at once when it reconnects, which compresses hours of activity into a single instant of server time.
Use timestamp_client to measure how long something took, the gap between two events, or the order they occurred in. Use timestamp_server for when a session was received, and as a fallback when a client timestamp is missing.
Client clocks are set by the device and are occasionally wrong. Because a wrong clock is usually wrong by a constant amount, differences between two client timestamps stay accurate even when the absolute time does not.
Sensor Data
The sensor stream records three entities per run: headset, ctrl_l and ctrl_r. Each sample carries position as px, py, pz and rotation as rx, ry, rz, tied to a runId.
Last updated