Single-session activities

Single-session activities are the simplest model: a student starts and completes an activity in one browser session. The client SDK tracks time automatically and reports completion when the student finishes.

For info on shared concepts, see the Custom Activities overview.

How it works

Once started, the SDK sends periodic TimeSpentEvents throughout the session. When the student finishes, the SDK sends one final TimeSpentEvent followed by an ActivityCompletedEvent. All events share the same runId for correlation.

Starting an activity

Every single-session activity starts the same way:

const activity = timeback.activity.start({
	id: 'intro-to-fractions',
	name: 'Introduction to Fractions',
	course: { subject: 'Math', grade: 3 }, // from timeback.config.json
})

// Student engages... (heartbeats emit automatically)

See the reference for full parameter documentation including time options, callbacks, and runId.

Ending an activity

How you end an activity depends on whether the student completed the activity. In both cases, accumulated time data is flushed. The difference is whether a completion result is also recorded.

With completion

When a student finishes, call activity.end() with completion metrics:

Flushes a final heartbeat (TimeSpentEvent)
Submits the completion (ActivityCompletedEvent)

await activity.end({
	xpEarned: number,
	totalQuestions: number?,
	correctQuestions: number?,
	masteredUnits: number?,
})

See the reference for full completion data documentation.

Without completion

Call activity.end() without arguments to flush time data only; in this case, no completion event is recorded.

Flushes a final heartbeat (TimeSpentEvent)
Stops the heartbeat timer

await activity.end()

There are two reasons to end without completion:

Cleanup: the component unmounts before the student finishes (e.g. navigating away mid-activity). You want to flush accumulated time without recording a result.
Stateful activities: the activity spans multiple sessions, so the client only tracks time per visit. Completion is recorded by the server when the student eventually finishes.

Framework integration

React
Vue
Svelte
Solid

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

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

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

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

		return () => {
			// Cleanup flush: time only, do not mark completion on unmount.
			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(() => {
	if (timeback.value) {
		activity.value = timeback.value.activity.start({
			id: props.lessonId,
			name: props.lessonName,
			course: { subject: 'Math', grade: 3 },
		})
	}
})

onUnmounted(() => {
	// Cleanup flush: do not mark completion on unmount.
	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(() => {
		if ($timeback) {
			activity = $timeback.activity.start({
				id: lessonId,
				name: lessonName,
				course: { subject: 'Math', grade: 3 },
			})
		}
	})

	onDestroy(() => {
		// Cleanup flush: do not mark completion on unmount.
		void activity?.end()
	})
</script>

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

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

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

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

	onCleanup(() => {
		// Cleanup flush: do not mark completion on unmount.
		void activity?.end()
	})

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

Best practices

Start activities in useEffect/onMount

Always start activities in lifecycle hooks to ensure proper cleanup.

Flush time on cleanup, complete on user action

Use activity.end() (no args) in cleanup functions. Only call activity.end(metrics) when the student has actually finished the activity.

Handle missing timeback client

Check if the timeback client exists before creating activities (it may be null if not authenticated).

Use meaningful activity IDs

Use stable, unique IDs that identify the specific lesson or content piece.

Next steps

Stateful activities

Multi-session activities with server-side completion

Reference

Parameters, properties, methods, and callbacks

Getting Started

CLI

SDK

Reference

How it works

Starting an activity

Ending an activity

With completion

Without completion

Framework integration

Best practices

Next steps

Stateful activities

Reference

Getting Started

CLI

SDK

Reference

​How it works

​Starting an activity

​Ending an activity

​With completion

​Without completion

​Framework integration

​Best practices

​Next steps

Stateful activities

Reference

How it works

Starting an activity

Ending an activity

With completion

Without completion

Framework integration

Best practices

Next steps