Skip to main content
The Timeback SDK emits Caliper-based events to report learning activity.
See Activity Models for when each event is emitted.

​
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": "student@example.com"
	},
	"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).
​
xpEarned
number
required
XP earned for this activity. Must follow the 1 XP = 1 focused minute rule.
​
totalQuestions
number
Total questions in the activity. Optional, but required if correctQuestions is provided.
​
correctQuestions
number
Questions answered correctly. Optional, but required if totalQuestions is provided.
​
masteredUnits
number
Number of new units (lessons) the student mastered during this activity. This is an incremental count, not a cumulative total. The server sums these values across submissions and uses them to auto-compute pctCompleteApp. Optional. See Course progress for full details.
​
pctCompleteApp
number
Course completion percentage (0—100). Either passed directly via pctComplete in the activity payload, or auto-computed by the server from masteredUnits and totalLessons. Sent via generated.extensions.pctCompleteApp. See Course progress.

​
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": "student@example.com"
	},
	"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

​
active
number
Seconds the student was actively engaged (tab visible, not paused).
​
inactive
number
Seconds the student was inactive (paused or tab hidden).
​
waste
number
Seconds classified as non-productive.
​
unknown
number
Seconds that could not be classified.
​
anti-pattern
number
Seconds flagged as anomalous behavior.

​
Per-item fields

​
subType
string
Optional sub-classification providing additional detail on the time category.
​
startDate
string
ISO 8601 timestamp for the start of the time window.
​
endDate
string
ISO 8601 timestamp for the end of the time window.

​
Shared structure

Both event types share these top-level fields:
​
@context
string
required
Caliper JSON-LD context. Always "http://purl.imsglobal.org/ctx/caliper/v1p2".
​
id
string
required
Unique event identifier in urn:uuid:... format.
​
type
string
required
"ActivityEvent" for completions, "TimeSpentEvent" for time windows.
​
action
string
required
"Completed" for completions, "SpentTime" for time windows.
​
profile
string
required
Always "TimebackProfile".
​
eventTime
string
required
ISO 8601 timestamp of when the event occurred.
​
actor
TimebackUser
required
The student who performed the action. See Identity.
​
object
TimebackActivityContext
required
The activity context where the event was recorded.
​
generated
object
required
Metrics collection. Shape depends on event type:
Type: TimebackActivityMetricsCollection
​
edApp
string
URL identifying the application context (standard Caliper envelope field).
​
extensions
object
Custom attributes including runId and courseId for event correlation.
Both events also accept these optional Caliper envelope fields:
​
target
string
Entity representing a particular segment or location within the object.
​
referrer
string
Entity representing the referring context.
​
group
string | object
An Organization representing the group context. Can be a URL or an Organization entity object.
​
membership
string
The relationship between the actor and the group in terms of roles and status.
​
session
string
The current user session.
​
federatedSession
string
If the event occurs within an LTI platform launch, the tool’s LtiSession.

Custom Activities

How the SDK emits these events

Caliper API

Direct Caliper API access for custom event submission