Skip to main content

​
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

​
name
string
required
Display name for your application.
​
sensor
string (URL)
Default Caliper sensor endpoint URL for activity tracking. Can be overridden per-course. See Sensor resolution.
​
launchUrl
string (URL)
Default LTI launch URL. Can be overridden per-course.
​
defaults
CourseDefaults
Default values applied to all courses.
​
courses
CourseConfig[]
required
Array of course definitions (minimum 1). See Course properties.
​
studio
object
Studio-specific configuration.

​
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.
​
subject
TimebackSubject
required
Subject area. One of: "Math", "Reading", "Language", "Vocabulary", "Writing", "Science", "Social Studies", "FastMath", "None", "Other".
​
grade
number
Grade level. -1 for Pre-K, 0 for Kindergarten, 1—12 for grades, 13 for AP. Required if courseCode is not provided.
​
courseCode
string
Unique course identifier (e.g., "MATH-3"). Required if grade is not provided.
​
level
string
Course level description (e.g., "Elementary", "AP", "Honors").
​
sensor
string (URL)
Caliper sensor endpoint URL for this course. Overrides the root sensor.
​
launchUrl
string (URL)
LTI launch URL for this course. Overrides the root launchUrl.
​
ids
object
Environment-specific course IDs, populated automatically by timeback sync.
​
metadata
CourseMetadata
Course metadata including publication status, goals, and metrics. See Course metadata.
​
overrides
object
Per-environment overrides. See Overrides.

​
Course metadata

All metadata fields are optional. Metadata set in defaults.metadata is merged into every course.
​
courseType
string
Course classification: "base", "hole-filling", or "optional".
​
isSupplemental
boolean
Whether this course is supplemental to a base course.
​
isCustom
boolean
Whether this is a custom course generated for an individual student.
​
publishStatus
string
Publication state: "draft", "testing", "published", or "deactivated".
​
contactEmail
string
Contact email for course issues.
​
primaryApp
string
Primary application identifier.
​
goals
CourseGoals
Daily learning goals for students in this course.
​
metrics
CourseMetrics
Aggregate course metrics.

​
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):
  1. defaults (lowest priority)
  2. Course base values
  3. overrides[env] (highest priority)
FieldMerge strategy
levelReplaced entirely
sensorReplaced entirely
launchUrlReplaced entirely
metadataMerged — nested goals and metrics are deep-merged

​
Sensor resolution

Each course must have a resolvable sensor. The SDK checks these sources in order:
  1. course.overrides[env].sensor
  2. course.sensor
  3. Root sensor
  4. 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