🔔 Backend notifications

Introduction

1️⃣ Before diving into the Notification service, ensure you understand the High-level architecture concept, particularly the section about the multi-instance platform. In this context, an instance is the foundational unit for Notification services. Rules and settings are set at the instance level, affecting all users within that instance.

This approach offers tremendous flexibility to your product. Specifically, you can categorize users into distinct groups and establish unique rules for export, including destination, even for users from a single mobile app.

2️⃣ Familiarize yourself with Data management options and the provided datasets.

Setting up

There are 2 steps to complete configuration:

Select and configure notification provider:
Configure Damoov platform
Process received notifications

Select and configure notification provider:

Integration of Notification Services for Backend: ➡️ Setup Guide
If you're looking to extract data from the Damoov platform and manage it on your own server, this part is essential. Currently, we support the following notification services:

Every dataset accessible through the data export service is associated with a unique event type. You can find a comprehensive list of these types and sample data Here

Configure Damoov platform

Ensure you possess the essential details before beginning the configuration:

Service provider	Required details
AWS	- Access Key, - Secret Key, - TopicArn
Azure event grid	- TopicKey, - Endpoint
Azure service bus	- Endpoint - SharedAccessKeyName - SharedAccessKey

Visit Damoov Portal to complete the configuration: https://portal.damoov.com/callbacks

Process received notifications

There are two types of notifications:

Notifications with URL inside the message body (Trips, Claims)
Notifications with message body only (Heartbeats)

Notifications with URL inside the message body (Trips, Claims)

To retrieve data from the URL, you need to use Get Request and provide UserId (UserId=DeviceToken) as a Header:

curl --location --request GET 'https://mobilesdk.telematicssdk.com/mobilesdk/stage/track/get_track/v1?TrackToken=b6xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxec' \
--header 'DeviceToken: 4cccxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxa5'

Type of notifications

TRIPS:

IncomingTrackRemoved (the track was deemed invalid or excluded) - it may include walking, cycling, and walking activities prior to driving and after driving.
IncomingTrackReceived (the track was valid and has been stored as Raw Trips Data) (Recommended)
TrackEnrichmentFinished (a track has been converted from raw to processed) (Recommended)

Notification sample

{
  "Event": "IncomingTrackRemoved",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "IncomingTrackSummary",
    "Url": "https://mobilesdk.telematicssdk.com/mobilesdk/incoming/incoming/tracks/removed/9347f5eb-7aca-48c3-b698-f2c7b35add29/v1/"
  },
  "Timestamp": "2020-07-20T14:44:54.9074056Z",
  "Details": {
    "TrackStartDate": "2020-04-29T09:20:48.0000000-06:00",
    "TrackFinishDate": "2020-04-29T09:57:02.0000000-06:00",
    "Reason": "Insufficient Track length"
  }
}

{
  "Event": "IncomingTrackReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "IncomingTrack",
    "Url": "https://mobilesdk.telematicssdk.com/mobilesdk/incoming/incoming/tracks/received/9347f5eb-7aca-48c3-b698-f2c7b35add29/v1/"
  },
  "Timestamp": "2020-07-20T14:44:54.9074056Z",
  "Details": {
    "TrackStartDate": "2020-04-29T09:20:48.0000000-06:00",
    "TrackFinishDate": "2020-04-29T09:57:02.0000000-06:00"
  }
}

{
  "Event": "TrackEnrichmentFinished",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "RichTrack",
    "Url": "https://mobilesdk.telematicssdk.com/mobilesdk/stage/track/get_track/v1?trackToken=9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2020-07-20T14:44:54.9074056Z",
  "Details": {
    "ObjectReplaced": true,
    "TracksRemoved": [
      {
        "Id": "3337f5eb-7aca-48c3-b698-f2c7b35add29",
        "Type": "RichTrack"
      },
      {
        "Id": "4447f5eb-7aca-48c3-b698-f2c7b35add29",
        "Type": "RichTrack"
      }
    ]
  }
}

CRASH:

Crash notification - 4 - AccidentEventReceived
Crash Data Buffer Received - 5 - AccidentEventExtraReceived
The full set of crash data received - 6 - AccidentEventCompletePackageReceived
Crash data - 7 - AccidentEventFiltered (recommended)

High-level scheme for crash data

Notification sample

{
  "Event": "AccidentEventReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "Accident",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "DateReceived": "2021-07-20T14:42:54.8884056Z"
  }
}

{
  "Event": "AccidentEventExtraReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "AccidentExtra",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/extras/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "DateReceived": "2021-07-20T14:42:54.8884056Z"
  }
}

{
  "Event": "AccidentEventCompletePackageReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "Accident",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "PackageDateReceived": "2021-07-20T14:42:54.8884056Z",
    "AccidentPassedFilters":  true
  }
}

{
  "Event": "AccidentEventFiltered",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "Accident",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "DateFiltered": "2021-07-20T14:42:54.8884056Z"
  }
}

PHONE STATUS

Status update (Heartbeat

Notification sample

{
  "Event": "HeartbeatReceived",
  "Sender": "Damoov",
  "UserId": "4dbf7a0f-d4ed-4a38-867c-1a4bbd84d089",
  "ClientId": "Gocha",
  "Timestamp": "2023-09-18T22:38:02.4974696Z",
  "Object": {
    "Id": "4dbf7a0f-d4ed-4a38-867c-1a4bbd84d089",
    "Type": "RawHeartbeat",
    "Uri": null
  },
  "Details": {
    "ChargeLevel": 89.4,
    "WifiEnabled": true,
    "GPSEnabled": true,
    "RealTimeLocationEnabled": false,
    "MobileDataEnabled": true,
    "NotUploadedTripsCount": 6,
    "InstanceId": "3c1c8fd7-4133-404a-82e9-93a015d85362",
    "TimeReceived": "2023-09-18T22:37:53.7273284Z"
  }
}

Data samples

For your convenience, we've attached the data from a sample trip (recorded in March 2021 outside Cambridge, UK)

Raw Telematics data (notification IncomingTrackReceived) Download JSON file, 1.2 MB
note that an IncomingTrackRemoved notification technically also links to an object similar to this one, but it will contain little or no useful information, but may be used for troubleshooting if you get many invalid tracks.
Processed Trip Data (notification TrackEnrichementFinished) Download JSON file, 341 kB

Data Format Reference

👉 Raw telematics data
👉 Processed telematics data
👉 Crash data

Data processing workflow for vehicle data

Item 5 in the schematic at the top

Note that this is an advanced and rare use case. For most driver behavior and fleet management use cases, you will not need to use this.

Vehicle data collection is an advanced feature that is available as an add-on, and it works as follows: The SDK connects through Bluetooth to a so-called OBD (On-Board Diagnostics) device that talks directly to the car's onboard computer to get data like engine failure codes, maintenance status, etc. One example would be to generate a notification when the "Check Engine" light is on.
This feature requires additional hardware 👉 Bluetooth OBD and communication via Bluetooth, and requires specific knowledge of the make and model of the car. It is most commonly used by fleet apps that actively manage the vehicles and their maintenance.
👉 In-vehicle data

In general, vehicle data is handled in a similar fashion to GPS and Sensor data; data is filtered and enriched, and notifications are sent when a new dataset is available.

Accessing these datasets

Now that we've discussed the main categories of data and how they are processed, let's see how you can access that data. This consists in principle of two steps:
Option API:

Get a notification that a new dataset has been processed
Access the API to download the data referenced in the notification
Option Third-party storage
Data gets copied by us to your preferred storage provider
Get a notification that a new dataset has been copied

Notifications

When a dataset moves from one stage to the next on the Damoov platform, it creates an event. You can subscribe to those events to then access the relevant data

📘
Note
Notification message doesn't contain any track’s data, such as events or waypoints. To get these details, you have to query the track’s data using the Web API service, using credentials received from SNS Message.

We support several well-known notification services, including Amazon and Azure. Each notification contains URLs, identifiers, and credentials for the respective dataset.

🚧
Important
Your back-end or application had to be prepared to receive several notifications related to a single trip. It means the previous version of the track has been updated, and you need to retrieve an updated version from our API again.

An Example where this happens would be that the track was merged with another trip segment. the updated trip will have new trip details (time, distance, etc)

Setting up notifications through Amazon SNS

to set up Amazon SNS, please go to Datahub -> Management -> Platform integration

👉 How to register AWS SNS

The following AWS information is required to complete the setup:

AccessKey
Secret
AWS Region
TopicArn of the SNS queue

Setting up notifications through Azure Service Bus

to set up Amazon SNS, please go to Datahub -> Management -> Platform integration
👉 More about Azure service bus

The following Azure information has to be entered to complete the setup:

Endpoint=sb://site.servicebus.windows.net/;
SharedAccessKeyName=SampleAccessPolicy;
SharedAccessKey=s4-0/Lkj4gsmFfro1/s08+E/0DtjtGG7y5q1Pxm4G2Q=

Setting up notifications through Azure Event grid

👉 More about Azure event grid

The following Azure information has to be entered to complete the setup:

Endpoint:https://samplegridtopic01.eastus-1.eventgrid.azure.net/api/events
TopicKey:fFWO97gfd21je0KgChLbLkBRMfG7mfMiQ8P53AmdbyWw=

🔔 Backend notifications

Introduction

Setting up

Select and configure notification provider:

Configure Damoov platform

Process received notifications

Type of notifications

Data samples

Data Format Reference

Data processing workflow for vehicle data

Accessing these datasets

Notifications

📘
Note

🚧
Important

Setting up notifications through Amazon SNS

Setting up notifications through Azure Service Bus

Setting up notifications through Azure Event grid

Introduction

Setting up

Select and configure notification provider:

Configure Damoov platform

Process received notifications

Type of notifications

Data samples

Data Format Reference

Data processing workflow for vehicle data

Accessing these datasets

Notifications

📘Note

🚧Important

Setting up notifications through Amazon SNS

Setting up notifications through Azure Service Bus

Setting up notifications through Azure Event grid

📘
Note

🚧
Important