Events

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

number

required

XP earned for this activity. Must follow the 1 XP = 1 focused minute rule.

number

Total questions in the activity. Optional, but required if correctQuestions is provided.

number

Questions answered correctly. Optional, but required if totalQuestions is provided.

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.

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

number

Seconds the student was actively engaged (tab visible, not paused).

number

Seconds the student was inactive (paused or tab hidden).

number

Seconds classified as non-productive.

number

Seconds that could not be classified.

number

Seconds flagged as anomalous behavior.

Per-item fields

string

Optional sub-classification providing additional detail on the time category.

string

ISO 8601 timestamp for the start of the time window.

string

ISO 8601 timestamp for the end of the time window.

Shared structure

Both event types share these top-level fields:

string

required

Caliper JSON-LD context. Always "http://purl.imsglobal.org/ctx/caliper/v1p2".

string

required

Unique event identifier in urn:uuid:... format.

string

required

"ActivityEvent" for completions, "TimeSpentEvent" for time windows.

string

required

"Completed" for completions, "SpentTime" for time windows.

string

required

Always "TimebackProfile".

string

required

ISO 8601 timestamp of when the event occurred.

TimebackUser

required

The student who performed the action. See Identity.

Show properties

string

required

URL identifying the user (e.g. OneRoster user URL).

string

required

Always "TimebackUser".

string

required

The student’s email address.

string

Display name.

string

One of student, teacher, admin, or guide.

TimebackActivityContext

required

The activity context where the event was recorded.

Show properties

string

required

URL identifying the activity.

string

required

Always "TimebackActivityContext".

string

required

One of Reading, Language, Vocabulary, Social Studies, Writing, Science, FastMath, Math, None, Other.

object

required

The application. Must include name. Optional id (URL) and extensions.

object

The course context. Must include name. Optional id (URL) and extensions.

object

The specific activity. Must include name. Optional id (URL) and extensions.

boolean

Whether to process the event through the ETL pipeline.

object

required

Metrics collection. Shape depends on event type:

ActivityCompletedEvent
TimeSpentEvent

Type: TimebackActivityMetricsCollection

Show properties

string

required

URL identifying this collection.

string

required

Always "TimebackActivityMetricsCollection".

TimebackActivityMetric[]

required

Array of activity metrics. Each item has type (xpEarned, totalQuestions, correctQuestions, masteredUnits) and value (number). See Activity metrics.

object

Additional attributes, e.g. pctCompleteApp (course completion percentage, 0–100).

Type: TimebackTimeSpentMetricsCollection

Show properties

string

required

URL identifying this collection.

string

required

Always "TimebackTimeSpentMetricsCollection".

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.

object

Additional attributes not defined by the model.

string

URL identifying the application context (standard Caliper envelope field).

object

Custom attributes including runId and courseId for event correlation.

Both events also accept these optional Caliper envelope fields:

string

Entity representing a particular segment or location within the object.

string

Entity representing the referring context.

string | object

An Organization representing the group context. Can be a URL or an Organization entity object.

string

The relationship between the actor and the group in terms of roles and status.

string

The current user session.

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

Getting Started

CLI

SDK

Reference

ActivityCompletedEvent

Activity metrics

TimeSpentEvent

Time metrics

Time categories

Per-item fields

Shared structure

Custom Activities

Caliper API

​ActivityCompletedEvent

​Activity metrics

​TimeSpentEvent

​Time metrics

​Time categories

​Per-item fields

​Shared structure

Custom Activities

Caliper API

ActivityCompletedEvent

Activity metrics

TimeSpentEvent

Time metrics

Time categories

Per-item fields

Shared structure