---
title: Track SDK
description: Vehicle and asset GPS tracking with geofencing and location history. Real-time tracking for fleets, delivery drivers, drones, and any moving asset.
---

# @nolag/track

Vehicle and asset GPS tracking with geofencing and location history.

## Overview

Track vehicles, delivery drivers, drones, or any moving asset in real time. `@nolag/track` broadcasts location updates to all zone subscribers instantly. Geofence detection runs client-side using the haversine formula for circular boundaries and a ray-casting algorithm for polygon boundaries, so triggers fire without a server round-trip. Zones group assets by geographic area or fleet. Join multiple zones to observe overlapping regions.

### Key Features

- Real-time GPS location broadcast to all zone subscribers
- In-memory location buffer per asset for client-side history
- Client-side geofence detection for circle (haversine) and polygon (ray-casting)
- Asset online/offline presence via lobby
- Optional metadata attached to each location point
- Automatic reconnect with zone and presence restoration

## How It Works

`NoLagTrack` wraps the `@nolag/js-sdk` client and manages a lobby that tracks which assets are online. Calling `joinZone(name)` returns a `TrackingZone` that subscribes to two topics: `locations` for ephemeral GPS points and `_geofence` for ephemeral geofence configuration events. Both topics are ephemeral (no server-side retention) to handle high-frequency GPS data without storage overhead. Location history is maintained in-memory on the client. Geofence evaluation happens locally on receipt of each `locationUpdate` event. No additional server calls are made.

| Topic | Purpose | Replay |
| --- | --- | --- |
| `locations` | GPS location points with optional metadata | Ephemeral |
| `_geofence` | Geofence add/remove events (internal, client-side evaluation) | Ephemeral |

## Installation

```bash [Terminal]
npm install @nolag/track @nolag/js-sdk
```

## Quick Start

```typescript [TypeScript]
import { NoLagTrack } from '@nolag/track'

const tracker = new NoLagTrack('your-access-token')
await tracker.connect()

// Join a tracking zone (groups assets by geographic area or fleet)
const zone = await tracker.joinZone('fleet-london')

// Device side: report location
zone.sendLocation({ lat: 51.5074, lng: -0.1278 }, { driverId: 'drv_001', speed: 42 })

// Add a circular geofence (haversine distance check)
zone.addGeofence({
  id: 'depot-central',
  type: 'circle',
  center: { lat: 51.5074, lng: -0.1278 },
  radiusMeters: 500,
  label: 'Central Depot',
})

// Add a polygon geofence (ray-casting algorithm)
zone.addGeofence({
  id: 'zone-east',
  type: 'polygon',
  coordinates: [
    { lat: 51.52, lng: -0.05 },
    { lat: 51.50, lng: -0.03 },
    { lat: 51.48, lng: -0.06 },
    { lat: 51.50, lng: -0.09 },
  ],
  label: 'East Zone',
})

// Controller side: listen for updates
zone.on('locationUpdate', ({ assetId, point, metadata, timestamp }) => {
  console.log(`Asset ${assetId} at ${point.lat}, ${point.lng}`)
})

zone.on('geofenceTriggered', ({ assetId, geofenceId, event }) => {
  console.log(`Asset ${assetId} ${event} geofence ${geofenceId}`)
})

// Get in-memory location history for a specific asset
const history = await zone.getLocationHistory('drv_001')
console.log(`${history.length} location points in buffer`)

// Clean up
tracker.on('disconnected', () => console.log('Disconnected'))
```

## API Reference

### NoLagTrack

| Method | Returns | Description |
| --- | --- | --- |
| `connect()` | `Promise<void>` | Establish the WebSocket connection and join the lobby. |
| `disconnect()` | `void` | Close the connection and leave the lobby. |
| `joinZone(name)` | `Promise<TrackingZone>` | Subscribe to a tracking zone. Returns the zone instance. |
| `leaveZone(name)` | `Promise<void>` | Unsubscribe from a zone and release its resources. |
| `getOnlineAssets()` | `Asset[]` | Return the list of assets currently present in the lobby. |

### NoLagTrack Events

| Event | Payload | Description |
| --- | --- | --- |
| `connected` | none | WebSocket connection established. |
| `disconnected` | `reason: string` | Connection closed. |
| `reconnected` | none | Connection restored after a drop; zone membership and presence are restored automatically. |
| `error` | `error: Error` | A transport or protocol error occurred. |
| `assetOnline` | `asset: Asset` | An asset joined the lobby. |
| `assetOffline` | `asset: Asset` | An asset left the lobby. |

### TrackingZone

| Method | Returns | Description |
| --- | --- | --- |
| `sendLocation(point, metadata?)` | `void` | Broadcast a GPS point `{ lat, lng }` with optional metadata to zone subscribers. |
| `getLocationHistory(assetId?)` | `Promise<LocationPoint[]>` | Fetch location points from the in-memory buffer. Omit `assetId` to get all assets. |
| `addGeofence(geofence)` | `void` | Register a circle or polygon geofence evaluated on every incoming location update. |
| `removeGeofence(id)` | `void` | Deregister a geofence by its ID. |
| `getGeofences()` | `Geofence[]` | Return all currently registered geofences for this zone. |

### TrackingZone Events

| Event | Payload | Description |
| --- | --- | --- |
| `locationUpdate` | `{ assetId, point, metadata?, timestamp }` | A location point was received from an asset in this zone. |
| `assetJoined` | `asset: Asset` | An asset joined this zone. |
| `assetLeft` | `asset: Asset` | An asset left this zone. |
| `geofenceTriggered` | `{ assetId, geofenceId, geofence, event: 'enter' \| 'exit', point }` | An asset crossed a geofence boundary. Evaluated client-side on each location update. |