Stateful activities

Stateful activities span multiple sessions. The client SDK tracks time per session via heartbeats, and the server records completion when the activity is truly done.

For info on shared concepts, see the Activity Tracking overview.

Architecture

Stateful activities split responsibility between frontend and backend:

Responsibility	Owner	Mechanism
Time tracking	Frontend	Heartbeats via `activity.start()`
State	Backend	Your app’s database
Completion	Backend	`timeback.activity.record()`

A runId ties all sessions together. The SDK generates one automatically when you call activity.start(), but you can also provide your own. Any unique string works. If your app already has a unique identifier for the activity attempt (e.g. an assignment row ID), pass it as runId directly instead of storing a separate value. On resume, pass the same runId so every heartbeat and the final completion event share the same identifier.

Frontend

The frontend tracks time per session and orchestrates the student’s workflow (starting, resuming, and submitting answers). But completion must come from the server: across multiple sessions, it’s the only part of the system that has the full picture of the student’s accumulated progress.

Starting a session

const activity = timeback.activity.start({
	id: 'lesson-1',
	name: 'Fractions',
	course: { subject: 'Math', grade: 3 },
})

// Your API — persist the runId so you can pass it back on resume
await saveProgress({ lessonId: 'lesson-1', runId: activity.runId })

Resuming a session

const progress = await loadProgress({ lessonId: 'lesson-1' })

const activity = timeback.activity.start({
	id: 'lesson-1',
	name: 'Fractions',
	course: { subject: 'Math', grade: 3 },
	runId: progress.runId, // reuse the saved runId
})

Ending a session

This is the key difference from single-session activities: the student can leave at any point — close the tab, navigate away, or simply stop for the day — without losing their progress. Calling activity.end() flushes the accumulated time but does not record a completion. The activity stays open, ready to be resumed later with the same runId.

await activity.end() // Flushes time, no completion

The frontend always calls activity.end() without metrics. Completion is recorded by the server.

Framework examples

React
Vue
Svelte
Solid

import { useEffect, useRef } from 'react'
import { useTimeback } from '@timeback/sdk/react'

function ResumableLesson({ lessonId, lessonName }) {
	const timeback = useTimeback()
	const activityRef = useRef(null)

	useEffect(() => {
		if (!timeback) return

		async function startTracking() {
			// Your API — load saved progress (if any)
			const res = await fetch(`/api/progress/${lessonId}`)
			const progress = await res.json()

			activityRef.current = timeback.activity.start({
				id: lessonId,
				name: lessonName,
				course: { subject: 'Math', grade: 3 },
				...(progress?.runId && { runId: progress.runId }),
			})

			// Your API — persist runId on first start
			if (!progress?.runId) {
				await fetch(`/api/progress/${lessonId}`, {
					method: 'POST',
					body: JSON.stringify({ runId: activityRef.current.runId }),
				})
			}
		}

		startTracking()

		return () => {
			// Flush time on unmount — server handles completion
			void activityRef.current?.end()
		}
	}, [timeback, lessonId, lessonName])

	return <div>Lesson content...</div>
}

<script setup>
import { onMounted, onUnmounted, ref } from 'vue'
import { useTimeback } from '@timeback/sdk/vue'

const props = defineProps(['lessonId', 'lessonName'])
const timeback = useTimeback()
const activity = ref(null)

onMounted(async () => {
	if (!timeback.value) return

	// Your API — load saved progress (if any)
	const res = await fetch(`/api/progress/${props.lessonId}`)
	const progress = await res.json()

	activity.value = timeback.value.activity.start({
		id: props.lessonId,
		name: props.lessonName,
		course: { subject: 'Math', grade: 3 },
		...(progress?.runId && { runId: progress.runId }),
	})

	// Your API — persist runId on first start
	if (!progress?.runId) {
		await fetch(`/api/progress/${props.lessonId}`, {
			method: 'POST',
			body: JSON.stringify({ runId: activity.value.runId }),
		})
	}
})

onUnmounted(() => {
	// Flush time on unmount — server handles completion
	void activity.value?.end()
})
</script>

<script>
	import { onMount, onDestroy } from 'svelte'
	import { timeback } from '@timeback/sdk/svelte'

	export let lessonId
	export let lessonName

	let activity

	onMount(async () => {
		if (!$timeback) return

		// Your API — load saved progress (if any)
		const res = await fetch(`/api/progress/${lessonId}`)
		const progress = await res.json()

		activity = $timeback.activity.start({
			id: lessonId,
			name: lessonName,
			course: { subject: 'Math', grade: 3 },
			...(progress?.runId && { runId: progress.runId }),
		})

		// Your API — persist runId on first start
		if (!progress?.runId) {
			await fetch(`/api/progress/${lessonId}`, {
				method: 'POST',
				body: JSON.stringify({ runId: activity.runId }),
			})
		}
	})

	onDestroy(() => {
		// Flush time on unmount — server handles completion
		void activity?.end()
	})
</script>

import { onMount, onCleanup } from 'solid-js'
import { useTimeback } from '@timeback/sdk/solid'

function ResumableLesson(props) {
	const timeback = useTimeback()
	let activity

	onMount(async () => {
		if (!timeback) return

		// Your API — load saved progress (if any)
		const res = await fetch(`/api/progress/${props.lessonId}`)
		const progress = await res.json()

		activity = timeback.activity.start({
			id: props.lessonId,
			name: props.lessonName,
			course: { subject: 'Math', grade: 3 },
			...(progress?.runId && { runId: progress.runId }),
		})

		// Your API — persist runId on first start
		if (!progress?.runId) {
			await fetch(`/api/progress/${props.lessonId}`, {
				method: 'POST',
				body: JSON.stringify({ runId: activity.runId }),
			})
		}
	})

	onCleanup(() => {
		// Flush time on unmount — server handles completion
		void activity?.end()
	})

	return <div>Lesson content...</div>
}

Backend

When a student completes an activity, as determined by your app’s logic, the backend records the result using timeback.activity.record(). This sends an ActivityCompletedEvent to the Caliper API.

Basic usage

await timeback.activity.record({
	user: { email: '[email protected]' },
	activity: {
		id: 'lesson-1',
		name: 'Fractions',
		course: { code: 'MATH-3' },
	},
	metrics: {
		totalQuestions: 20,
		correctQuestions: 16,
		xpEarned: 150,
		masteredUnits: 2,
		pctComplete: 100,
	},
	runId: savedProgress.runId, // Correlate with frontend heartbeats
})

With time data (advanced)

You will rarely, if ever, need this pattern. The frontend SDK already tracks time via heartbeats. Only use the time parameter if your backend independently tracks accumulated time (e.g. from offline sync or batch imports) and you need to override what the heartbeats reported.

await timeback.activity.record({
	user: { email: '[email protected]' },
	activity: {
		id: 'lesson-1',
		name: 'Fractions',
		course: { code: 'MATH-3' },
	},
	metrics: {
		totalQuestions: 20,
		correctQuestions: 16,
		xpEarned: 150,
	},
	time: {
		activeMs: 1200000, // 20 minutes total active time
		inactiveMs: 120000, // 2 minutes total paused time
	},
	runId: savedProgress.runId,
})

API reference

user

object

required

Student identity. Provide email (required) and optionally timebackId. See Identity for how users are resolved.

activity

object

required

Activity identity.

Show child attributes

string

required

Unique activity identifier

name

string

required

Human-readable activity name

course

object

required

Course reference — provide code (course code), or subject and grade

metrics

object

required

Completion metrics.

Show child attributes

xpEarned

number

required

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

totalQuestions

number

Total questions in the activity

correctQuestions

number

Questions answered correctly

masteredUnits

number

Units mastered

pctComplete

number

Completion percentage, 0-100

time

object

Optional time data. Include when the backend tracks accumulated session time.

Show child attributes

startedAt

string

ISO 8601 timestamp of when the activity was first started

endedAt

string

ISO 8601 timestamp of when the activity was completed

activeMs

number

Total active milliseconds across all sessions

inactiveMs

number

Total inactive (paused) milliseconds across all sessions

runId

string

UUID correlating this completion with frontend heartbeats. Should match the runId persisted when the activity was started on the client.

totalQuestions and correctQuestions must be provided together.If you provide one, you must provide the other.

Best practices

Persist runId immediately after activity.start()

The runId is the correlation key between frontend heartbeats and backend completion. Save it to your database as soon as the activity starts.

Use a fresh runId for new attempts after completion

When a student starts a new attempt of a previously completed activity, do not reuse the old runId. Omit it from activity.start() to generate a fresh one — otherwise new heartbeats would be incorrectly correlated with the old completion event.

Only call activity.end() without args on the frontend

Completion should come from the backend via timeback.activity.record(). The frontend should always use activity.end() (no metrics) to flush time data only.

Getting Started

CLI

SDK

API Clients

Reference

Architecture

Frontend

Starting a session

Resuming a session

Ending a session

Framework examples

Backend

Basic usage

With time data (advanced)

API reference

Best practices

Next steps

Single-session activities

Identity

Getting Started

CLI

SDK

API Clients

Reference

​Architecture

​Frontend

​Starting a session

​Resuming a session

​Ending a session

​Framework examples

​Backend

​Basic usage

​With time data (advanced)

​API reference

​Best practices

​Next steps

Single-session activities

Identity

Architecture

Frontend

Starting a session

Resuming a session

Ending a session

Framework examples

Backend

Basic usage

With time data (advanced)

API reference

Best practices

Next steps