Geotab Deeper Add-In Overview

Deeper Add-Ins, also referred to as Deeper Integrations or simply Map Add-Ins, embed third-party integrations within the Maps page and the Trips History page of MyGeotab, enabling Geotab customers to access the integration from within the native MyGeotab Map and Trips History pages. A panel will slide out on the right-side of the page, allowing users to manipulate the map and see data presented by the integration alongside Geotab GO device data.

Below is an example of a Deeper Add-In on the Trips History page. When a user hovers over any part of a trip, this add-in displays the vehicles odometer and fuel level in the native tooltip that appears when hovering your mouse over any part of the trip. Note that the other details in the tooltip are displayed by the MyGeotab system by default.

Example of adding new information to vehicle tooltip on the map.
Pic 1 - Tooltip with additional information.

This document provides the setup process and functionality available to Partners looking to build Deeper Add-Ins.

How to Install Deeper Add-Ins

Deeper Add-Ins are installed on the System Settings page, just like regular Add-Ins. The difference is in the contents of the configuration file. Deeper Add-Ins have following configuration JSON file:

    
{
    "name": "Tooltip",
    "supportEmail": "",
    "version": "1.0",
    "items": [{
        "page": "map",
        "title": "Tooltips",
        "noView": false,
        "mapScript": {
            "src": "/tooltip/addin.js",
            "style": "/tooltip/addin.css"
        }
    }]
}
    

The five main properties of the configuration file are as follows:

  1. page - Defines which page the Add-In will exist within. It has two possible values: “map” (for the Maps page) or “tripsHistory” (for the Trips History page). The default value is “map”.
  2. src - JavaScript file reference for this Add-In. In the example above, the JS file was dropped into MyGeotab, but an external reference is possible and recommended.
  3. style - CSS file reference for this Add-In.
  4. title - The title that will be displayed in the right-side panel if there are multiple Deeper Add-Ins installed.
  5. url - HTML file reference for this Add-In. This option should be used instead of src and style. All link to stylesheets and javascript modules can be listed in this HTML file. Also all content of the <body> tag will be automatically added to add-in tab. (Example).
  6. noView - If true add-in won't be shown in the right-side panel.

The script file from the “src” property and the style file from the “style” property will be added to the MyGeotab page iframe in the right-side panel.

The starting point for the Deeper Add-In JS script will be the function that is added as a method to “window.geotab.addin”. For example:

    
geotab.addin.request = (elt, service) => {
    // code for Deeper Add-In
}
    

This function has two arguments:

  1. elt - The HTMLElement for the Add-In. Inside it is everything that belongs to the Add-In. Nothing will be removed or changed.
  2. services - JavaScript file reference for this Add-In. In the example above, the JS file was dropped into MyGeotab, but an external reference is possible and recommended.

How Deeper Add-Ins are Opened Inside MyGeotab

In MyGeotab, Deeper Add-Ins are opened inside an sandboxed iframe. This means that custom scripts is run inside the iframe.

There are a few differences between a script run in the browser and a script run inside an iframe. When the user leaves the Map or Trips History page, the content of the iframe is cleared by the browser.

  • When the user returns to the page, the scripts inside the iframe are reloaded.
  • The current Add-In state should be saved in localStorage, IndexedDB, or elsewhere, if necessary.

Don't access any elements or API in main window because they can be changed in future. To make sure that your add-ins won't be broken in later versions of MyGeotab all communications with main window should be made with documented services.

The maximum width of the Deeper Add-In panel is 450 px. The height is responsive to fill the height of the iframe that the panel exists within. The width may become smaller for mobile devices.

The following screenshots display how the panel size changes between a laptop screen and a mobile phone screen.

Example of how map add-ins look like on laptop screen size
Pic 2 - Add-ins on the map page (desktop).
Example of how map add-ins look like on mobile screen size
Pic 3 - Add-ins on the map page (mobile).

Each Deeper Add-In exists within its own tab on the right-side panel. Each Add-In has its own HTMLElement where it can append content. The Add-In function will be called when a user visits the Add-In by clicking on its tab. After that, the “focus” and “blur” events will be fired when the user opens or leaves the Add-In tab, respectively (See services.page).

The screenshot below displays the tabs for different Deeper Add-Ins. The different Add-Ins are named “Canvas”, “Hello from the other side of the frame”, and “Tooltip for map”.

Example of how tabs looks like if multiple map add-ins are installed
Pic 4 - Multiple add-ins on the map page.

Deeper Add-In Services

page service (Example)

Service for getting/setting page state and moving between MyGeotab page

Methods

Service methodsDescription
set (key: string, value: string): Promise<boolean>Sets new key/value pair to page state
get (): Promise<object>Gets page state
go (page: string, state?: object): Promise<boolean>Changes current page
hasAccessToPage (page: string): Promise<boolean>Checks whether current user has access to MyGeotab page
getFilterState (): Promise<IGroupFilterId[]>Gets current company filter state
attach (eventName: string, eventHandler: (serviceData: any) => void): voidAttaches event handler to service
detach (eventName: string, eventHandler?: (serviceData: any) => void): voidDetaches event handler to service

Properties

Service property nameTypeDescription
activebooleanCurrent map add-in state. It's true if current add-in is focused

Events

Event nameEvent objectDescription
focusEmpty objectEvent is fired when user focuses on current map add-in
blurEmpty objectEvent is fired when user focuses on another map add-in
stateChange
state: (object) - Updated page state
Event is fired when the state of the page is changed
filterChange
groups: (IGroupFilterId[]) - Updated array of filter groups
Event is fired when the company filter groups is changed

Interface IGroupFilterId

Group id object that is selected by user in company filter

PropertyType
idstring

localStorage service (Example)

Service to request information stored in browser LocalStorage

Methods

Service methodsDescription
set (key: string, value: string): Promise<boolean>Sets key-value pairs to browser localStorage with key
remove (key: string): Promise<boolean>Removes value from browser localStorage by key
get (key: string): Promise<string>Gets value from browser localStorage by key

api service (Example)

Service for requesting data from Geotab server

Methods

Service methodsDescription
call (method: string, params: object): Promise<any[]>Sends single request to Geotab server
multiCall (calls: TApiCall[]): Promise<any[][]>Sends multiple requests to Geotab server in one batch
getSession (): Promise<ISessionInfo>Gets current user session information

Interface ISessionInfo

Current user session information

PropertyType
databasestring
userNamestring
sessionIdstring
domainstring

Type TApiCall

[string, object]

Tuple for calling server methods where first element is method name and second is an object with parameters.

events service (Example)

Service for catching events that happens when user interact with different entities on the map

Methods

Service methodsDescription
attach (eventName: string, eventHandler: (serviceData: any) => void): voidAttaches event handler to service
detach (eventName: string, eventHandler?: (serviceData: any) => void): voidDetaches event handler to service

Events

Event nameEvent objectDescription
move
data: (ICoordinate) - Position of the pointer on the map
Event is fired when user moves pointer over the map
over
data: (TEventData) - Main information about entity
Event is fired when user moves pointer over an obejct on the map
out
data: (TEventData) - Main information about entity
Event is fired when user moves pointer out of an obejct on the map
click
data: (TEventData) - Main information about entity
Event is fired when user clicks on an obejct on the map

Interface IZoneEvent

Event object that is sent to add-in when user interacts with zone

PropertyType
type"zone"
entityIZoneEventData

Interface IZoneEventData

Zone object that is sent to add-in when user interacts with zone

PropertyType
idstring

Interface IDeviceEvent

Event object that is sent to add-in when user interacts with device

PropertyType
type"device"
entityIDeviceEventData

Interface IDeviceEventData

Device object that is sent to add-in when user interacts with device

PropertyType
idstring

Interface IRouteEvent

Event object that is sent to add-in when user interacts with route

PropertyType
type"route"
entityIRouteEventData

Interface IRouteEventData

Route object that is sent to add-in when user interacts with route

PropertyType
idstring

Interface ITripEvent

Event object that is sent to add-in when user interacts with trip

PropertyType
type"trip"
entityITripEventData

Interface ITripEventData

Trip object that is sent to add-in when user interacts with trip

PropertyTypeDescription
idstringId of the trip
device{ id: string; }Device id object that drove this trip
dateTimestringDate and time of the trip point

Interface IExceptionsEvent

Event object that is sent to add-in when user interacts with device exceptions

PropertyType
type"exceptions"
entityIExceptionsEventData

Interface IExceptionsEventData

Exceptions object that is sent to add-in when user interacts with exception icon on the map

PropertyType
exceptionsIExceptionEventData[]

Interface IExceptionEventData

Exception object that is sent to add-in when user interacts with exception icon on the map

PropertyTypeDescription
tostringDate and time when this exception ends
fromstringDate and time when this exception starts
idstringId of the exception
rule{ id: string; }Rule id object of this exception
device{ id: string; }Device id object where this exception happen

Type TEventData

IZoneEvent | IDeviceEvent | IRouteEvent | ITripEvent | IExceptionsEvent

Event object that is sent to add-in when user interacts with different types of entitis on the map

map service (Example)

Service for manipulating viewport of the map and getting updates about changed map viewport

Methods

Service methodsDescription
setBounds (bounds: IMapBounds): Promise<boolean>Sets map bounds
getBounds (): Promise<IMapBounds>Gets current map bounds
setZoom (zoom: number): Promise<boolean>Sets map zoom level
getZoom (): Promise<number>Gets current map zoom level
attach (eventName: string, eventHandler: (serviceData: any) => void): voidAttaches event handler to service
detach (eventName: string, eventHandler?: (serviceData: any) => void): voidDetaches event handler to service

Events

Event nameEvent objectDescription
changeEmpty objectEvent is fired when viewport of map is changed. This event fires each time when use drags or zooms map
changed
viewport: (IChangedViewport) - Current map zoom and bounds
Event is fired when user finished dragging and zooming map

Interface IChangedViewport

Current map viewport

PropertyTypeDescription
zoomnumberCurrent map zoom
boundsIMapBoundsCurrent map bounds

Interface IMapBounds

Object that represents a map bounding box.

PropertyTypeDescription
swIMapLatLngThe southwest corner of the bounding box.
neIMapLatLngThe northeast corner of the bounding box.

Interface IMapLatLng

An object that represents longitude and latitude

PropertyTypeDescription
latnumberLatitude, measured in degrees.
lngnumberLongitude, measured in degrees.

tooltip service (Example)

Service for showing additional information in entities tooltip

Methods

Service methodsDescription
showAt (position: TPosition, pattern: ITooltip, sequence: number): voidShows custom tooltip at certain position on the map
show (pattern: ITooltip, sequence: number): voidAdds additional information to already shown tooltip on the map
hide (): voidHids additional information from already shown and custom tooltip
setConfig (config: ITooltipConfig): Promise<boolean>Sets configuration for changing current application tooltip
getConfig (): Promise<ITooltipConfig>Sets configuration for current application tooltip

Interface ITooltip

Custom map add-in tooltip options. It can be either a text information or an image

PropertyTypeDescription
iconstringIcon image for custom tooltip part.
imageITooltipImageImage options that should be shown instead of text in tooltip
mainstringMain tooltip text
secondarystring[]Secondary information that will be written with smaller font
additionalstring[]Some additional tooltip information

Interface ITooltipImage

Custom tooltip image options. It can be either link to external image, base64 image or image stored in ArrayBuffer

PropertyTypeDescription
urlstringEither link to external image or serialized base64 image or stringified SVG image
bufferArrayBufferImage stored in ArrayBuffer
widthnumberWidth of the image
heightnumberHeight of the image

Interface ITooltipConfig

Application tooltip config. Based on this config application desides what parts of tooltip should be rendered

PropertyTypeDescription
deviceIDeviceTooltipConfigChanges information in devices tooltip

Interface IDeviceTooltipConfig

Device tooltip config to control amount of information that is shown in tooltip.

PropertyTypeDescription
statebooleanShows/hides current device state in tooltip
groupsbooleanShows/hides device groups information in tooltip

actionList service (Example)

Service for showing a custom action list instead of the existing one, or adding custom buttons to existing action lists.

Methods

Service methodsDescription
show (position: TPosition, title: string, items: IMenuActionItem[]): voidShows custom action menu on certain position
attachMenu (menuName: TMenuType, handler: TMenuHandler): voidSubscribes on event when one of the MyGeotab map menus is shown to add new action button
detachMenu (menuName: TMenuType, handler?: TMenuHandler): voidUnsubscribes on event when one of the MyGeotab map menus is shown
attach (eventName: string, eventHandler: (serviceData: any) => void): voidAttaches event handler to service
detach (eventName: string, eventHandler?: (serviceData: any) => void): voidDetaches event handler to service

Events

Event nameEvent objectDescription
CustomEvent
data: (object) - Data from `IAddinActionItem.data` for the current button
Event is fired when user clicks on custom button in action list. Event name is defined by "clickEvent" property in custom button object.

Interface IMenuActionItem

Custom action button options

PropertyTypeDescription
titlestringButton title
iconstringButton icon image
urlstringURL to external page. If this property is used than button will be an anchor element
clickEventstringName of the event that will be fired when user clicks on this button
zIndexnumberNumber that defined position of the custom action button in menu
dataobjectCustom data that will be send with `clickEvent` when user clicks on this button

Interface IMenuEventData

Data that is passed to add-in when all types of map action menus are about to be shown

PropertyType
xnumber
ynumber
menuNamestring
locationILocation

Interface IMapMenuEventData extends IMenuEventData

Data that is passed to add-in when map action menu is about to be shown

Interface IZoneMenuEventData extends IMenuEventData

Data that is passed to add-in when zone action menu is about to be shown

PropertyType
zone{ id: string; }

Interface IRouteMenuEventData extends IMenuEventData

Data that is passed to add-in when route action menu is about to be shown

PropertyType
route{ id: string; }

Interface IMarkerMenuEventData extends IMenuEventData

Data that is passed to add-in when location marker action menu is about to be shown

PropertyType
titlestring

Interface IDeviceMenuEventData extends IMenuEventData

Data that is passed to add-in when device action menu is about to be shown

PropertyType
device{ id: string; }

Interface ITripMenuEventData extends IMenuEventData

Data that is passed to add-in when trip action menu is about to be shown

PropertyType
dateTimestring
device{ id: string; }
tripITripData

Interface ITripData

Trip data that is passed to add-in when trip action menu is about to be shown

PropertyType
startstring
stopstring

Type TMenuType

"zone" | "map" | "device" | "route" | "marker" | "trip"

Types of menus where custom action buttons can be added

Type TMenuHandler

(menuName: string, data: TMenuEventData) => IMenuActionItem[] | Promise<IMenuActionItem[]>

Function that will be called when certain action menu is about to be opened

Type TMenuEventData

IMapMenuEventData | IZoneMenuEventData | IRouteMenuEventData | IMarkerMenuEventData | IDeviceMenuEventData | ITripMenuEventData

Data that is passed to add-in based on type of menu that is shown

canvas service (Example)

Service for drawing custom shapes on the map

Methods

Service methodsDescription
path (path: IPathSeg[], zIndex: number): ICanvasElement<ICanvasPathAttributes>Draws SVG path element on the map
rect (coords: TPosition, width: number, height: number, radius: number, zIndex: number): ICanvasElement<ICanvasRectAttributes>Draws SVG rect element on the map
circle (coords: TPosition, radius: number, zIndex: number): ICanvasElement<ICanvasCircleAttributes>Draws SVG circle element on the map
text (coords: TPosition, text: string, zIndex: number): ICanvasElement<ICanvasTextAttributes>Draws SVG text element on the map
marker (coords: TPosition, width: number, height: number, source: TMarkerSource, zIndex: number): ICanvasElement<ICanvasMarkerAttributes>Draws custom image element on the map
clear (): voidClears all drawn elements on the map

Interface IPathSeg

Segment of the path element that will be added in `d` attribute

PropertyTypeDescription
typestringType of the segment. Supported types `M`, `m`, `L`, `l`, `Z`, `C`, `c`, `S`, `s`
pointsTPathSegPoint[]Locations or coordinates that should be used in current segment

Interface ICanvasElement<T extends TCanvasElementAttributes>

New map element object

MethodDescription
change (attrs: T): ICanvasElement<T>Changes style attributes of the current map element
remove (): voidRemoves current map element
isRemoved (): booleanReturns true if element was removed
attach (event: TCanvasElementEvent, handler: (data: ICoordinate) => void): ICanvasElement<T>Attaches event handler to current element event
detach (event: TCanvasElementEvent, handler?: (data: ICoordinate) => void): ICanvasElement<T>Detaches event handler from current element event

Interface ICanvasElementStyleAttributes

Style properties that can be changed for every custom element

PropertyTypeDescription
fillstringBackground color of the element
strokestringBorder color of the element
stroke-widthnumberBorder width of the element
fill-opacitynumberOpacity of the element
font-sizenumberText element font size
font-weightnumberText element font weight

Interface ICanvasRectAttributes extends ICanvasElementStyleAttributes

Rect element attributes that can be changed for every custom rect element

PropertyTypeDescription
heightnumberHeight of the rectangle
widthnumberWidth of the rectangle
rxnumberThe horizontal corner radius of the rectangle
rynumberThe vertical corner radius of the rectangle
coordsTPositionPosition of the rectangle

Interface ICanvasTextAttributes extends ICanvasElementStyleAttributes

Text element attributes that can be changed for every custom text element

PropertyTypeDescription
dxnumberOffset in pixels x-axios of the element
dynumberOffset in pixels y-axios of the element
textstringText of the element
coordsTPositionPosition of the element

Interface ICanvasCircleAttributes extends ICanvasElementStyleAttributes

Circle element attributes that can be changed for every custom circle element

PropertyTypeDescription
rnumberRadius in pixels of the element
coordsTPositionPosition of the element

Interface ICanvasPathAttributes extends ICanvasElementStyleAttributes

Path element attributes that can be changed for every custom path element

PropertyTypeDescription
pathIPathSeg[]Path of the element

Interface ICanvasMarkerAttributes extends ICanvasElementStyleAttributes

Marker element attributes that can be changed for every custom marker element

PropertyTypeDescription
heightnumberHeight in pixels of the element
widthnumberWidth in pixels of the element
xnumberPosition of the element
ynumberPosition of the element
dxnumberOffset in pixels x-axios of the element
dynumberOffset in pixels y-axios of the element
coordsTPositionPosition of the element
hrefstringImage href of the element
bufferArrayBufferImage ArrayBuffer of the element

Type TPathSegPoint

ILocation | ICoordinate | number

Location or coordinate of the next point

Type TCanvasElementAttributes

ICanvasRectAttributes | ICanvasTextAttributes | ICanvasCircleAttributes | ICanvasPathAttributes | ICanvasMarkerAttributes

Attribute of marker that can be changed for every custom element

Type TCanvasElementEvent

"click" | "over" | "out"

Supported custom map element event types

Type TMarkerSource

string | ArrayBuffer

Marker can be presented as a encoded SVG or base64 string or URL to third party resource or binary array in ArrayBuffer

Interface ICoordinate

PropertyType
xnumber
ynumber

Interface ILocation

PropertyType
latnumber
lngnumber

Type TPosition

ILocation | ICoordinate

Sample Add-Ins

Here are some examples and types definition file that can help developers understand how to work with the new Add-Ins. Please download them, extract the files, then follow the instructions in the ReadMe document. Remember to have Feature Preview enabled in your MyGeotab User Options so you can see the Deeper Add-ins.