> ## 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.

# Introduction

> Use Timeback's lesson engine to serve adaptive content

Managed Lessons let your app deliver learning experiences powered by Timeback's lesson engine. Instead of building your own content pipeline, sequencing logic, and scoring system, you call `timeback.lessons.*` and the SDK handles the rest.

<Tip>
  This section covers the SDK implementation for **Managed Lessons** ([Level
  2](/beta/build-on-timeback/integration-levels#level-2-fully-native)). For the onboarding guide,
  see [Building native apps](/beta/build-on-timeback/start-building/native-apps). If you own your
  content, see [Custom Activities](/beta/build-on-timeback/sdk/activity-tracking/intro).
</Tip>

## When to use

|                       | [Custom Activities](/beta/build-on-timeback/sdk/activity-tracking/intro)     | Managed Lessons                                                            |
| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Content**           | Your own content and logic                                                   | Timeback's course builder                                                  |
| **Platform role**     | Time and completion reporting                                                | Sequencing, scoring, and XP                                                |
| **Integration level** | [Level 1](/beta/build-on-timeback/integration-levels#level-1-minimal-viable) | [Level 2](/beta/build-on-timeback/integration-levels#level-2-fully-native) |

## How it works

Your app renders the UI. The SDK manages everything else: discovering available lessons, serving questions, accepting answers, scoring, and tracking time.

```mermaid theme={null}
graph TB
    subgraph browser [Your App]
        UI["UI Layer"] --> SDK["@timeback/sdk client"]
    end
    SDK -->|"POST /lessons/*"| Server["@timeback/sdk server"]
    Server --> OR["OneRoster API"]
    Server --> PP["PowerPath API"]
    SDK -->|"TimeSpentEvent heartbeats"| Caliper["Caliper API"]
```

Under the hood, the SDK orchestrates two Timeback systems:

| System        | Purpose            | What it provides                   |
| ------------- | ------------------ | ---------------------------------- |
| **OneRoster** | Lesson discovery   | Courses, components, and resources |
| **PowerPath** | Assessment runtime | Sequencing, questions, scoring     |

Time tracking is handled automatically. When a lesson starts, the SDK creates an activity tracker that sends periodic `TimeSpentEvent` heartbeats.

## The lesson lifecycle

A typical Managed Lesson flow has four phases:

| Phase             | SDK method                                                                                                | What happens                 |
| ----------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Discover**      | [`lessons.list()`](/beta/build-on-timeback/sdk/managed-lessons/reference#lessons-list)                    | List available lessons       |
| **Start**         | [`lessons.start()`](/beta/build-on-timeback/sdk/managed-lessons/reference#lessons-start)                  | Begin or resume an attempt   |
| **Next question** | [`session.next()`](/beta/build-on-timeback/sdk/managed-lessons/reference#lessonquestion)                  | Fetch the next question      |
| **Submit answer** | [`session.submit()`](/beta/build-on-timeback/sdk/managed-lessons/reference#lessonsubmitresult)            | Score and record a response  |
| **Complete**      | [`session.complete()`](/beta/build-on-timeback/sdk/managed-lessons/reference#lessonsessioncompleteresult) | Finalize scoring, flush time |

The `LessonSession` object returned by `lessons.start()` is the central runtime. It tracks state like `score`, `attempt`, and `finalized`, and updates these properties as the session progresses.

## Caliper behavior

| Event            | Sent by   | Purpose                              |
| ---------------- | --------- | ------------------------------------ |
| `TimeSpentEvent` | SDK       | Time tracking heartbeats (every 15s) |
| `ActivityEvent`  | PowerPath | Scoring, XP, and gradebook writes    |

The SDK does **not** send an [`ActivityCompletedEvent`](/beta/build-on-timeback/reference/events#activitycompletedevent) for Managed Lessons. PowerPath is the source of truth for completion, XP, and gradebook updates.

## Configuration

Managed Lessons require a Caliper sensor URL in your [`timeback.config.json`](/beta/build-on-timeback/reference/configuration).

<Info>
  See the [configuration
  reference](/beta/build-on-timeback/reference/configuration#sensor-resolution) for sensor
  resolution rules and environment overrides.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Lesson discovery" icon="magnifying-glass" href="/beta/build-on-timeback/sdk/managed-lessons/lesson-discovery">
    List available lessons and start a session
  </Card>

  <Card title="Question loop" icon="arrows-rotate" href="/beta/build-on-timeback/sdk/managed-lessons/question-loop">
    Fetch questions and submit answers
  </Card>

  <Card title="Completion" icon="flag-checkered" href="/beta/build-on-timeback/sdk/managed-lessons/completion">
    Finalize scoring and interpret results
  </Card>

  <Card title="Attempt history" icon="clock-rotate-left" href="/beta/build-on-timeback/sdk/managed-lessons/attempt-history">
    Review past attempts and per-question data
  </Card>

  <Card title="Reference" icon="code" href="/beta/build-on-timeback/sdk/managed-lessons/reference">
    Parameters, properties, methods, and return types
  </Card>

  <Card title="Configuration" icon="gear" href="/beta/build-on-timeback/reference/configuration">
    Full timeback.config.json reference
  </Card>

  <Card title="Getting started" icon="rocket" href="/beta/build-on-timeback/start-building/native-apps">
    Onboarding guide for building native apps on Timeback
  </Card>
</CardGroup>