DataTool | Troubleshooting

I. You’ve made a trip but don’t see it in UserDataHub

Possible causes:

  1. SDK is disabled
  2. Not all required permissions have been granted
  3. Trips got stuck on a smartphone
  4. Trips were recognized as invalid / excluded

1. SDK is disabled

How to investigate and resolve:

  1. Follow to UserDataHub -> DataTool
  2. Search the user by DeviceToken (Email / Phone / Name / Client ID)
  3. Follow to Services => Tracking
  4. The value should be “True”.

A) If tracking is “False” or “No Data”, please check the SDK installation
B) If tracking is “True”, please check heartbeats (device status):

How to check heartbeats (device status):

  1. Follow to UserDatahub -> DataTool
  2. Search the user by DeviceToken (Email / Phone / Name / Client ID)
  3. Scroll down to “Export Data” section
  4. Select dates and export “Heartbeats” CSV file

🚧

What is Heartbeat (device status)?

:point-right: Learn more here

When the Telematics SDK is initialized it sends a first heartbeat, so, if your heartbeats file is empty or you have a notification “No data” when export, it means SDK doesn’t work. It can be caused by improper SDK installation or required permissions haven’t been granted yet.

If the heartbeats CSV file has records, it means SDK is installed properly, and as the next step you have to check permissions.

2. Check if all required permissions have been granted

How to investigate and resolve:

  1. Follow to UserDataHub => DataTool
  2. Search the user by DeviceToken (Email / Phone / Name / Client ID)
  3. Follow to the Status section and check the permission Status and if all required permissions have been granted:
  1. If all the required permissions have been granted, also check the “Permissions Changes” CSV file in the “Export Data” section below. It helps you to verify that no permission manipulations occured before/after/during the time of the supposed trip.
  1. If any of required permissions have not been granted and (or) the user made manipulations with permissions :point-right: contact the user and send the Permissions Guide depending on the user's OS version:
    iOS: https://docs.telematicssdk.com/docs/permissions-in-ios
    Android: https://docs.telematicssdk.com/docs/permissions-in-android

  2. If all the required permissions have been (were) granted correctly, please check “Heartbeats” CSV if the trip was detected.

How to check if the SDK recognized trips

  1. Follow to UserDatahub -> DataTool
  2. Search the user by DeviceToken (Email / Phone / Name / Client ID)
  3. Scroll down to “Export Data” section
  4. Select dates and export “Heartbeats” CSV file

Heartbeats contain important information that you can use for troubleshooting. Heartbeats are triggered and sent every time when important events occur. Column “Reason” provides information about the activity that triggers the heartbeat:

🚧

What is Heartbeat (device status)?

:point-right: Learn more here

Please find in the column “Created” an approximate time (UTC) of your trip and check if the heartbeat with the reason “Track start” was created. If the heartbeat exists, that means the SDK detected and started recording the trip. That is a good sign! It shows that you successfully integrated the SDK.

If there are no heartbeats with “Trip start” Reason, please refer to:

  1. Minimal parameters of a trip for guaranteed tracking
  2. Make sure you’re using the latest SDK version :point-right: Changelog

If both points above are done and you still don’t see “Trip start” events, please, contact our Service Desk by following this link

If SDK detected the trip start, and you still can’t see the trip neither in UserDatahub and/or Trips API, proceed to the next step:

3. SDK is enabled and detects trip, but trips haven’t been uploaded to the server (trips got stuck on a smartphone).

How to investigate and resolve

  1. Follow to UserDataHub => DataTool
  2. Search the user by DeviceToken (Email / Phone / Name / Client ID)
  3. Follow to SDK section and check if user has tracks on device.

This number indicates a number of trips that were recorded but not transferred to the platform yet.

You also can see how this number changed over a period of time. To do so, please refer to “Heartbeats” CSV file.

  1. Follow to UserDataHub -> DataTool
  2. Search the user by DeviceToken (Email, Phone, Name, Client ID)
  3. Scroll down to “Export Data” section
  4. Export “Heartbeats” CSV file

The Column “NotLoadTripsCount” shows how many trips are on the smartphone. The case below shows that the trip was detected and recorded, then the trip finished and data transferred to the platform.

If data was recorded and transferred from the smartphone, you have to check what happened with the trip then.

Be aware, that one trip can consist of several segments and in the “Heartbeats” CSV file you will see “Trip start” and “Trip end” for each segment, and the number of not uploaded trips will be increased accordingly. Later, during processing, these segments will be merged into one single trip. These segments will be marked as “Excluded” and will have a status “Merged”.

4. Trips were recorded, but then recognized as invalid / excluded

There are minimal parameters of a trip to be recognized as a vehicle trip. So, if your trip doesn’t meet these requirements, it will be marked as invalid. You can find the 7days overview of invalid trips in DataTool SDK section:

To get detailed information about invalid/excluded trips, including the reason and the parameters of the trips, you can download these CSV files:

TrackDetails:
{
TrackReceivedAtUtc":"2021-06-22T06:43:04.2091583Z" 
"DistanceMeters":0.0 
"PointsAmount":1 
"StartReason":"MotionDetected" 
"StopReason":"LowSpeedTimeout" 
"MaxSpeedKmh":16.171136477262749 
"AvgAccuracy":9.8686655670171657 

"StartPoint":
{
"PointDate":"2021-06-21T15:39:24+02:00" 
"Latitude":42.439056310059563 
"Longitude":19.249742556644506 
"Accuracy":9.8686655670171657 
"SpeedKmh":16.171136477262749 
"TickTimestamp":1624282766
} 

"FinishPoint":
{
"PointDate":"2021-06-21T15:39:24+02:00" 
"Latitude":42.439056310059563 
"Longitude":19.249742556644506 
"Accuracy":9.8686655670171657 
"SpeedKmh":16.171136477262749 
"TickTimestamp":1624282766
} 
"PointsWithQuantilesAmount":1 
"LastKnownPointsAmount":6}"

If user has invalid/excluded trips and they are wrongly recognized as invalid/excluded: check if user has all required permissions granted during the trips by following this guide

If user has all required permissions granted during the trips: please, contact our Service Desk by following this link

II. Incorrect Start/End of the trip

👍

NOTE:

IF <=300 meters are missing - it is acceptable level of accuracy

In 90% of cases your trip won’t have the missing part, as we reconstruct the first part of each trip. You can see how the reconstruction works by enabling raw point layer in UserDatahub => Trips => Trip Details

The example below has two lines - Green - processed waypoints, Grey - raw waypoints. So, Point A of the grey line is a place where SDK started the trip recording, Point A of the Green line is a point where trip started. The difference is the segment that was reconstructed. To reconstruct the part, we select the most optimal route. It can cause a slightly inaccurate path, but that is acceptable level of accuracy.

2 factors that impact on accuracy:

  1. Landscape
  2. Level of granted permissions

1. Landscape

Landscape impacts tracking accuracy, however almost all cases will be improved during data processing.

  • Tunnels
  • Tall buildings and Downtowns
  • Multi-level roads

Example 1: Hong Kong | Tunnel | Grey line - raw points, Green - Processed path

Example 2: *New York | Manhattan | Grey line - raw points, Green - Processed path

2. Level of granted permissions:

Please refer to permissions requirements. Ask the driver to keep WiFi enabled. No need to connect to the wifi, just keep it on.

Why WiFi improves GPS: https://www.reddit.com/r/Android/comments/xfxcw/how_does_having_wifi_turned_on_improve_location/

If user has all required permissions granted during the trips: please, contact our Service Desk by following this link

III. Wrong type of transport was detected

👍

NOTE:

This AI model is self-educated, the larger the volume of marked trips (with transportation type), the more accurate model is. We highly recommend adding the feature of changing transport type to your app.
:point-right: iOS
:point-right: Android

If the trip was marked with a wrong transportation type, there are 4 options how you can change it:

  1. Ask user to change it in your app (make sure you added this feature to your app)
  2. Change it via API
  3. Change it via UserDataHub (coming soon)
  4. Create a support ticket with all the details about this trip via our Service Desk, and we will re-check everything and change the transport type if needed.

IV. Scoring Issues

Please leave us all the details about this trip via our Service Desk, and we will re-check everything for this trip.

V. Issues with speed limits and detected events

Please leave us all the details about this trip via our Service Desk, and we will re-check everything for this trip.

VI. The trips are shown in UserDataHub, but not in the app

  1. Please, ask user to refresh the triplog
  2. If it doesn’t help, ask user to fully close the app and re-open it again and refresh the triplog
  3. If it doesn’t help, please leave us all the details and we will re-check everything.

Did this page help you?