useTrackingSession

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 only when you need the raw CurrentFlight object without derived fields, or want to avoid the extra effect for the elapsed timer.

Import

import { useTrackingSession } from "@skyvexsoftware/stratos-sdk";

Signature

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 for the full shape.

Usage

Basic tracking display

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

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

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

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.

Getting Started

Plugin Basics

UI Module

Background Module

Deploy

Type Reference

Import

Signature

Return value

`RecoverableFlight`

Usage

Basic tracking display

Start a flight with options

Recovery handling

Report the online network

Notes

​Import

​Signature

​Return value

​RecoverableFlight

​Usage

​Basic tracking display

​Start a flight with options

​Recovery handling

​Report the online network

​Notes

Import

Signature

Return value

`RecoverableFlight`

Usage

Basic tracking display

Start a flight with options

Recovery handling

Report the online network

Notes