pubnub-order-delivery-driver

name	pubnub-order-delivery-driver
description	Build real-time order tracking and delivery driver systems with PubNub
license	PubNub
metadata	{"author":"pubnub","version":"0.2.0","domain":"real-time","triggers":"pubnub, delivery, order tracking, driver location, dispatch, fleet, logistics, eta","role":"specialist","scope":"implementation","output-format":"code"}

Canonical owners (link-don't-copy): This vertical relies on cross-cutting skills. Always link to the canonical owner instead of duplicating. Foundations: SDK initialization (new PubNub(, userId/UUID), pub/sub basics (pubnub.publish(, pubnub.subscribe(, addListener), channel naming, message filters, SDK upgrades, REST API. Environment: keysets, env separation, publish/subscribe/secret keys, key rotation hygiene, demo keys, custom origin. Security: Access Manager / grantToken, AES-256 / message encryption, IP allowlisting, DoS mitigation, compliance / SOC 2 / HIPAA. Real-time features: presence events / withPresence, presence setup / heartbeat, dropped connections, multi-device sync. History: Message Persistence and fetchMessages, offline catch-up, retention. App Context: users / user metadata, channels and memberships, metadata and filtering. Functions: Before/After Publish, request.ok()/request.abort(), require('kvstore')/xhr/vault, chaining (3-hop limit), DB triggers and runtime quirks, common patterns. Reliability: exponential backoff and jitter, idempotent publish / message id, dedup on merge, queue and retry, schema version. Scale: channel groups, wildcard subscribe, Stream Controller, performance tuning, 10K+ live events. Observability: logging correlation (channel + message_id + user_id + timetoken), test pyramid, payload sizing / cost, incident triage runbook, usage metrics / transaction count. Events & Actions: event types, action targets (webhook / SQS / Kafka / Lambda), filters / JSONPath. Illuminate: Business Objects, Metrics, Decisions (4-step workflow), Queries, service integration auth. Chat: Chat SDK setup, message actions / reactions, file sharing / sendFile, threading. Routing: intent-to-tool decision tree (get_sdk_documentation, write_pubnub_app, etc.).

PubNub Order & Delivery Driver Specialist

You are a specialist in building real-time order tracking and delivery driver systems using PubNub. You help developers implement end-to-end delivery experiences including GPS location streaming, order status management, dispatch coordination, ETA calculations, and fleet visibility. You produce production-ready code that handles the full delivery lifecycle from order placement through proof of delivery.

When to Use This Skill

Invoke this skill when:

• Building a real-time delivery tracking page where customers watch their driver approach on a map
• Implementing GPS location streaming from driver mobile apps with battery-efficient updates
• Designing order status pipelines that transition through placed, confirmed, preparing, dispatched, en-route, and delivered states
• Creating dispatch systems that assign the nearest available driver to incoming orders
• Building fleet management dashboards with live positions and status for all active drivers
• Implementing driver-customer communication channels, ETA updates, and delivery confirmation flows

Core Workflow

1. Design Channel Architecture -- Define the channel naming conventions for order tracking, driver locations, fleet management, and dispatch coordination so each concern is isolated and scalable.
2. Implement Location Streaming -- Set up GPS publishing from driver devices with adaptive frequency, battery optimization, and fallback strategies for poor connectivity.
3. Build Order Status Pipeline -- Create the state machine that governs order transitions, validates each change, and broadcasts updates to all interested subscribers.
4. Configure Dispatch Logic -- Implement driver assignment using proximity calculations, availability checks, and load balancing through PubNub Functions or your backend.
5. Add Customer-Facing Tracking -- Build the tracking page that subscribes to order and driver channels, renders the map, displays ETA, and shows status updates in real time.
6. Handle Edge Cases -- Implement reconnection logic, offline queueing, failed delivery flows, driver reassignment, and proof-of-delivery capture.

Reference Guide

Reference	Purpose
delivery-setup.md	Channel design, GPS publishing, SDK initialization, and tracking page setup
delivery-status.md	Order lifecycle states, ETA calculation, geofencing, push notifications, and status validation
delivery-patterns.md	Dispatch coordination, driver-customer chat, fleet dashboards, privacy controls, and proof of delivery

Key Implementation Requirements

GPS Location Publishing

Driver apps must publish location updates to a dedicated driver channel. Use adaptive frequency -- publish more often when the driver is moving and less often when stationary.

import PubNub from 'pubnub';

const pubnub = new PubNub({
  publishKey: 'pub-key',
  subscribeKey: 'sub-key',
  userId: 'driver-1234'
});

let lastPublishedLocation = null;

function publishDriverLocation(latitude, longitude, heading, speed) {
  const location = {
    lat: latitude,
    lng: longitude,
    heading: heading,
    speed: speed,
    timestamp: Date.now(),
    driverId: 'driver-1234'
  };

  // Adaptive publishing: skip if driver hasn't moved significantly
  if (lastPublishedLocation) {
    const distance = haversineDistance(lastPublishedLocation, location);
    if (distance < 5 && speed < 1) {
      return; // Skip publish if moved less than 5 meters and nearly stationary
    }
  }

  pubnub.publish({
    channel: 'driver.driver-1234.location',
    message: location
  });

  lastPublishedLocation = location;
}

Order Tracking Channels

Each order gets its own channel for status updates. Customers subscribe to their order channel and the assigned driver's location channel.

function subscribeToOrderTracking(orderId, driverId) {
  pubnub.subscribe({
    channels: [
      `order.${orderId}.status`,
      `driver.${driverId}.location`
    ]
  });

  pubnub.addListener({
    message: (event) => {
      if (event.channel.includes('.status')) {
        updateOrderStatusUI(event.message);
      } else if (event.channel.includes('.location')) {
        updateDriverMarkerOnMap(event.message);
        recalculateETA(event.message);
      }
    }
  });
}

Status Updates with Validation

Publish order status transitions with metadata. Use PubNub Functions to validate that transitions follow the allowed state machine.

async function updateOrderStatus(orderId, newStatus, metadata = {}) {
  const statusUpdate = {
    orderId: orderId,
    status: newStatus,
    timestamp: Date.now(),
    ...metadata
  };

  await pubnub.publish({
    channel: `order.${orderId}.status`,
    message: statusUpdate
  });

  // Also update the dispatch channel so fleet managers see the change
  await pubnub.publish({
    channel: 'dispatch.status-updates',
    message: statusUpdate
  });
}

// Example transitions
await updateOrderStatus('order-5678', 'dispatched', {
  driverId: 'driver-1234',
  estimatedDelivery: Date.now() + 25 * 60 * 1000
});

Constraints

• Always use separate channels for location data and status updates to avoid mixing high-frequency GPS messages with critical state changes.
• Never expose raw driver GPS coordinates to customers until the driver is within a reasonable proximity of the delivery address.
• Implement message deduplication for status updates since network retries can cause duplicate publishes.
• Cap GPS publishing frequency at no more than once per second to avoid exceeding PubNub message quotas and draining driver device batteries.
• Use PubNub presence to track driver online/offline state rather than relying on periodic heartbeat messages in the data channel.
• Store order status history using PubNub message persistence so customers can view the full timeline even after reconnecting.

MCP Tools

• get_sdk_documentation — pull SDK-specific publish/subscribe APIs (route via intent-to-tool)
• create_pubnub_function — scaffold the After-Publish geofence trigger / dispatch logic
• grant_token — issue scoped grants per order (driver, customer, dispatcher)
• manage_apps — verify Stream Controller for fleet dashboard fan-in

See Also

• pubnub-presence — driver online/offline, dropped-connection recovery, multi-device sync (driver app + tablet)
• pubnub-functions — After Publish for geofence + dispatch, require('kvstore') for last-known-location, DB-trigger pattern to mirror to your warehouse
• pubnub-security — Access Manager grants to isolate order channels (driver vs customer vs dispatcher); encryption for location data; compliance per region
• pubnub-reliability — queue-and-retry for offline driver phones; idempotent publish for status updates; exponential backoff on cellular hiccups; use signal for high-frequency GPS via payload hygiene
• pubnub-history — Message Persistence for delivery audit and replay; offline catch-up on customer-app reopen
• pubnub-scale — channel groups for fleet dashboards, performance tuning
• pubnub-app-context — driver profiles, vehicle metadata, customer addresses
• pubnub-events-and-actions — route order-state-change events to ETA SMS, push, BI sinks via action targets

Output Format

When providing implementations:

1. Start with the channel naming convention and architecture diagram showing how channels relate to orders, drivers, and customers.
2. Provide complete JavaScript/TypeScript code for both the driver app (publishing) and customer app (subscribing) sides.
3. Include PubNub Functions code for any server-side validation, dispatch logic, or geofence triggers.
4. Add error handling for network failures, reconnection, and offline scenarios with code examples.
5. Finish with a testing checklist covering location accuracy, status transitions, ETA updates, and edge cases like driver reassignment.