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

# useTrackingSession

> High-level flight tracking state and controls.

`useTrackingSession` is the recommended entry point for tracking-aware plugins. It provides derived tracking state — `isTracking`, `isPaused`, `elapsedTime` (ticking locally every second), `phase` — alongside flight lifecycle controls and crash recovery handling.

Use this hook when your plugin needs to know whether a flight is active or wants to show elapsed time. Fall back to [`useFlightManager`](/sdk/hooks/use-flight-manager) only when you need the raw `CurrentFlight` object without derived fields, or want to avoid the extra effect for the elapsed timer.

## Import

```ts theme={null}
import { useTrackingSession } from "@skyvexsoftware/stratos-sdk";
```

## Signature

```ts theme={null}
function useTrackingSession(): UseTrackingSessionReturn;

type UseTrackingSessionReturn = {
  isTracking: boolean;
  isPaused: boolean;
  simDisconnected: boolean;
  reconnecting: boolean;
  suspendReason: string | null;
  autoStartWaitReason: string | null;
  currentFlight: CurrentFlight | null;
  pendingRecovery: RecoverableFlight | null;
  elapsedTime: number;
  phase: FlightPhase;
  startFlight: (
    plan: FlightPlan,
    options?: { skipPreflightWarnings?: boolean; forceStart?: boolean },
  ) => Promise<StartFlightResult>;
  pauseFlight: () => Promise<boolean>;
  resumeFlight: () => Promise<boolean>;
  endFlight: (
    status?: "completed" | "diverted" | "crashed" | "cancelled",
  ) => Promise<{ success: boolean; error?: string }>;
  recoverFlight: () => Promise<boolean>;
  dismissRecovery: () => Promise<boolean>;
  isLoading: boolean;
};
```

## Return value

| Field | Type | Description |
| - | - | - |
| `isTracking` | `boolean` | `true` when a flight is active or paused |
| `isPaused` | `boolean` | `true` when the active flight is paused |
| `simDisconnected` | `boolean` | Tracking is suspended: the continuity gate asserted the flight is no longer continuous (socket drop that didn't classify as a continued flight, sustained menu, or an in-stream position jump). Only `resumeFlight()` clears it. |
| `reconnecting` | `boolean` | A gap is open (sim disconnected or in a menu) and Stratos is waiting for frames to classify it. The flight may still be `active`. |
| `suspendReason` | `string \| null` | Reason tracking is suspended; `null` when not suspended. |
| `autoStartWaitReason` | `string \| null` | Why auto-start has not started a flight yet, as a sentence fragment (for example `the aircraft is 260 nm from CYUL, the nearest booked departure`); `null` when auto-start is off, not polling, or a flight is active. Show it near the bookings list so the pilot knows what auto-start is waiting for. |
| `currentFlight` | `CurrentFlight \| null` | Full flight state object, or `null` when idle |
| `pendingRecovery` | `RecoverableFlight \| null` | A previous flight that can be recovered, if one exists |
| `elapsedTime` | `number` | Elapsed flight time in milliseconds, updating every second |
| `phase` | `FlightPhase` | Current flight phase (defaults to `FlightPhase.BOARDING` when idle) |
| `startFlight` | `Function` | Start a new flight; accepts optional start options |
| `pauseFlight` | `() => Promise<boolean>` | Pause the active flight |
| `resumeFlight` | `() => Promise<boolean>` | Resume a paused flight |
| `endFlight` | `(status?) => Promise<{ success, error? }>` | End the active flight |
| `network` | `string` | Pilot-reported online network for the current flight (`"offline"` when none selected). |
| `setNetwork` | `(network: string) => Promise<boolean>` | Set the pilot-reported online network. Resolves `false` when no flight is in progress. |
| `recoverFlight` | `() => Promise<boolean>` | Recover a previously interrupted flight |
| `dismissRecovery` | `() => Promise<boolean>` | Dismiss the pending recovery prompt |
| `isLoading` | `boolean` | `true` during the initial REST hydration |

## `RecoverableFlight`

When Stratos detects a flight was interrupted (e.g. the app crashed mid-flight), `pendingRecovery` is populated with a lean summary of that flight. See [`RecoverableFlight`](/sdk/type-reference#recoverableflight) for the full shape.

## Usage

### Basic tracking display

```tsx theme={null}
import { useTrackingSession, FlightPhase } from "@skyvexsoftware/stratos-sdk";

export function TrackingStatus() {
  const { isTracking, isPaused, phase, elapsedTime } = useTrackingSession();

  const formatTime = (ms: number) => {
    const h = Math.floor(ms / 3_600_000);
    const m = Math.floor((ms % 3_600_000) / 60_000);
    const s = Math.floor((ms % 60_000) / 1_000);
    return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
  };

  if (!isTracking) return <p>No active flight</p>;

  return (
    <div>
      <p>Phase: {phase}</p>
      <p>Elapsed: {formatTime(elapsedTime)}</p>
      <p>{isPaused ? "Paused" : "Active"}</p>
    </div>
  );
}
```

### Start a flight with options

```tsx theme={null}
const { startFlight } = useTrackingSession();

const result = await startFlight(
  {
    source: "simbrief",
    sourceId: "12345678",
    callsign: "QFA001",
    departureIcao: "YSSY",
    arrivalIcao: "EGLL",
    route: ["SY", "LL"],
    aircraftIcao: "A388",
  },
  { skipPreflightWarnings: false, forceStart: false },
);

if (result.vaConfirmation) {
  // Show VA confirmation dialog before the flight is fully registered
  console.log(result.vaConfirmation);
}
```

### Recovery handling

```tsx theme={null}
const { pendingRecovery, recoverFlight, dismissRecovery } =
  useTrackingSession();

if (pendingRecovery) {
  return (
    <div>
      <p>Interrupted flight found: {pendingRecovery.callsign}</p>
      <button onClick={recoverFlight}>Recover</button>
      <button onClick={dismissRecovery}>Dismiss</button>
    </div>
  );
}
```

### Report the online network

```tsx theme={null}
const { network, setNetwork } = useTrackingSession();

<Select value={network} onValueChange={(v) => void setNetwork(v)}>
  ...
</Select>;
```

Only shown when the airline enables the flight-tracking plugin's
**Capture Network Presence** setting; the selection resets to `"offline"`
on every flight start.

## Notes

* `elapsedTime` is computed locally via a 1-second `setInterval` so it ticks smoothly between server broadcasts (which occur every \~15 seconds).
* The hook uses `staleTime: Infinity` and refetches on socket reconnect to catch flights started before the UI loaded.
* The TanStack Query cache key is `["tracking-session", "state"]` — this is the same key used across the shell and all plugins, ensuring consistent state with no duplicate requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.