Skip to main content
This guide walks through Level 1 integration: add event tracking and rostering to your existing app. You keep your own content and learning logic — Timeback handles the rest. Once you have staging credentials, this takes about 15 minutes.
Timeback apps must follow strict rules.Read how we evaluate apps and the non-negotiables before you start.
1

Verify you have staging credentials

If you do not have credentials yet, complete first steps first. Confirm you have your staging client ID and secret from the Developer Portal.You will need these credentials for the CLI and SDK.
2

Install the CLI

Install the Timeback CLI:
curl -fsSL https://timeback.dev/cli | bash
Or install via a package manager:
npm install -g timeback
Verify the installation:
timeback --version
3

Initialize your project

Run the interactive timeback init command in your project root:
timeback init
The CLI guides you through setup:
  1. Mode: Initialize a new app or import an existing one
  2. App name: Enter your application name
  3. Subjects: Select subjects your app covers
  4. Grade levels: Select grade levels
  5. Launch URL: Your app’s entry point
This creates a timeback.config.json file in your project:
timeback.config.json
{
	"name": "My Learning App",
	"launchUrl": "https://my-app.example.com",
	"courses": [
		{
			"subject": "Math",
			"grade": 3,
			// ...
		}
	]
}
See Configuration for the full schema reference.
4

Push to Timeback

Push your configuration to staging:
timeback resources push # defaults to staging
This creates or updates your courses in Timeback.Use --dry-run to preview changes:
timeback resources push --dry-run
See CLI: Resources for more commands.
5

Emit learning events

Start emitting learning events from your app. You have two options:Option A: Use the SDK (recommended for web apps)
npm install @timeback/sdk

import { createTimeback } from '@timeback/sdk'

const timeback = await createTimeback({
	env: 'staging',
	api: {
		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
	},
})

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

// When complete
await activity.end({
	totalQuestions: 10,
	correctQuestions: 8,
	xpEarned: 80,
})
See SDK Overview for full documentation and Environment for configuration options.Option B: Use the API directly
npm install @timeback/caliper

import { CaliperClient } from '@timeback/caliper'

const caliper = new CaliperClient({
	env: 'staging',
	auth: {
		clientId: process.env.CALIPER_CLIENT_ID!,
		clientSecret: process.env.CALIPER_CLIENT_SECRET!,
	},
})

await caliper.events.sendActivity(sensorUrl, activityData)
See API Clients for direct API access.

​
What to expect next

After completing these steps:
  1. Verify events are flowing using Studio
  2. Complete the Level 1 checklist
  3. Submit evidence for review
  4. Receive feedback and production credentials upon approval

CLI: Credentials

Manage multiple credential sets

CLI: Resources

Push, pull, and sync courses

SDK Overview

Full-stack SDK for web apps

Integration levels

See Level 1 requirements in detail