The Timeback SDK emits Caliper -based events to report learning activity.
ActivityCompletedEvent Emitted once per activity run when the student completes the activity. Carries completion metrics like questions answered, XP earned, and mastery.
{ "@context" : "http://purl.imsglobal.org/ctx/caliper/v1p2" , "id" : "urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594" , "type" : "ActivityEvent" , "action" : "Completed" , "profile" : "TimebackProfile" , "eventTime" : "2026-01-27T10:03:00.000Z" , "actor" : { "id" : "https://api.example.com/ims/oneroster/rostering/v1p2/users/student-123" , "type" : "TimebackUser" , "email" : "[email protected] " }, "object" : { "id" : "https://myapp.example.com/activities/Math/g3/lesson-1" , "type" : "TimebackActivityContext" , "subject" : "Math" , "app" : { "name" : "My App" } }, "generated" : { "id" : "https://api.example.com/ims/metrics/collections/activity/abc-123" , "type" : "TimebackActivityMetricsCollection" , "items" : [ { "type" : "xpEarned" , "value" : 80 }, { "type" : "totalQuestions" , "value" : 10 }, { "type" : "correctQuestions" , "value" : 8 }, { "type" : "masteredUnits" , "value" : 1 } ], "extensions" : { "pctCompleteApp" : 67 } }, "extensions" : { "runId" : "f47ac10b-58cc-4372-a567-0e02b2c3d479" , "courseId" : "MATH-3" } }
Activity metrics The generated.items array contains completion metrics. Each item has a type (string) and a value (number).
Total questions in the activity. Optional, but required if correctQuestions is provided.
Questions answered correctly. Optional, but required if totalQuestions is provided.
Number of units mastered during this activity. Optional.
App-defined course completion percentage (0–100). Sent via generated.extensions.pctCompleteApp.
TimeSpentEvent Emitted periodically during a session (every 15s by default) and on final flush. Each event covers a bounded time window — how many seconds were active vs inactive.
{ "@context" : "http://purl.imsglobal.org/ctx/caliper/v1p2" , "id" : "urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "type" : "TimeSpentEvent" , "action" : "SpentTime" , "profile" : "TimebackProfile" , "eventTime" : "2026-01-27T10:00:15.000Z" , "actor" : { "id" : "https://api.example.com/ims/oneroster/rostering/v1p2/users/student-123" , "type" : "TimebackUser" , "email" : "[email protected] " }, "object" : { "id" : "https://myapp.example.com/activities/Math/g3/lesson-1" , "type" : "TimebackActivityContext" , "subject" : "Math" , "app" : { "name" : "My App" } }, "generated" : { "id" : "https://api.example.com/ims/metrics/collections/time-spent/def-456" , "type" : "TimebackTimeSpentMetricsCollection" , "items" : [ { "type" : "active" , "value" : 15 , "startDate" : "2026-01-27T10:00:00.000Z" , "endDate" : "2026-01-27T10:00:15.000Z" }, { "type" : "inactive" , "value" : 0 } ] }, "extensions" : { "runId" : "f47ac10b-58cc-4372-a567-0e02b2c3d479" , "courseId" : "MATH-3" } }
Time metrics The generated.items array contains time window metrics. Each item has a type (string), a value in seconds (max 86400), and optional fields.
Time categories Seconds the student was actively engaged (tab visible, not paused).
Seconds the student was inactive (paused or tab hidden).
Seconds classified as non-productive.
Seconds that could not be classified.
Seconds flagged as anomalous behavior.
Per-item fields Optional sub-classification providing additional detail on the time category.
ISO 8601 timestamp for the start of the time window.
ISO 8601 timestamp for the end of the time window.
Shared structure Both event types share these top-level fields:
Caliper JSON-LD context. Always "http://purl.imsglobal.org/ctx/caliper/v1p2".
Unique event identifier in urn:uuid:... format.
"ActivityEvent" for completions, "TimeSpentEvent" for time windows.
"Completed" for completions, "SpentTime" for time windows.
Always "TimebackProfile".
ISO 8601 timestamp of when the event occurred.
The student who performed the action. See Identity . URL identifying the user (e.g. OneRoster user URL).
The student’s email address.
One of student, teacher, admin, or guide.
object
TimebackActivityContext
required
The activity context where the event was recorded. URL identifying the activity.
Always "TimebackActivityContext".
One of Reading, Language, Vocabulary, Social Studies, Writing, Science, FastMath, Math, None, Other.
The application. Must include name. Optional id (URL) and extensions.
The course context. Must include name. Optional id (URL) and extensions.
The specific activity. Must include name. Optional id (URL) and extensions.
Whether to process the event through the ETL pipeline.
Metrics collection. Shape depends on event type: ActivityCompletedEvent
TimeSpentEvent
Type: TimebackActivityMetricsCollection URL identifying this collection.
Always "TimebackActivityMetricsCollection".
items
TimebackActivityMetric[]
required
Array of activity metrics. Each item has type (xpEarned, totalQuestions, correctQuestions, masteredUnits) and value (number). See Activity metrics . Additional attributes, e.g. pctCompleteApp (course completion percentage, 0–100).
Type: TimebackTimeSpentMetricsCollection URL identifying this collection.
Always "TimebackTimeSpentMetricsCollection".
items
TimeSpentMetric[]
required
Array of time metrics. Each item has type (active, inactive, waste, unknown, anti-pattern), value (seconds), and optional startDate/endDate. See Time metrics . Additional attributes not defined by the model.
URL identifying the application context (standard Caliper envelope field).
Custom attributes including runId and courseId for event correlation.
Both events also accept these optional Caliper envelope fields:
Entity representing a particular segment or location within the object.
Entity representing the referring context.
An Organization representing the group context. Can be a URL or an Organization entity object.
The relationship between the actor and the group in terms of roles and status.
The current user session.
If the event occurs within an LTI platform launch, the tool’s LtiSession.
