Tracker System User Guide

Overview

The Tracker System lets you monitor the movement of physical tracker devices as they travel through a supply chain — from a manufacturer, through distribution centres, and into their final delivery locations. This guide explains the key concepts and walks through how to set the system up correctly.

Core Concepts

Client

A client is the top-level organisation in the system. Everything — brands, production runs, trackers, and users — belongs to a client. When you log in, you will only see data for the clients your account has been assigned to.

Brand

A brand sits beneath a client and provides a further layer of filtering. Clients that manufacture or distribute products under multiple brand names can use brands to keep production runs organised. Every production run must be linked to a brand. If your client does not use multiple brands, simply create one brand with the same name as the client.

Production Runs

A production run, also called a campaign, is a group of trackers that are being monitored together for a specific purpose and period of time. The two terms are interchangeable in this guide and in the app UI.

Example: Lego manufactures display stands for a new product and wants them distributed to all Sainsbury's stores. They create a production run to track the stands from manufacture through to store delivery. Sainsbury's receives the stands at their distribution centres first, then ships them on to individual stores.

Key points to understand:

We do not know in advance which tracker will end up at which distribution centre or store — we only record where each tracker actually arrives.
A production run has a defined start and end date. Apple only provides location data for trackers within that active window. If a tracker is seen outside of those dates, Apple still collects the signal but we will not pull that data into the system.
Trackers assigned to a production run are actively queried throughout its duration.

Tracker Statuses

Every tracker has a current status that reflects where it is in its journey. Statuses are determined automatically based on whether the tracker's reported location overlaps with any of your configured geofences.

Status	Meaning	Map Pin Colour
IN_TRANSIT	The tracker has not yet arrived at a known storage or delivery location	Blue
IN_STORAGE	The tracker has arrived within a storage location geofence	Amber
DELIVERED	The tracker has arrived within a delivery location geofence	Green

Status priority: if a tracker's reported position overlaps with both a storage and delivery geofence simultaneously (unusual but possible), it will be recorded as DELIVERED. DELIVERED always takes priority over IN_STORAGE, which takes priority over IN_TRANSIT.

Once a tracker reaches DELIVERED status, tracking does not stop. It continues to record location data, providing a full audit trail of when and where delivery was confirmed.

Managing Clients, Brands, and Campaigns

Clients, brands, campaigns (production runs), and their child runs are all managed from one screen: Campaign Management (the admin panel's sidebar calls it "Campaign Management"; the same screen is available read-only in the regular frontend). It's a drill-down of four linked columns:

Clients → Brands → Campaigns → Child runs

Selecting an item in one column loads and filters the next column to match. For example, selecting a client shows only that client's brands; selecting a brand shows only that brand's campaigns.

Each column has its own:

Search box to filter that column's list by name
+ button to create a new item at that level (admins only — see Users below)
Cards that show a short summary (for example, a brand's card shows how many campaigns it has)

Hovering a card reveals edit and delete buttons in its corner — they're hidden the rest of the time to keep the list uncluttered. A campaign or child-run card also has quick-link icons to jump straight to that run's trackers or its locations, without going through the drill-down again.

On a phone or narrow window

The four columns don't try to squeeze side by side on a small screen. Instead they stack as full-width rows, one above the other, each with its own scrollable list. Selecting an item still filters the next column same as on desktop — the page just smooth-scrolls down to bring that next column into view, since it's no longer sitting right next to the one you just used.

Child runs

A campaign can have child runs — smaller batches within the same overall campaign, sharing its date window. Use these when a single campaign needs to be split into multiple sub-batches (for example, separate waves of stands going to different regions) without losing the fact that they're all part of the same effort. Child runs show up in the fourth column once you've selected their parent campaign.

Managing trackers within a campaign

Opening a campaign or child run (via its "trackers" quick-link, or from the drill-down) takes you to that run's tracker list, where you can:

Switch between a list view and a card view
Sort by name, MAC address, or last-reported time
Import trackers via CSV, or export the current list
Select trackers (individually, via "select all," or by pasting a list of names/MAC addresses) and move them to a different run in the same batch — either through a menu or by dragging a card onto the run you want to move it to

Locations

Locations are optional. A tracker does not require locations to be configured — it will still be tracked, but no automatic status changes will occur. Locations allow the system to determine when a tracker has arrived at a place that matters to you.

Locations are campaign-specific: each production run has its own list of unique delivery and storage locations. That means the locations you configure for one campaign do not automatically appear on another. You can view and edit a campaign's locations from Campaign Management, or use the dashboard map directly via Map Location Actions to add or edit locations in place.

Each location requires a latitude and longitude. The system builds a circular geofence around that point with a default diameter of 200 metres. This can be adjusted depending on the size of the facility — for example, large distribution centres often need a 350 metre geofence to reliably capture arrivals.

How Geofence Detection Works

Apple devices that detect a nearby tracker estimate their own GPS position and report how far away they believe the tracker to be. If the estimated tracker position (device position plus the reported distance radius) overlaps with any of your configured geofences, the tracker is deemed to have arrived at that location.

Storage Locations

Intermediate arrival points — typically distribution centres or warehouses. When a tracker enters a storage location geofence, its status changes to IN_STORAGE and the map pin turns amber.

Delivery Locations

The final destination you have defined for the production run — typically a retail store or end customer site. When a tracker enters a delivery location geofence, its status changes to DELIVERED and the map pin turns green. This is the primary reporting event that confirms the tracker reached where it was supposed to go.

Users

Users must have an account to log in. Each account has:

A role — either admin (full system access) or user (restricted to their assigned clients)
A client list — the clients the user is permitted to see data for

Standard users will only ever see trackers, production runs, and locations for the clients they have been assigned to. Admin users can see all data across all clients.

Mapping

How Location Accuracy Works

Tracker devices are passive Bluetooth beacons. They have no GPS, no internet connection, and no way to determine or transmit their own location. Instead, they rely on Apple's FindMy network:

A nearby Apple device (iPhone, iPad, Mac, etc.) detects the tracker's Bluetooth signal.
The Apple device estimates how far away the tracker is (for example, 100 metres).
The Apple device sends its own GPS location and the estimated distance to Apple's servers.
The system retrieves this data from Apple and uses the Apple device's GPS position plus the estimated distance to determine whether the tracker overlaps with any of your geofences.

This means location accuracy depends entirely on how close Apple devices are to the tracker and how accurate the Apple device's own GPS is. In busy urban areas with many Apple devices nearby, reports tend to be frequent and accurate. In rural or industrial areas, reports may be sparse.

Report Frequency

You have no control over how many Apple devices detect a tracker. It could be one per day or dozens per hour. Every detection generates a report. To avoid cluttering the map, the system aggregates reports into hourly snapshots — the frontend shows one representative location per tracker per hour rather than every individual detection.

Data History Limit

Apple retains location report data for a maximum of 7 days. If a tracker goes undetected for longer than that (for example, stored in a metal shipping container with no nearby Apple devices), those days will have no location data and cannot be recovered retroactively.

Map Location Actions

The dashboard map supports geofence management directly on the map:

Right-click anywhere on the map to open a small popover, then click Add location here to create a new delivery or storage location at that point.
Click an existing delivery or storage zone to open its popup, where you can edit the location.
When you add a location, the map automatically shows the matching delivery or storage layer so it is obvious that the action succeeded.
The map content is scoped to the currently selected production run. If you are working on a specific campaign, choose that campaign filter first so the locations you add or edit stay aligned with it.

What the System Does Not Track

The tracker operates at the production run level. It records where individual tracker devices are located at any point in time — nothing more.

Clients sometimes provide detailed logistics documentation when onboarding, expecting us to use it. The following data is not required and cannot be used by the system:

Shipping manifests
Individual shipment or consignment references
Pallet-level tracking or pallet IDs
Carrier names or carrier booking references
Purchase order references
Delivery schedules or expected arrival dates

The reason is straightforward: we do not know which tracker will end up on which pallet, in which shipment, or with which carrier. We know only that a tracker is somewhere in the world, and we record where it appears. The production run is the most granular grouping the system works with — it represents a cohort of trackers that are being monitored together for a shared purpose.

If a client needs to correlate tracker data with their internal logistics records, that reconciliation is done outside of this system using the tracker's serial number or MAC address as a reference point.

Setup — Required Order

The system has dependencies between entities. Follow this order when setting up a new client, using the Campaign Management drill-down for the first three steps:

Create the Client — everything else belongs to the client.
Create a Brand — at least one brand is required, even if it shares the name of the client.
Create a Production Run — linked to the brand, with a start and end date.
Configure Locations — add storage and delivery locations to the production run with appropriate geofence sizes.
Import Trackers — assign tracker devices to the production run.
Create Users — assign users to the client so they can log in and view their data.

Note: A client must exist before a user can be assigned to it. A brand must exist before a production run can be created. A production run must exist before trackers can be imported.