Stateful activities - Timeback Docs (Beta)

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 or Backend	Heartbeats or `time: false`
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. The SDK HTTP handlers and server recording API require a UUID. Reuse an assignment ID only if it is a valid UUID; otherwise store a separate UUID for the attempt. 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 })

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

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: your app saves progress independently of the SDK. Calling activity.end() attempts a final time flush and closes this browser tracker without a completion event. To resume, load saved progress from your app and create a new tracker with the same runId. Tab closure does not guarantee a successful final save or heartbeat.

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

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

Loading and lifecycle

Create or load the attempt in your authenticated backend before starting its browser tracker. Persist the UUID with the attempt, and return it with the saved answers. This avoids losing the correlation ID if a browser closes between start() and a later save. Use the lifecycle guidance in Single-session activities: wait for client initialization and verification, serialize end() and start(), and cancel pending progress loads when a screen unmounts. The SDK does not provide saveProgress or loadProgress; both are your application APIs.

Server-managed time

If your server already tracks time (e.g. from request logs or its own session model), you can disable heartbeats entirely by passing time: false. The client still provides the activity.end() ergonomics, but no TimeSpentEvents are sent.

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

// No heartbeats during the session — end() closes the activity without sending time data
await activity.end()

When using time: false, the server must report time via the time parameter in timeback.activity.record(). Do not use both heartbeats and server-side time — this will double-count. See the server reference for details.

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 after resolving the user and synced course. Downstream gradebook and XP processing is asynchronous; a successful SDK call does not prove that it has completed. At 100% progress the SDK also attempts a mastery-completion gradebook entry; failures of that extra write are logged without failing the request. Pass the same runId from the frontend to correlate heartbeats with the completion event.

See the reference for full parameter documentation.

await timeback.activity.record({
    user: { email: 'student@example.com' },
    activity: {
        id: 'lesson-1',
        name: 'Fractions',
        course: { code: 'MATH-3' },
    },
    metrics: {
        totalQuestions: 20,
        correctQuestions: 16,
        xpEarned: 150,
        masteredUnits: 2,
        pctComplete: 100,
    },
    runId: savedProgress.runId,
})

await timeback.activity.record({
    "user": {"email": "student@example.com"},
    "activity": {
        "id": "lesson-1",
        "name": "Fractions",
        "course": {"code": "MATH-3"},
    },
    "metrics": {
        "total_questions": 20,
        "correct_questions": 16,
        "xp_earned": 150,
        "mastered_units": 2,
        "pct_complete": 100,
    },
    "run_id": saved_progress.run_id,
})

Only include time when the frontend uses time: false. If heartbeats are active (the default), the platform already has the time data — passing time here would double-count. See the full server reference for all parameters.

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.

Next steps

Single-session activities

Simpler model for one-sitting activities

Reference

Full parameter and method reference

Identity

Authentication setup for resolving users

​Architecture

​Frontend

​Starting a session

​Resuming a session

​Ending a session

​Loading and lifecycle

​Server-managed time

​Backend

​Best practices

​Next steps

Single-session activities

Reference

Identity

Architecture

Frontend

Starting a session

Resuming a session

Ending a session

Loading and lifecycle

Server-managed time

Backend

Best practices

Next steps