Integration Guide

0 mins to read

July 2022

Startup

Configuration

The onStartup property must be set to true to execute an Add-In when logging in to Geotab Drive. An example of the configuration is provided below:

{

"name": "My First Geotab Add-In",

"supportEmail": "myname@mycompany.com",

"version": "1.0",

"items": [...],

"files": { },

"key": "12345-MYAPIKEY",

"signature": "12345-MYSIGNATURE",

"onStartup": true

}

Add-In Execution on Startup

Startup Add-Ins are executed when a driver logs in to the Drive App for the first time.

document Image

When the dashboard page is visible, the startup method is only called once. If the user navigates away from the page then navigates back, the startup method is not called again. If the Add-In requires re-initialization, the user must either log out and log in again, or refresh the application.

<html>

<head>

<script>

geotab.addin.drive = function () {

return {

startup: function (freshApi, freshState, initializeCallback) {

// Code that needs to be executed on dashboard should go here

initializeCallback();

},

initialize: function (freshApi, freshState, initializeCallback) {

console.log("initialize", foo);

initializeCallback();

},

focus: function (freshApi, freshState) {

},

blur: function (freshApi, freshState) {

},

};

};

</script>

</head>

<body>

<div id="addin-container"></div>

</body>

</html>

NOTE: With both startup and initialization, the callback will only be executed when a user navigates to the dashboard or Add-In page. However, the focus and blur methods are called every time the Add-In page is accessed.

Shutdown

Configuration

The onShutdown property must be set to true to execute an Add-In when logging out of Geotab Drive. An example of the configuration is provided below:

{

"name": "My First Geotab Add-In",

"supportEmail": "myname@mycompany.com",

"version": "1.0",

"items": [...],

"files": { },

"key": "12345-MYAPIKEY",

"signature": "12345-MYSIGNATURE",

"onShutdown": true

}

If the onShutdown property is not set to true, the Add-Ins are only executed when the user manually goes to the desired Add-In page, and only initialize, focus, and blur methods are called.

Add-In Execution on Shutdown

Shutdown Add-Ins are executed when the final driver logs out of the Drive App. If there are co-drivers, and one of the co-drivers logs out (while other drivers remain logged in to the Drive App), the shutdown Add-In is not executed.

Additionally, the Add-In is expected to return a promise since shutdown Add-Ins have a 15-second time limit to perform their function before the Add-Ins time out and the logout process is completed. The time limit prevents the application from freezing in the middle of the logout process as a result of faulty Add-Ins.

<html>

<head>

<script>

geotab.addin.drive = function () {

return {

shutdown: function (api, state, callback) {

return new Promise (resolve => {

// Do work, make any api calls etc

resolve() // eventually need to call this somewhere so the promise resolves

}

}

};

};

</script>

</head>

<body>

<div id="addin-container"></div>

</body>

</html>

NOTE: The shutdown method takes in a callback but is not required to be called to correctly function.

Notifications

The Drive App allows Add-Ins to send, dismiss, and update native notifications. All methods work asynchronously and return a promise.

If api.mobile.exists(), you can use the following methods under api.mobile.notification:

  1. hasPermission,
  2. requestPermission,
  3. notify,
  4. update, and/or
  5. cancel.

hasPermission

The hasPermission asynchronously checks the notification permission for the Drive App and returns a promise. An example is provided below:

function addinCheckNotificationPermission(){

api.mobile.notification.hasPermission().then( result => console.log(result) ).catch( error => console.log(error) ) }

Output

Apps that have permission

Notification permission granted

Apps that do not have permission

Notification permission not granted

requestPermission

The requestPermission prompts the user to grant notification permission for the Drive App so Add-Ins can send messages to users through the application. An example is provided below:

function addinRequestNotificationPermission(){

api.mobile.notification.requestPermission().then( result => console.log(result) ).catch( error => console.log(error) ) }

Output

Apps that already have permission

Notification permission already granted

User grants notification permission

Notification permission granted

User denies notification permission

Notification permission denied

For app that has iOS, a Drive App version 5.0 or lower, and notification permission not granted

Request notification permission is not supported.

notify

The notify method sends a native notification to the user with the provided title and message. If the application does not yet have notification permission, we will requestNotificationPermission() then notify() if the user granted permission; otherwise the promise is rejected. An example is provided below:

function addinSendNotification(message: string, title: string){

api.mobile.notification.notify(message, title).then( result => console.log(result) ).catch( error => console.log(error) ) }

Output

App notification successfully sent

{

"id":0,

"text":"Message",

"title":"Title",

"icon":"res://ic_stat_notification",

"smallIcon":"res://ic_stat_notification",

"priority":1

}

Note: When the notification is successfully sent, the promise is resolved with the message object the Drive App just sent. You may use the id reference for update and cancel at a later time.

App does not have notification permission

Notification permission denied

For app that has iOS, a Drive App version 5.0 or lower, and notification permission not granted

Request notification permission is not supported

update

The update method allows you to update the content of active notifications. To update active notifications that have not yet been acknowledged, the original notification id -- created at the time the notification is sent -- must be provided.

function addinUpdateNotification(message: string, title: string, id: number){

api.mobile.notification.update(message, title, id).then( result => console.log(result) ).catch( error => console.log(error) ) }

Output

Message successfully updated

{

"id":0,

"text":"Updated Message",

"title":"Title",

"icon":"res://ic_stat_notification",

"smallIcon":"res://ic_stat_notification",

"priority":1

}

Active message with given ID does not exist

No active message with ${id}

App does not have notification permission

Notification permission denied

cancel

The cancel method dismisses an active message with the given ID. An example is provide below:

function addinCancelNotification(id: number){

api.mobile.notification.cancel(id).then( result => console.log(result) ).catch( error => console.log(error) ) }

Output

Apps that have permission

Notification permission granted

Apps that do not have permission

Notification permission not granted

scroll-up