Events

The Timeback SDK emits Caliper-based events to report learning activity. This page describes the SDK’s TimebackProfile output before any destination-specific transformation. Choose your assigned endpoint and wire format in Event Contracts. The Partner Events API and Platform native schemas have separate event references.

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" },
		"course": { "id": "https://api.example.com/ims/oneroster/rostering/v1p2/courses/course-example", "name": "Math Grade 3" },
		"activity": { "name": "Fractions lesson" },
		"process": true
	},
	"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": "course-example"
	}
}

Activity metrics

The generated.items array contains completion metrics. Each item has a type (string) and a value (number).

number

required

XP supplied by your app for this activity. Follow the XP policy agreed for your integration. The SDK does not infer XP from elapsed time or question counts.

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. When this value is positive, the SDK server can combine it with historical enrollment facts and a configured positive totalLessons to compute pctCompleteApp, unless you supplied pctComplete explicitly. If enrollment or historical facts cannot be resolved, computation can be skipped. 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

The SDK sends periodic heartbeats every 15 seconds by default and flushes measured time when an activity ends. The server uses that measured time to construct TimeSpentEvents. Each event reports a bounded time window; a heartbeat is not itself proof that a Caliper event or analytics fact was persisted.

{
	"@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" },
		"course": { "id": "https://api.example.com/ims/oneroster/rostering/v1p2/courses/course-example", "name": "Math Grade 3" },
		"activity": { "name": "Fractions lesson" },
		"process": true
	},
	"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": "course-example"
	}
}

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.

Acceptance and delivery

An accepted Caliper request does not confirm XP, reporting, or progression completion. Preserve each event ID and the original payload across transport retries. A new event ID can represent new work to a downstream consumer. An activity’s Completed action does not by itself assert that the whole course is complete.

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, Handwriting, 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

Controls TimebackProfile activity processing. The SDK defaults this to true. When sending direct activity events, include it when your integration expects the activity consumer to process them.

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

Application context on the event. Its accepted representation depends on the target contract.

object

Custom attributes including runId and courseId for event correlation.

The legacy event schema also defines the following optional event-level fields. They are not envelope metadata, and compatibility parsers on another destination may reject them:

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

Acceptance and delivery

Shared structure

Custom Activities

Caliper API

Getting Started

CLI

SDK

Reference

​ActivityCompletedEvent

​Activity metrics

​TimeSpentEvent

​Time metrics

​Time categories

​Per-item fields

​Acceptance and delivery

​Shared structure

Custom Activities

Caliper API

ActivityCompletedEvent

Activity metrics

TimeSpentEvent

Time metrics

Time categories

Per-item fields

Acceptance and delivery

Shared structure