Trip Viewer — Integration Guide

Embed an interactive trip map into your web application. The Trip Viewer renders telematics trip data on Google Maps with route visualization, driving events, speed analysis, activity/accuracy heatmaps, and trip replay.

Table of Contents

1. Quick Start
2. Authentication
3. Embedding via iframe
4. URL Parameters — Complete Reference
   • Required Parameters
   • Trip Data Source
   • Display Settings
   • Speed Analysis
   • Heatmap
   • UI Visibility
5. Display Modes
6. Integration Recipes
7. Troubleshooting

1. Quick Start

📘

Configuration builder

The easiest way to get started is with our configuration builder — it lets you set all parameters through a form and preview the result in real time: https://portal-apis.telematicssdk.com/spa/test-harness/

The Trip Viewer is a standalone web page that accepts all configuration through URL parameters. The simplest integration is an iframe:

<iframe
  src="https://portal-apis.telematicssdk.com/spa/trip-viewer/?accessToken=YOUR_JWT&trackId=TRIP_ID&userId=USER_ID"
  width="100%"
  height="600"
  frameborder="0"
  allow="fullscreen"
></iframe>

That's it. The viewer loads the trip, renders the route on the map, and provides interactive controls for the end user.

2. Authentication

Every request requires an authentication token. Two methods are supported:

Option A: JWT Token (accessToken)

Use when your backend already has a valid Damoov JWT.

/spa/trip-viewer/?accessToken=eyJhbG...&trackId=abc-123&userId=user-456

Option B: Short-Term Token (Token)

Use for embedded/iframe scenarios where you generate a short-lived token from your backend. This is the recommended approach for portal integrations — it avoids exposing long-lived tokens in the browser.

/spa/trip-viewer/?Token=short-lived-token&trackId=abc-123

If both accessToken and Token are provided, Token takes priority.

3. Embedding via iframe

Basic iframe

<iframe
  id="trip-viewer"
  src="https://portal-apis.telematicssdk.com/spa/trip-viewer/?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&unitSystem=Si"
  width="100%"
  height="600"
  frameborder="0"
  style="border: 1px solid #e0e0e0; border-radius: 8px;"
  allow="fullscreen"
></iframe>

Dynamic URL construction (JavaScript)

function buildTripViewerUrl(options) {
  const base = 'https://portal-apis.telematicssdk.com/spa/trip-viewer/';
  const params = new URLSearchParams();

  // Required
  params.set('Token', options.token);        // or 'accessToken' for JWT
  params.set('trackId', options.trackId);

  // Optional
  if (options.userId)              params.set('userId', options.userId);
  if (options.unitSystem)          params.set('unitSystem', options.unitSystem);
  if (options.incomingTrackToken)  params.set('incomingTrackToken', options.incomingTrackToken);
  if (options.viewMode)            params.set('viewMode', options.viewMode);
  if (options.hideLayers)          params.set('hideLayers', 'true');
  if (options.showReplay === false) params.set('showReplay', 'false');

  return `${base}?${params.toString()}`;
}

// Usage
const url = buildTripViewerUrl({
  token: 'short-lived-token',
  trackId: 'abc-123',
  userId: 'user-456',
  unitSystem: 'Si'
});

document.getElementById('trip-viewer').src = url;

Responsive iframe

<div style="position: relative; width: 100%; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe
    src="https://portal-apis.telematicssdk.com/spa/trip-viewer/?Token=TOKEN&trackId=TRACK_ID"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
    allow="fullscreen"
  ></iframe>
</div>

4. URL Parameters — Complete Reference

Required Parameters

Trip Data Source

Display Settings

Speed Analysis

Heatmap

Speed (Activity) — activity classification by speed:

Accuracy heatmaps (raw GPS data only):

UI Visibility

5. Display Modes

The Trip Viewer can show up to two data sources at once:

Processed Trip (viewMode=processed)

The default when only trackId is provided. Shows the server-calculated route with:

• Route polyline (dark blue)
• Speeding segments (red)
• Phone usage segments (cyan)
• Incident markers (Acceleration, Braking, Cornering icons)
• Start/end pins

Raw GPS Trip (viewMode=raw)

The default when only incomingTrackToken is provided. Shows the raw device GPS trace with:

• Route polyline (blue)
• Optional accuracy heatmap overlay
• Optional incident markers
• Start/end pins

Both (viewMode=both)

Shows both layers simultaneously. The processed route is rendered at 50% opacity so the raw GPS trace is visible underneath. Useful for comparing server-processed route quality against raw device data.

6. Integration Recipes

Simple trip display (most common)

Show a processed trip with default settings. End users can toggle layers using the built-in panel.

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&unitSystem=Si

Compact embed — no controls

Display a clean map with no panels or replay bar. Good for dashboards or thumbnail previews.

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&hideLayers=true&showReplay=false

Trip comparison — processed vs raw GPS

Show both data sources so users can compare route quality.

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&incomingTrackToken=RAW_TOKEN&viewMode=both

Fleet manager — speed compliance view

Highlight all points where the driver exceeded 80 km/h with clustered markers.

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&speedThreshold=80&clusterSpeed=true

Speed compliance — posted speed limits

Highlight every point where the driver exceeded the posted road speed limit.

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&speedThreshold=maxspeed

Activity classification — speed heatmap

Color the route by speed to distinguish walking, cycling, urban driving, and highway driving. Works on processed data, raw data, or both.

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&heatmapMode=speedActivity

Data quality review — GPS accuracy

Show raw GPS heatmap colored by signal accuracy for diagnostics.

?Token=TOKEN&incomingTrackToken=RAW_TOKEN&userId=USER_ID&heatmapMode=gpsAccuracy&showRawDots=true

Detailed trip analysis — all features on

Full-featured view with all data points visible and replay enabled.

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&incomingTrackToken=RAW_TOKEN&viewMode=both&showProcessedDots=true&showRawDots=true&showReplay=true

Imperial units (US/UK)

?Token=TOKEN&trackId=TRACK_ID&userId=USER_ID&unitSystem=Imperial

7. Troubleshooting

"Error: No authentication token provided"

Neither accessToken nor Token is present in the URL. Add one of them.

"Error: Please provide at least trackId or incomingTrackToken"

No trip identifier was given. Add trackId for a processed trip or incomingTrackToken for a raw GPS trip.

"Authentication Error" / token expired

The JWT or short-term token has expired. Generate a new token from your backend and reload the viewer with the fresh token.

"Trip Not Found" (404)

The trackId does not match any trip in the system. Verify the trip ID and that the authenticated user has access to it.

"No Raw Data Available"

The raw GPS data is not available for this trip. This typically happens with older trips where raw data has expired or was not collected by the device.

Map loads but shows no route

• Verify that the userId matches the user who recorded the trip.
• Check that unitSystem is a valid value (Si, Metric, or Imperial).
• Open the browser developer console (F12) and look for [PERFORMANCE] or [RAW TRIP] log entries for more details.

Raw GPS route not visible alongside processed trip

• Ensure both trackId and incomingTrackToken are provided.
• Set viewMode=both to explicitly show both layers.
• The raw API requires a valid JWT (accessToken). Short-term tokens (Token) may not have access to the raw data endpoint.

Heatmap not showing

• speedActivity works on both processed and raw data — it will appear whenever any route data is visible.
• Accuracy heatmaps (gpsAccuracy, speedAccuracy, verticalAccuracy) require raw GPS data. Make sure incomingTrackToken is provided and viewMode is set to raw or both.

Layers panel remembers old settings

The viewer stores layer visibility preferences in the browser's localStorage. URL parameters always override stored preferences. To force a specific configuration, include the relevant parameters explicitly in the URL (e.g. showSpeeding=true&showEvents=false).