Integration Guide
0 mins to read
Geotab Drive Add-in SDK
Integration Guide
0 mins to read
Learn how to configure and use the Geotab Drive Add-In Software Development Kit, including information on startup, shutdown, and notifications functions. The Drive App allows Add-ins to send, dismiss, and update native notifications.
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.
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:
- hasPermission,
- requestPermission,
- notify,
- update, and/or
- 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 |
