> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timeback.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stateful activities
> Track activities that students complete across multiple sessions
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](/beta/build-on-timeback/sdk/activity-tracking/intro).
## Architecture
Stateful activities split responsibility between frontend and backend:
| Responsibility | Owner | Mechanism |
| - | - | - |
| **Time tracking** | Frontend or Backend | [Heartbeats](#starting-a-session) or [`time: false`](#server-managed-time) |
| **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.
```mermaid theme={null}
graph TD
DB[("Your Database")]
subgraph S1 [Session 1 - Monday]
A["activity.start()"] -->|generates runId| B["Heartbeats"]
B --> C["activity.end()"]
end
C -->|save runId| DB
DB -->|load runId| E
subgraph S2 [Session 2 - Wednesday]
E["activity.start with runId"] --> F["Heartbeats"]
F --> G["activity.end()"]
end
DB -->|load runId| H
subgraph S3 [Server]
H["timeback.activity.record with runId"]
end
B -- TimeSpentEvent --> I["Caliper API"]
C -- TimeSpentEvent --> I
F -- TimeSpentEvent --> I
G -- TimeSpentEvent --> I
H -- ActivityCompletedEvent --> I
style A fill:#3b82f6,stroke:#2563eb,color:#fff
style E fill:#3b82f6,stroke:#2563eb,color:#fff
style H fill:#10b981,stroke:#059669,color:#fff
style I fill:#8b5cf6,stroke:#7c3aed,color:#fff
style DB fill:#f59e0b,stroke:#d97706,color:#fff
```
## 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
```typescript theme={null}
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](/beta/build-on-timeback/sdk/activity-tracking/reference#activity-start-params) for full parameter documentation including time options and callbacks.
### Resuming a session
```typescript theme={null}
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](/beta/build-on-timeback/sdk/activity-tracking/single-session): 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.
```typescript theme={null}
await activity.end() // Flushes time, no completion
```
The frontend **always** calls `activity.end()` without metrics. Completion is recorded by the
[server](#server-recording-completion).
### 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](/beta/build-on-timeback/sdk/activity-tracking/single-session#framework-integration): 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 `TimeSpentEvent`s are sent.
```typescript theme={null}
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](/beta/build-on-timeback/sdk/activity-tracking/reference#server) 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`](/beta/build-on-timeback/reference/events#activitycompletedevent) to the Caliper API after resolving the user and synced course. Downstream gradebook and [XP](/beta/about-timeback/concepts/xp-system) 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](/beta/build-on-timeback/sdk/activity-tracking/reference#timeback-activity-record-params) for full parameter documentation.
```typescript TypeScript theme={null}
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,
})
```
```python Python theme={null}
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`](#server-managed-time). If heartbeats
are active (the default), the platform already has the time data — passing `time` here would
double-count. See the full [server reference](/beta/build-on-timeback/sdk/activity-tracking/reference#server)
for all parameters.
## Best practices
The `runId` is the correlation key between frontend heartbeats and backend completion. Save
it to your database as soon as the activity starts.
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.
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
Simpler model for one-sitting activities
Full parameter and method reference
Authentication setup for resolving users