> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timeback.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Existing apps

> Level 1 integration for apps that already exist

This guide walks through [Level 1 integration](/beta/build-on-timeback/integration-levels#level-1-minimal-viable): 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.

<Warning>
  **Timeback apps must follow strict rules.**

  <hr />

  Read [how we evaluate apps](/beta/about-timeback/concepts/evaluating-apps) and [the
  non-negotiables](/beta/about-timeback/concepts/non-negotiables) before you start.
</Warning>

<Steps>
  <Step title="Verify you have staging credentials">
    If you do not have credentials yet, complete
    [first steps](/beta/build-on-timeback/first-steps) first. Confirm you have your staging client ID and secret.

    You will need these credentials for the CLI and SDK.
  </Step>

  <Step title="Install the CLI">
    Install the [Timeback CLI](/beta/build-on-timeback/cli/overview):

    ```bash theme={null}
    curl -fsSL https://timeback.dev/cli | bash
    ```

    Or install via a package manager:

    <CodeGroup>
      ```bash npm theme={null}
      npm install -g timeback
      ```

      ```bash pnpm theme={null}
      pnpm add -g timeback
      ```

      ```bash yarn theme={null}
      yarn global add timeback
      ```

      ```bash bun theme={null}
      bun add -g timeback
      ```
    </CodeGroup>

    Verify the installation:

    ```bash theme={null}
    timeback --version
    ```
  </Step>

  <Step title="Initialize your project">
    Run the interactive [`timeback init`](/beta/build-on-timeback/cli/init) command in your project root:

    ```bash theme={null}
    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:

    ```json timeback.config.json theme={null}
    {
    	"name": "My Learning App",
    	"launchUrl": "https://my-app.example.com",
    	"courses": [
    		{
    			"subject": "Math",
    			"grade": 3,
    			// ...
    		}
    	]
    }
    ```

    See [Configuration](/beta/build-on-timeback/reference/configuration) for the full schema reference.
  </Step>

  <Step title="Push to Timeback">
    Push your configuration to staging:

    ```bash theme={null}
    timeback resources push # defaults to staging
    ```

    This creates or updates your courses in Timeback.

    Use `--dry-run` to preview changes:

    ```bash theme={null}
    timeback resources push --dry-run
    ```

    <Tip>**See [CLI: Resources](/beta/build-on-timeback/cli/resources) for more commands.**</Tip>
  </Step>

  <Step title="Emit learning events">
    Start emitting learning events from your app using [Custom Activities](/beta/build-on-timeback/sdk/activity-tracking/intro).

    <Tabs>
      <Tab title="SDK (recommended)">
        <CodeGroup>
          ```bash npm theme={null}
          npm install @timeback/sdk
          ```

          ```bash pnpm theme={null}
          pnpm add @timeback/sdk
          ```

          ```bash yarn theme={null}
          yarn add @timeback/sdk
          ```

          ```bash bun theme={null}
          bun add @timeback/sdk
          ```

          ```bash pip theme={null}
          pip install timeback-sdk
          ```

          ```bash uv theme={null}
          uv add timeback-sdk
          ```
        </CodeGroup>

        <CodeGroup>
          ```typescript TypeScript theme={null}
          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!,
          	},
          })

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

          ```python Python theme={null}
          from timeback.server import create_server, TimebackConfig, ApiCredentials

          timeback = create_server(TimebackConfig(
          	env="staging",
          	api=ApiCredentials(
          		client_id=os.environ["TIMEBACK_API_CLIENT_ID"],
          		client_secret=os.environ["TIMEBACK_API_CLIENT_SECRET"],
          	),
          ))

          # Record a completed activity
          await timeback.activity.record({
          	"user": {"email": "student@example.com"},
          	"activity": {
          		"id": "lesson-1",
          		"name": "Introduction to Fractions",
          		"course": {"code": "MATH-3"},
          	},
          	"metrics": {
          		"total_questions": 10,
          		"correct_questions": 8,
          		"xp_earned": 80,
          	},
          })
          ```
        </CodeGroup>

        <Note>
          This example shows the
          [single-session](/beta/build-on-timeback/sdk/activity-tracking/single-session) pattern. If your
          activities span multiple sessions, see [stateful
          activities](/beta/build-on-timeback/sdk/activity-tracking/stateful) for the multi-session model
          with server-side completion.
        </Note>

        <Info>
          See [SDK Overview](/beta/build-on-timeback/sdk/overview) for full documentation.
        </Info>
      </Tab>

      <Tab title="Caliper API">
        If you prefer lower-level control, you can send events using the [Caliper client](/beta/build-on-timeback/clients/caliper) directly. See [API Clients](/beta/build-on-timeback/clients/overview) for setup and usage.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## What to expect next

After completing these steps:

1. Verify events are flowing using [Studio](/beta/build-on-timeback/cli/studio)
2. Complete the [Level 1 checklist](/beta/build-on-timeback/integration-levels#level-1-minimal-viable)
3. Submit evidence for [review](/beta/build-on-timeback/integration-levels#what-to-expect-during-review)
4. Receive feedback and production credentials upon approval

<CardGroup cols={2}>
  <Card title="CLI: Credentials" icon="key" href="/beta/build-on-timeback/cli/credentials">
    Manage multiple credential sets
  </Card>

  <Card title="CLI: Resources" icon="folder" href="/beta/build-on-timeback/cli/resources">
    Push, pull, and sync courses
  </Card>

  <Card title="Custom Activities" icon="code" href="/beta/build-on-timeback/sdk/activity-tracking/intro">
    Time tracking and completion metrics for your content
  </Card>

  <Card title="Integration levels" icon="clipboard-check" href="/beta/build-on-timeback/integration-levels">
    See Level 1 requirements in detail
  </Card>
</CardGroup>

## Need help?

<Card title="Join us on Discord" icon="discord" href="https://discord.gg/Qh42FgpG4D">
  Get integration support from the Timeback team and other developers.
</Card>