Skip to main content
Custom Activities let you record learning sessions, measure time spent, and report completion metrics to the Timeback platform. You own your content and learning logic, while the SDK handles time tracking and event reporting.
This section covers the SDK implementation for Custom Activities (Level 1). For the step-by-step setup guide, see Integrating existing apps. If you want Timeback to manage the lesson engine, see Managed Lessons.

​
When to use

Custom ActivitiesManaged Lessons
ContentYour own content and logicTimeback’s course builder
Platform roleTime and completion reportingSequencing, scoring, and XP
Integration levelLevel 1Level 2

​
Choose your model

The SDK supports two activity models. Both use the same continuous time tracking under the hood; the difference is in how completion is handled.

Single-session

Completed in one sitting. Client tracks time and reports completion.

Stateful

Spans multiple sessions. Client tracks time, server records completion.
Not sure which to choose? See Activity Models for a conceptual comparison.

​
How time tracking works

Both models use continuous heartbeat-based time tracking. Rather than accumulating time and reporting it once at the end, the SDK sends periodic updates throughout the session. Each update reconciles a time window, reporting how many milliseconds were active and how many were inactive. Heartbeats begin automatically when you call activity.start() and repeat at a regular interval (default 15s), and are sent as TimeSpentEvents.

​
Why this matters

  • Maximum 15s of data loss if a student closes the tab unexpectedly (vs. losing the entire session)
  • Accurate per-window timestamps: each event represents the actual engagement window
  • Visibility-aware: time is only counted when the tab is in the foreground

​
Abandoned tab detection

If a tab stays hidden for an extended period (default 10 minutes), the SDK stops heartbeats entirely. When the student returns, tracking resets from a clean slate. This prevents counting hours of abandoned-tab time.

​
Event correlation with runId

Every activity is identified by a runId, a unique identifier generated at activity.start(). All heartbeats, as well as the final completion event, share the same runId, which allows downstream systems to correlate time-spent data with completion results. For stateful activities, the runId is persisted and reused when the student resumes, so heartbeats from different sessions are still correlated with the same completion event.

​
Pause and resume

Both models support pause and resume. Paused time is not counted as active. The SDK distinguishes active and inactive milliseconds in every heartbeat. When paused, the SDK flushes accumulated time and stops heartbeats. On resume, it starts a fresh tracking window. Optional onPause and onResume callbacks fire on both explicit calls and automatic state changes like hidden timeouts. See pause() and resume() in the reference for usage.

​
Configuration

Custom activity tracking requires a Caliper sensor URL in your timeback.config.json.
See the configuration reference for sensor resolution rules and environment overrides.

​
Next Steps

Single-session

Client-driven activities completed in one sitting

Stateful

Multi-session activities with server-side completion

Reference

Parameters, properties, methods, and callbacks

Configuration

Full timeback.config.json reference

Getting started

Step-by-step setup guide for integrating existing apps