Agent tracking

Tracking is how RideWiseCore knows where your agents are and who can take a ride. Your backend sends each agent's location over the real-time socket, and RideWiseCore keeps the latest position and status for every agent.

Sending a location

socket.emit(
  "agent:location",
  {
    agentId: "agt_1001",   // your ID for the agent
    lat: 40.7128,
    lng: -74.0060,
    status: "available",    // "available" | "busy" | "offline"
    vehicleType: "sedan",
    heading: 92,            // optional, degrees 0–360
    speed: 11.4,            // optional, your unit (e.g. m/s)
  },
  (ack) => {
    if (!ack.ok) console.error(ack.error);
  },
);

Every location you send:

1. Updates the agent's stored position, status and vehicle type.
2. Refreshes the agent's last seen time.
3. Is sent back to every socket in your room as a agent:update event, so your dashboards and passenger-facing services can show it live.

Agent statuses

Freshness: the 30-second rule

An agent is considered fresh if RideWiseCore received a location from them in the last 30 seconds.

• Matching skips any agent who isn't fresh, even if their last status was available.
• A background sweep runs every ~10 seconds. It takes agents who have gone silent for 30 seconds offline, which removes them from matching and from your active-agent count.

This covers crashed apps, dead batteries and lost signal without any action from you.

Recommended cadence: send a location for every online agent every 3–10 seconds. Sending more often only improves accuracy. You're billed on peak concurrent agents, not on the number of updates, so frequent updates cost nothing extra.

Taking an agent offline

When an agent signs off, send one final update with status: "offline":

socket.emit("agent:location", {
  agentId: "agt_1001",
  lat: 40.7128,
  lng: -74.0060,
  status: "offline",
  vehicleType: "sedan",
});

This takes them out of matching and your active count straight away, instead of waiting 30 seconds.

Trip lifecycle and status

A typical agent's status over a shift:

sign in ──▶ available ──(accepts ride)──▶ busy ──(trip ends)──▶ available ──▶ … ──▶ offline
                        RideWiseCore sets     you send "busy"   you send
                        busy on accept        while on the trip "available"

RideWiseCore has no trip model, so it can't know when a trip ends. Your backend tells it by sending status: "available" again.

Following your live fleet

Listen for agent:update on your socket. Every stored location is echoed there, so you can drive live maps from it.

Validation rules

An invalid payload is rejected through the acknowledgement: { ok: false, error: "…" }.