Reference - Timeback Docs (Beta)

Client

`activity.current`

The currently active activity instance, or null if none is running.

`activity.start(params)`

Creates and starts a new activity tracker. Heartbeats begin immediately unless time: false is passed.

Only one activity can be active at a time. Calling start() while an activity is already running throws an error. Await end() on the current activity before starting the next one.

string

required

Activity slug: a stable, URL-safe identifier for the learning object (e.g. "fractions-with-like-denominators"). Used to construct the canonical activity URL in Caliper events.

string

required

Human-readable display name (e.g. "Fractions with Like Denominators"). Sent as object.activity.name in Caliper events.

object

required

Course selector: must match a course in timeback.config.json. Either { subject, grade } or { code }.

string

UUID for correlating events across sessions. Arbitrary strings are rejected by the HTTP handlers. If omitted, the SDK generates a new UUID. Pass the same runId when resuming a stateful activity to link heartbeats with the eventual completion event.

object | false

Time tracking configuration. All fields are optional: defaults work well for most apps.

Set to false to disable client-side time tracking entirely. When disabled, no heartbeats are sent, no visibility handlers are registered, and end() skips the final time flush. Use this when e.g. time is managed server-side.

Show time options

number

default:"15000"

Interval in milliseconds between automatic heartbeat flushes.

boolean

default:"true"

Pause time tracking when the browser tab is not visible.

boolean

default:"true"

Flush accumulated time immediately when the tab becomes hidden.

boolean

default:"true"

Attempt a best-effort flush on page unload via sendBeacon or fetch({ keepalive: true }).

number | null

default:"600000"

Stop tracking after this many milliseconds of hidden time (default 10 minutes). Prevents counting abandoned-tab time. Set to Infinity to disable. In the reviewed implementation, null is replaced by the default by a nullish-coalescing expression and does not disable the timeout.

number

default:"0"

Number of retry attempts for failed heartbeat sends. 0 means no retry (default). Retries follow the configured retryDelaysMs schedule.

number[]

default:"[100, 300, 1000]"

Delay schedule (in milliseconds) between retry attempts. Each index corresponds to the delay before that attempt. If more attempts than entries, the last value is reused.

(error, context) => void

Called when a time-spent flush or completion submission fails. For regular heartbeats, fires after the configured retries are exhausted. Completion sends and page-exit sends do not use that retry schedule. Time-spent errors are non-fatal: the SDK continues tracking. Completion errors (from end()) are also surfaced here before being re-thrown.

Show callback signature

Error

The error that occurred.

'timeSpent' | 'completion'

Which operation failed. Aligns with Caliper event types:

TimeSpentEvent
ActivityCompletedEvent

string

The activity slug passed to activity.start().

string

The runId for this activity instance.

() => void

Called when the activity is paused, either explicitly via pause() or automatically when the hidden timeout fires.

() => void

Called when the activity resumes, either via resume() or when the user returns after a hidden timeout.

(elapsedMs: number) => void

Called after a heartbeat request succeeds, or after the browser accepts a page-exit beacon for delivery. Beacon acceptance does not confirm server storage. The argument is the active milliseconds in that window.

Examples

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

const activity = timeback.activity.start({
    id: 'lesson-1',
    name: 'Intro to Fractions',
    course: { subject: 'Math', grade: 3 },
    time: {
        flushIntervalMs: 30000, // 30 seconds
        visibilityAware: false, // track even when tab is hidden
    },
})

const activity = timeback.activity.start({
    id: 'lesson-1',
    name: 'Intro to Fractions',
    course: { subject: 'Math', grade: 3 },
    onError: (err, ctx) => {
        console.warn(`Activity ${ctx.type} failed:`, err.message)
    },
    onPause: () => showPausedOverlay(),
    onResume: () => hidePausedOverlay(),
    onFlush: ms => updateTimeDisplay(ms),
})

const activity = timeback.activity.start({
    id: 'lesson-1',
    name: 'Intro to Fractions',
    course: { subject: 'Math', grade: 3 },
    time: {
        retryAttempts: 3,
        retryDelaysMs: [100, 300, 1000],
    },
    onError: (err, ctx) => {
        // Only fires after all retries are exhausted
        console.warn(`${ctx.type} failed after retries:`, err.message)
    },
})

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

// No heartbeats are sent — end() sends completion only
await activity.end({ xpEarned: 100 })

Activity instance

The object returned by activity.start().

Properties

string

The activity slug passed to start().

Date

When the activity was started.

boolean

Whether the activity is currently paused.

boolean

Whether end() has completed successfully.

Once true, the activity is no longer active and a new one can be started.

string

Unique identifier correlating heartbeats and completion events for this run.

number

Cumulative locally measured active time, including windows whose sends failed, plus the current window. This is not a server-confirmed total.

number

Active time for the current heartbeat window only. Resets to 0 after each flush.

Methods

Flushes accumulated time, then stops heartbeats until resume() is called. Fires onPause if provided.

Starts a fresh tracking window and restarts heartbeats. Fires onResume if provided.

Promise<void>

Attempt to flush accumulated time to the server. Failures are reported to onError and swallowed, so a resolved promise is not proof of delivery. No-op when time tracking is disabled or the activity is paused. Serialized — only one flush can be in flight at a time.

activity.pause() // Flushes time, stops heartbeats
activity.resume() // Fresh window, restarts heartbeats

onPause and onResume callbacks also fire for automatic state changes like hidden timeouts — use them to keep your UI in sync without polling isPaused.

`activity.end(data?)`

Ends the activity. Attempts a final time flush when automatic time tracking is enabled. If completion data is provided, also sends an ActivityCompletedEvent.

// Time-only flush (no completion recorded)
await activity.end()

// With completion
await activity.end({
    xpEarned: 80,
    totalQuestions: 10,
    correctQuestions: 8,
    pctComplete: 100,
})

If the completion call fails, the activity remains usable so the caller can retry. A heartbeat failure alone does not reject end(). onError fires with { type: 'completion' } before the error is re-thrown.

const activity = timeback.activity.start({
    id: 'lesson-1',
    name: 'Fractions',
    course: { subject: 'Math', grade: 3 },
    onError: (err, ctx) => {
        if (ctx.type === 'completion') showRetryButton()
    },
})

Completion data

number

required

App-supplied XP for this activity. Follow the agreed XP policy; the SDK cannot infer it from time spanning multiple sessions.

number

Total questions in the activity. Must be paired with correctQuestions.

number

Questions answered correctly. Must be paired with totalQuestions.

number

Number of new units (lessons) the student mastered during this activity. This is an incremental count, not a cumulative total. The server sums these across submissions and divides by totalLessons to auto-compute pctComplete when it is omitted. See Course progress for details.

number

Course completion percentage (0—100). If omitted and masteredUnits is provided, the server auto-computes this from EduBridge enrollment analytics when available. The browser submission handler clamps explicit values to 0–100; the TypeScript server recording API rejects values outside that range.

The reviewed browser implementation does not read end({ time: ... }), even though the exported type contains a time field. Do not use it for offline time imports. Report explicit time through the server activity.record({ time: ... }) API below, and disable automatic heartbeats for the same time interval.

totalQuestions and correctQuestions must be provided together.

If you provide one, you must provide the other.

Server

`timeback.activity.record(params)`

Records an activity completion from the backend. Sends an ActivityCompletedEvent to the Caliper API after resolving the user and synced course. Gradebook and XP processing continues downstream; this promise does not acknowledge those outcomes. At 100% progress an additional mastery-completion write is attempted; its failures are logged rather than propagated.

The optional time event is sent after completion, in a separate request. Failure can leave partial success; your app must reconcile retries. A shared runId correlates events and does not make these writes one transaction.

See the server adapter docs for setup.

object

required

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

object

required

Activity identity.

Show child attributes

string

required

Unique activity identifier

string

required

Human-readable activity name

object

required

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

object

required

Completion metrics.

Show child attributes

number

required

App-supplied XP following the agreed XP policy. The reviewed TypeScript input permits negative XP deductions; the Python validator rejects negative XP.

number

Total questions in the activity

number

Questions answered correctly

number

Number of new units (lessons) mastered during this activity. This is incremental, not cumulative. See Course progress.

number

Course completion percentage (0—100). Auto-computed from masteredUnits when omitted. See Course progress.

object

Optional time data. Include when the backend tracks accumulated session time — for example, when the frontend uses time: false, or for offline sync and batch imports.

Show child attributes

string

ISO 8601 timestamp of when the activity was first started

string

ISO 8601 timestamp of when the activity was completed

number

Total active milliseconds across all sessions

number

Total inactive (paused) milliseconds across all sessions

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.

Examples

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,
})

With time data

Only include time when the frontend uses time: false, meaning your server owns time tracking. Do not pass time here if the frontend is sending heartbeats (the default), or time will be double-counted.

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,
    },
    time: {
        activeMs: 1200000, // 20 minutes total active time
        inactiveMs: 120000, // 2 minutes total paused time
    },
    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,
    },
    "time": {
        "active_ms": 1200000,  # 20 minutes total active time
        "inactive_ms": 120000, # 2 minutes total paused time
    },
    "run_id": saved_progress.run_id,
})

​Client

​activity.current

​activity.start(params)

​Examples

​Activity instance

​Properties

​Methods

​activity.end(data?)

​Completion data

​Server

​timeback.activity.record(params)

​Examples

​With time data

Client

`activity.current`

`activity.start(params)`

Examples

Activity instance

Properties

Methods

`activity.end(data?)`

Completion data

Server

`timeback.activity.record(params)`

Examples

With time data