Configuration

Overview

The timeback.config.json file configures your Timeback integration, defining courses, sensors, and environment-specific overrides.

Location

This file is generated by timeback init during project setup and typically lives in your project root:

my-app

timeback.config.json

package.json

src

Schema

Use the JSON schema for autocompletion and validation:

timeback.config.json

{
	"$schema": "https://timeback.dev/schema.json"
}

Complete example

timeback.config.json

{
	"$schema": "https://timeback.dev/schema.json",
	"name": "My Learning App",
	"sensor": "https://my-app.example.com/sensors/default",
	"launchUrl": "https://my-app.example.com/start",
	"defaults": {
		"level": "Elementary"
	},
	"courses": [
		{
			"subject": "Math",
			"grade": 3,
			"courseCode": "MATH-3",
			"level": "Elementary",
			"sensor": "https://my-app.example.com/sensors/math",
			"launchUrl": "https://my-app.example.com/math",
			"metadata": {
				"courseType": "base",
				"publishStatus": "testing",
				"contactEmail": "math-team@example.com",
				"goals": {
					"dailyXp": 100,
					"dailyLessons": 3,
					"dailyActiveMinutes": 25,
					"dailyAccuracy": 80,
					"dailyMasteredUnits": 2
				},
				"metrics": {
					"totalXp": 2500,
					"totalLessons": 42,
					"totalGrades": 1
				}
			},
			"overrides": {
				"staging": {
					"level": "Staging",
					"sensor": "https://staging.my-app.example.com/sensors/math",
					"metadata": {
						"publishStatus": "draft",
						"metrics": {
							"totalLessons": 10
						}
					}
				},
				"production": {
					"metadata": {
						"publishStatus": "published"
					}
				}
			}
		}
	]
}

Root properties

string

required

Display name for your application.

string (URL)

Default Caliper sensor endpoint URL for activity tracking. Can be overridden per-course. See Sensor resolution.

string (URL)

Default LTI launch URL. Can be overridden per-course.

CourseDefaults

Default values applied to all courses.

Show defaults fields

string

Default course code.

string

Default course level (e.g., "Elementary", "AP", "Honors").

CourseMetadata

Default metadata applied to all courses. See Course metadata.

CourseConfig[]

required

Array of course definitions (minimum 1). See Course properties.

object

Studio-specific configuration.

Show studio fields

boolean

default:"true"

Enable anonymous usage telemetry.

Course properties

Each course must have either grade or courseCode (or both). All (subject, grade) pairs must be unique, and all courseCode values must be unique.

TimebackSubject

required

Subject area. One of: "Math", "Reading", "Language", "Vocabulary", "Writing", "Science", "Social Studies", "FastMath", "None", "Other".

number

Grade level. -1 for Pre-K, 0 for Kindergarten, 1—12 for grades, 13 for AP. Required if courseCode is not provided.

string

Unique course identifier (e.g., "MATH-3"). Required if grade is not provided.

string

Course level description (e.g., "Elementary", "AP", "Honors").

string (URL)

Caliper sensor endpoint URL for this course. Overrides the root sensor.

string (URL)

LTI launch URL for this course. Overrides the root launchUrl.

object

Environment-specific course IDs, populated automatically by timeback sync.

Show ids fields

string

Course ID in the staging environment.

string

Course ID in the production environment.

CourseMetadata

Course metadata including publication status, goals, and metrics. See Course metadata.

object

Per-environment overrides. See Overrides.

Show overrides fields

CourseEnvOverrides

Overrides applied in the staging environment.

CourseEnvOverrides

Overrides applied in the production environment.

Course metadata

All metadata fields are optional. Metadata set in defaults.metadata is merged into every course.

string

Course classification: "base", "hole-filling", or "optional".

boolean

Whether this course is supplemental to a base course.

boolean

Whether this is a custom course generated for an individual student.

string

Publication state: "draft", "testing", "published", or "deactivated".

string

Contact email for course issues.

string

Primary application identifier.

CourseGoals

Daily learning goals for students in this course.

Show goals fields

number (positive integer)

Target XP to earn per day.

number (positive integer)

Target lessons to complete per day.

number (positive integer)

Target active learning minutes per day.

number (0--100)

Target accuracy percentage per day.

number (positive integer)

Target units to master per day.

CourseMetrics

Aggregate course metrics.

Show metrics fields

number (positive integer)

Total XP available in the course.

number (positive integer)

required

Total number of lessons in the course. Used as the denominator when the server auto-computes pctCompleteApp from masteredUnits.

number (positive integer)

Total grade levels covered by this course.

Course metadata example

timeback.config.json (course excerpt)

{
	"metadata": {
		"courseType": "base",
		"publishStatus": "published",
		"contactEmail": "math-team@example.com",
		"goals": {
			"dailyXp": 100,
			"dailyLessons": 3,
			"dailyActiveMinutes": 25
		},
		"metrics": {
			"totalXp": 2500,
			"totalLessons": 42,
			"totalGrades": 1
		}
	}
}

Overrides

Each environment override can contain level, sensor, launchUrl, and metadata. Metadata in overrides is merged with the base metadata — it does not replace it.

timeback.config.json (course excerpt)

{
	"overrides": {
		"staging": {
			"level": "Staging",
			"sensor": "https://staging.example.com/sensors/math",
			"metadata": {
				"publishStatus": "draft",
				"metrics": {
					"totalLessons": 10
				}
			}
		},
		"production": {
			"metadata": {
				"publishStatus": "published"
			}
		}
	}
}

Merge behavior

Overrides are merged in this order (highest priority last):

defaults (lowest priority)
Course base values
overrides[env] (highest priority)

Field	Merge strategy
`level`	Replaced entirely
`sensor`	Replaced entirely
`launchUrl`	Replaced entirely
`metadata`	Merged — nested `goals` and `metrics` are deep-merged

Sensor resolution

Each course must have a resolvable sensor. The SDK checks these sources in order:

course.overrides[env].sensor
course.sensor
Root sensor
Derived from launchUrl origin (falls back to course.launchUrl, then root launchUrl)

If no sensor can be resolved, config validation fails.

Next steps

Environment

Environment variables and credentials

Course progress

How totalLessons and masteredUnits drive pctCompleteApp

CLI resources

Push and pull configurations

Events

Caliper event schemas

Getting Started

CLI

SDK

Reference

Overview

Location

Schema

Complete example

Root properties

Course properties

Course metadata

Course metadata example

Overrides

Merge behavior

Sensor resolution

Next steps

Environment

Course progress

CLI resources

Events

​Overview

​Location

​Schema

​Complete example

​Root properties

​Course properties

​Course metadata

​Course metadata example

​Overrides

​Merge behavior

​Sensor resolution

​Next steps

Environment

Course progress

CLI resources

Events

Overview

Location

Schema

Complete example

Root properties

Course properties

Course metadata

Course metadata example

Overrides

Merge behavior

Sensor resolution

Next steps