Skip to main content

​
Overview

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

​
Location

The CLI creates timeback.config.json 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",
	"defaults": {
		"level": "Elementary"
	},
	"courses": [
		{
			"subject": "Math",
			"grade": 3,
			"courseCode": "MATH-3",
			"level": "Elementary",
			"sensor": "https://my-app.example.com/sensors/math",
			"metadata": {
				"publishStatus": "testing",
				"owner": "math-team"
			},
			"goals": {
				"dailyXP": 100,
				"weeklyActivities": 5
			},
			"metrics": {
				"xpPerQuestion": 10,
				"bonusMultiplier": 1.5
			},
			"overrides": {
				"staging": {
					"level": "Staging",
					"sensor": "https://staging.my-app.example.com/sensors/math",
					"metadata": {
						"publishStatus": "draft"
					}
				},
				"production": {
					"metadata": {
						"publishStatus": "published"
					}
				}
			}
		}
	]
}

​
Root Properties

​
name
string
required
Your application name.
​
sensor
string
Default Caliper sensor URL for activity tracking. Can be overridden per-course.
​
defaults
object
Default values applied to all courses. Supports level, metadata, goals, and metrics.
​
courses
CourseConfig[]
required
Array of course definitions. See Course Properties below.

​
Course Properties

​
subject
string
required
Subject name (e.g., “Math”, “ELA”, “Science”).
​
grade
number | 'K'
required
Grade level (1-12 or “K” for kindergarten).
​
courseCode
string
required
Unique course identifier.
​
level
string
Course level description.
​
sensor
string
Caliper sensor URL for this course. Overrides root sensor.
​
metadata
object
Custom metadata object. Common fields include publishStatus (“draft”, “testing”, “published”), owner, and version.
​
goals
object
Learning goals configuration with fields like dailyXP, weeklyXP, dailyActivities, weeklyActivities.
​
metrics
object
XP and scoring configuration with fields like xpPerQuestion, xpPerMinute, bonusMultiplier, masteryThreshold.
​
overrides
object
Environment-specific overrides keyed by staging or production. Each override can contain any course property to override for that environment.

​
Goals Example

{
	"goals": {
		"dailyXP": 100,
		"weeklyXP": 500,
		"dailyActivities": 3,
		"weeklyActivities": 15
	}
}

​
Metrics Example

{
	"metrics": {
		"xpPerQuestion": 10,
		"xpPerMinute": 2,
		"bonusMultiplier": 1.5,
		"masteryThreshold": 0.8
	}
}

​
Overrides Example

{
	"overrides": {
		"staging": {
			"level": "Staging Level",
			"sensor": "https://staging.example.com/sensor"
		},
		"production": {
			"level": "Production Level"
		}
	}
}

​
Override Merge Rules

Overrides are merged in this order:
  1. defaults (lowest priority)
  2. Course base values
  3. overrides[env] (highest priority)

​
Merge Behavior

​
level, sensor
string
Replaced entirely by override value
​
metadata
object
Shallow merged (properties combined)
​
goals
object
Deep merged with base values
​
metrics
object
Deep merged with base values

​
Sensor Resolution

The SDK resolves sensors in this order:
  1. course.overrides[env].sensor
  2. course.sensor
  3. Root sensor

​
Next Steps

Environment

Environment configuration

CLI resources

Push and pull configurations