Hướng dẫn tích hợp React SDK

npm install @vietmap/tracking-sdk-react
# hoặc
pnpm add @vietmap/tracking-sdk-react
yarn add @vietmap/tracking-sdk-react

import "@vietmap/tracking-sdk-react/styles.css";

import {
  FleetworkProvider,
  Dashboard,
  LiveMap,
  Report,
} from "@vietmap/tracking-sdk-react";
import "@vietmap/tracking-sdk-react/styles.css";

export default function App() {
  return (
    <FleetworkProvider apiKey="YOUR_API_TOKEN">
      <Dashboard />
      <LiveMap
        apiKeyTilemap="YOUR_VIETMAP_TILE_KEY"
        height="600px"
        memberNameKey="userName"
      />
      <Report />
    </FleetworkProvider>
  );
}

import { FleetworkProvider } from "@vietmap/tracking-sdk-react";

function App() {
  return (
    <FleetworkProvider apiKey="YOUR_API_KEY" locale="vi">
      <YourApp />
    </FleetworkProvider>
  );
}

<FleetworkProvider apiKey="..." memberNameKey="userName">
  <Dashboard />                    {/* MemberReport hiện metaData.userName */}
  <LiveMap apiKeyTilemap="..." />  {/* Marker name từ metaData.userName */}
  <Report />                       {/* Bảng Hành trình / Nhiên liệu hiện metaData.userName */}
</FleetworkProvider>

<LiveMap apiKeyTilemap="..." memberNameKey="driverCode" />

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "status": "Invalid - API Key Not Found",
  "errors": ["API key not found in database"]
}

// Mặc định — overlay tự bật, vẫn nhận callback song song
<FleetworkProvider
  apiKey="..."
  onAuthError={(event) => {
    // event: { status: 401|403, message, url, method, payload }
    if (event.status === 401) {
      // xử lý riêng
    }
  }}
>

// Tắt overlay nếu muốn tự xử lý hoàn toàn
<FleetworkProvider apiKey="..." disableAuthErrorOverlay onAuthError={handler}>

// Render overlay tuỳ chỉnh
<FleetworkProvider
  apiKey="..."
  renderAuthError={(event, dismiss) => (
    <MyCustomDialog message={event.message} onClose={dismiss} />
  )}
>

import {
  Dashboard,
  SummaryCards,
  MemberReport,
} from "@vietmap/tracking-sdk-react";

<Dashboard pollInterval={30_000} />
<Dashboard userIds={["u1", "u2"]} />   {/* lọc toàn bộ dashboard theo tập user */}

// Widget dùng độc lập cũng nhận userIds:
<SummaryCards userIds={["u1", "u2"]} />
<MemberReport pageSize={20} userIds={["u1", "u2"]} />

import { useRef } from "react";
import { LiveMap, type LiveMapRef } from "@vietmap/tracking-sdk-react";

const mapRef = useRef<LiveMapRef>(null);

<LiveMap
  ref={mapRef}
  apiKeyTilemap="YOUR_VIETMAP_KEY"
  height="600px"
  center={[106.63, 10.82]}
  zoom={11}
  defaultTile="terrain"
  pollInterval={10_000}
  maxUsers={3000}
  clusterRadius={50}
  clusterMaxZoom={14}
  memberNameKey="userName"
  showList
  onMarkerClick={(m) => console.log(m.name)}
  onMapReady={(map) => console.log("zoom:", map.getZoom())}
/>;

mapRef.current?.flyTo([106.63, 10.82], 14);
mapRef.current?.fitBounds([
  [102, 8],
  [110, 23],
]);
mapRef.current?.focusMember("user-123");      // Bay đến + mở popup
mapRef.current?.getMembers();                 // MemberStatus[] (đã áp status filter)
mapRef.current?.getMap();                     // MapInstance
mapRef.current?.setStatusFilter(["moving"]);  // Lọc; [] hoặc undefined = xoá lọc
mapRef.current?.getStatusFilter();            // MemberStatusKind[] | undefined

<LiveMap apiKeyTilemap="..." userIds={["driver-01", "driver-02", "driver-03"]} />

// 1) Controlled — qua prop (component cha giữ state)
<LiveMap apiKeyTilemap="..." statusFilter={["moving", "stopped"]} />

// 2) Imperative — gọi qua ref (bỏ prop để ở chế độ uncontrolled)
const mapRef = useRef<LiveMapRef>(null);
<LiveMap ref={mapRef} apiKeyTilemap="..." />;
mapRef.current?.setStatusFilter(["signal_lost"]); // chỉ hiện mất tín hiệu
mapRef.current?.setStatusFilter([]);              // xoá lọc

<Report from={Date.now() - 30 * 86_400_000} to={Date.now()} />

// userIds: chỉ lấy một tập user cho mọi báo cáo (API lọc server-side)
<Report from={from} to={to} userIds={["u1", "u2"]} />

import {
  TripSummaryReport,
  TripDetailReport,
  FuelSummaryReport,
  FuelDetailReport,
  ActivityTimeReport,
} from "@vietmap/tracking-sdk-react";

// Summary: range, onRangeChange, onBack, onError, pageSize, userIds, onUserClick
<TripSummaryReport
  range={{ from, to }}
  onRangeChange={setRange}
  onUserClick={(userId, name) => openDetail(userId, name)}
/>;

// Detail: thêm userId + userName để drill-down 1 user
// (ẩn cột nhân viên, lọc theo userId, tên hiện ở tiêu đề)
<TripDetailReport
  range={{ from, to }}
  onRangeChange={setRange}
  userId="u1"
  userName="Nguyễn Văn A"
/>;

// Dashboard
const { data } = useSummaryCards({ date?, userIds?, pollInterval? })
const { data } = useMemberReport({ date?, page?, pageSize?, status?, userIds? })
const { data } = useActivityHeatmap({ from?, to?, metric?, userId?, userIds? })
const { data } = useFuelTracking({ from?, to?, groupBy?, userId?, userIds? })
const { data } = useMonthlyExpenses({ from?, to?, currency?, userIds? })

// LiveMap
const { data } = useMembers({ pollInterval?, nameKey?, maxUsers?, userIds? })
const { data } = useMember(userId)
const { data } = useHistoryRoute({ userId, startTime, endTime })

// Report
// userId? (1 user, drill-down) hoặc userIds? (nhiều user, summary lọc server-side)
const { data } = useTripSummaryReport({ from, to, page?, pageSize?, sortBy?, sortDesc?, userId?, userIds? })
const { data } = useTripDetailReport({ from, to, page?, pageSize?, sortBy?, sortDesc?, userId? })
const { data } = useFuelSummaryReport({ from, to, page?, pageSize?, sortBy?, sortDesc?, userId?, userIds? })
const { data } = useFuelDetailReport({ from, to, page?, pageSize?, sortBy?, sortDesc?, userId? })
const { data } = useActivityTimeReport({ from, to, page?, pageSize? })

import {
  initFleetwork,
  DashboardController,
  LiveMapController,
  ReportController,
} from "@vietmap/tracking-sdk-react";

initFleetwork({ apiKey: "...", baseUrl: "..." });

const summary = await DashboardController.getSummaryCards();
const members = await LiveMapController.getMembers({ pageSize: 3000 });
const some = await LiveMapController.getMembers({ userIds: ["u1", "u2"] }); // lọc server-side
const report = await DashboardController.getMemberReport(Date.now(), {
  userIds: ["u1", "u2"],
});
const history = await LiveMapController.getHistoryRoute(userId, from, to);
const trips = await ReportController.getTripSummary({
  from,
  to,
  userIds: ["u1", "u2"],
});
const fuel = await ReportController.getFuelSummary({ from, to });
const userTrips = await ReportController.getTripDetail({
  from,
  to,
  userId: "u1",
}); // chi tiết 1 user

import { HttpService } from "@vietmap/tracking-sdk-react";

const data = await HttpService.get<MyType>("my/endpoint", { from, to });
const created = await HttpService.post<MyType>("my/endpoint", { name: "..." });

import { create } from "zustand";
import { DashboardController } from "@vietmap/tracking-sdk-react";
import type { SummaryCardsData } from "@vietmap/tracking-sdk-react";

interface Store {
  summary: SummaryCardsData | null;
  loading: boolean;
  fetchSummary: (date: number) => Promise<void>;
}

export const useDashboardStore = create<Store>((set) => ({
  summary: null,
  loading: false,
  fetchSummary: async (date) => {
    set({ loading: true });
    try {
      const summary = await DashboardController.getSummaryCards(date);
      set({ summary, loading: false });
    } catch {
      set({ loading: false });
    }
  },
}));

import { LiveMapController } from "@vietmap/tracking-sdk-react";

// Mặc định — backend tự quyết enriched hay raw
const auto = await LiveMapController.getHistoryComparison(userId, from, to);
auto.dataSource; // null

// GPS gốc, không map-matching — nhẹ nhất
const raw = await LiveMapController.getHistoryComparison(userId, from, to, {
  dataSource: "raw",
});

// Đối chiếu: vẽ enriched liền nét, raw nét đứt chồng lên
const cmp = await LiveMapController.getHistoryComparison(userId, from, to, {
  dataSource: "both",
});
cmp.enrichedSegments?.forEach((seg) => drawPolyline(seg)); // vẽ từng segment riêng
if (cmp.rawPoints) drawDashed(cmp.rawPoints);

// Một tuyến liền mạch, không hở ở chỗ matcher fail
const merged = await LiveMapController.getHistoryComparison(userId, from, to, {
  dataSource: "merged",
});
drawPolyline(merged.points);

// getHistoryRoute() = getHistoryComparison().points
const points = await LiveMapController.getHistoryRoute(userId, from, to, {
  dataSource: "merged",
});

<LiveMap apiKeyTilemap={key} dataSource="merged" />

<LiveMap apiKeyTilemap="..." showTransitionMarkers />

document.documentElement.classList.toggle("dark");

<FleetworkProvider
  theme={{
    colors: {
      primary: "#2563eb",
      background: "#0f172a",
      text: "#f1f5f9",
      border: "#1e293b",
      destructive: "#ef4444",
      statusMoving: "#10b981",
      statusStopped: "#f59e0b",
      statusSignalLost: "#94a3b8",
    },
    borderRadius: 8,
    fontFamily: "Inter, sans-serif",
  }}
>

import type {
  // Config
  ThemeConfig,
  FleetworkConfig,
  Locale,
  TileType,
  MemberStatusKind,
  // Dashboard
  SummaryCardsData,
  MemberReportData,
  MemberRow,
  ActivityHeatmapData,
  ActivityHeatmapCell,
  FuelTrackingData,
  MonthlyExpensesData,
  // LiveMap
  MemberStatus,
  GpsPoint,
  HistoryDataSource,
  HistoryRoute,
  EnrichedSegment,
  RouteSummary,
  // Lỗi
  SdkError,
  AuthErrorEvent,
} from "@vietmap/tracking-sdk-react";

type Locale = "vi" | "en";
type TileType = "light" | "dark" | "terrain" | "satellite";
type MemberStatusKind = "moving" | "stopped" | "signal_lost";

interface SummaryCardsData {
  date: number; // Unix ms
  activeUsers: { active: number; total: number };
  totalDistance: { value: number; unit: string };
  totalTravelTime: { totalSeconds: number; formatted: string };
  totalFuelCost: { value: number; currency: string; formatted: string };
  generatedAt: number; // Unix ms
}

interface MemberReportData {
  date: number; // Unix ms
  summary: {
    total: number;
    moving: number;
    stopped: number;
    signalLost: number;
  };
  users: MemberRow[]; // key: users
  pagination: {
    page: number;
    pageSize: number;
    totalItems: number;
    totalPages: number;
  };
}

interface MemberRow {
  userId: string;
  distance: { value: number; unit: string };
  travelTime: { totalSeconds: number; formatted: string };
  fuel: {
    consumedLiters: number;
    costVnd: number;
    costFormatted: string;
    efficiencyKmPerL: number;
  };
  status: MemberStatusKind;
  statusLabel: string;
  lastLocation: {
    lat: number;
    lng: number;
    address: string | null;
    speed: number; // km/h
    time: number; // Unix ms
    // JSON string các thuộc tính tuỳ ý — dùng resolveMemberName để lấy tên
    metadata?: string | null;
  } | null;
  lastSeenAt: number | null; // Unix ms
}

interface ActivityHeatmapCell {
  dayOfWeek?: string | number | null; // 'Mon' | 'monday' | 'T2' | thiếu → dùng date
  date: number; // Mốc bucket (ms) — nguồn chuẩn để map ngày/giờ
  hour?: number; // 0–23 giờ địa phương; thiếu thì suy từ date
  value: number;
  label?: string;
}

interface ActivityHeatmapData {
  from: number;
  to: number;
  metric: "distance" | "points";
  resolution: "hour";
  cells: ActivityHeatmapCell[];
  maxValue: number;
  minValue: number;
  totalCells: number;
}

interface FuelTrackingData {
  from: number;
  to: number;
  groupBy: "day" | "week" | "month";
  fuelEfficiency: { value: number; unit: string; trend: string };
  series: {
    period: string; // "2026-W01" | "2026-01" | "2026-04-01"
    label: string;
    distanceKm: number;
    fuelLiters: number;
    efficiencyKmPerL: number;
  }[];
  totals: {
    totalDistanceKm: number;
    totalFuelLiters: number;
    avgEfficiencyKmPerL: number;
  };
}

interface MonthlyExpensesData {
  from: number;
  to: number;
  currency: string; // "VND"
  months: {
    month: number; // 1–12
    label: string;
    costs: {
      fuel: number;
      maintenance: number;
      insurance: number;
      other: number;
      total: number;
    };
  }[];
  totals: {
    fuel: number;
    maintenance: number;
    insurance: number;
    other: number;
    grandTotal: number;
  };
  categories: { key: string; label: string; color: string }[];
}

interface MemberStatus {
  userId: string;
  name: string;
  avatarUrl?: string | null;
  groupName?: string | null;
  status: MemberStatusKind;
  statusLabel: string;
  lat: number;
  lng: number;
  speed?: number; // km/h
  lastSeenAt?: number; // Unix ms
  lastAddress?: string;
}

interface GpsPoint {
  time: number; // Unix ms
  status?: number;
  lat: number;
  lng: number;
  speed: number; // km/h
  heading: number; // 0–360
  userId?: string | null;
  vehicleId?: string | null;
  deviceId?: string | null;
  data?: string | null;
  // Endpoint /gps-tracking/users trả JSON string; latest/history trả object
  metadata?: string | Record<string, unknown> | null;
}

// Một segment polyline liền mạch sau map-matching — vẽ mỗi segment thành 1 polyline riêng
interface EnrichedSegment {
  segmentIndex: number;
  points: GpsPoint[];
}

interface RouteSummary {
  distanceMeters: number; // Quãng đường thực đi, KHÔNG tính khoảng mất GPS
  movingDurationMs: number; // Thời gian di chuyển
  stoppedDurationMs: number; // Dừng nhưng GPS vẫn hoạt động
  lostGpsDurationMs: number; // Mất tín hiệu — KHÔNG nằm trong 3 field trên
}

type HistoryDataSource = "raw" | "both" | "merged";

interface HistoryRoute {
  points: GpsPoint[]; // Dùng cho playback / timeline / marker
  rawPoints: GpsPoint[] | null; // Tuyến GPS gốc, sort theo thời gian
  enrichedPoints: GpsPoint[] | null; // Tuyến map-matched
  enrichedSegments: GpsPoint[][] | null; // Vẽ mỗi phần tử thành 1 polyline riêng
  enriched: boolean;
  routeSummary: RouteSummary | null;
  dataSource: HistoryDataSource | null;
}

interface SdkError extends Error {
  status?: number;
}

// Hooks — error object
const { data, error } = useSummaryCards();
if (error) return <div>Lỗi: {error.message}</div>;

// Components — onError callback
<Dashboard onError={(err) => console.error(err)} />;

// Controllers — throw SdkError
try {
  const data = await DashboardController.getSummaryCards();
} catch (error) {
  // error.status: 401 | 403 | 429 | 500
  // error.message: string
}

import { FleetworkProvider, Dashboard } from "@vietmap/tracking-sdk-react";
import "@vietmap/tracking-sdk-react/styles.css";

export default function DashboardPage() {
  const today = new Date();
  today.setHours(0, 0, 0, 0);

  return (
    <FleetworkProvider apiKey="YOUR_API_KEY" locale="vi" memberNameKey="userName">
      <div className="p-6">
        <h1 className="text-2xl font-bold mb-6">GPS Dashboard</h1>
        <Dashboard date={today.getTime()} />
      </div>
    </FleetworkProvider>
  );
}

import {
  useSummaryCards,
  useMemberReport,
  resolveMemberName,
} from "@vietmap/tracking-sdk-react";

function CustomDashboard({ date }: { date: number }) {
  const { data: summary, isLoading: s1 } = useSummaryCards({ date });
  const { data: report, isLoading: s2 } = useMemberReport({ date, pageSize: 5 });

  if (s1 || s2) return <p>Đang tải...</p>;

  return (
    <div>
      <div style={{ display: "flex", gap: 16 }}>
        <div>
          {summary?.activeUsers.active} / {summary?.activeUsers.total} nhân viên
        </div>
        <div>{summary?.totalDistance.value} km</div>
        <div>{summary?.totalFuelCost.formatted}</div>
      </div>
      <table>
        <tbody>
          {report?.users.map((m) => (
            <tr key={m.userId}>
              <td>
                {resolveMemberName(m.lastLocation?.metadata, "userName") ??
                  m.userId}
              </td>
              <td>{m.distance.value} km</td>
              <td>{m.statusLabel}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

import { useRef } from "react";
import {
  FleetworkProvider,
  LiveMap,
  type LiveMapRef,
} from "@vietmap/tracking-sdk-react";
import "@vietmap/tracking-sdk-react/styles.css";

export default function MapPage() {
  const mapRef = useRef<LiveMapRef>(null);

  return (
    <FleetworkProvider apiKey="YOUR_API_KEY">
      <div style={{ padding: 8, display: "flex", gap: 8 }}>
        <button
          onClick={() =>
            mapRef.current?.fitBounds([
              [105.8, 21.0],
              [106.7, 10.7],
            ])
          }
        >
          Fit All
        </button>
        <button onClick={() => mapRef.current?.setStatusFilter(["moving"])}>
          Chỉ hiện xe đang chạy
        </button>
      </div>
      <LiveMap
        ref={mapRef}
        apiKeyTilemap="YOUR_VIETMAP_TILE_KEY"
        height="calc(100vh - 48px)"
        center={[106.6, 10.8]}
        zoom={12}
        pollInterval={10_000}
        onMarkerClick={(member) => {
          alert(`${member.name} — ${member.statusLabel}`);
          return false;
        }}
        renderMarkerPopup={(member) => (
          <div style={{ minWidth: 180 }}>
            <strong>{member.name}</strong>
            <div>{member.lastAddress ?? "—"}</div>
            <div>Tốc độ: {member.speed ?? 0} km/h</div>
          </div>
        )}
      />
    </FleetworkProvider>
  );
}