Configuration

Asset tracking SDK provides a variety of configuration methods, users can customize data reporting, location data collection, notification, and Android services during Asset tracking SDK initialization.

An example of the configuration module usage during SDK initialization is presented as follows:

1
AssetTracking {
2
   setDefaultConfig(
3
       DefaultConfig( )
4
   )
5
   setLocationConfig(
6
       LocationConfig(
7
           trackingMode = TrackingMode.ACTIVE
8

9
       )
10
   )
11
   setNotificationConfig(
12
       NotificationConfig(
13
           title = "NextBillion.ai",
14
           content = "Asset tracking is now enabled and your device's location will be tracked",
15
       )
16
   )
17
   setDataTrackingConfig(
18
       DataTrackingConfig(
19
           baseUrl = baseUrl,
20
           dataUploadingBatchSize = 30,
21
           dataUploadingBatchWindow = 20,
22
           dataStorageSize = 5000,
23
           shouldClearLocalDataWhenCollision = true
24
       )
25
   )
26
   initialize("YOUR_ACCESS_KEY")
27
}

The classes corresponding to the configuration are:

• DataTrackingConfig : Data caching and reporting configuration

• DefaultConfig: Foreground service configuration

• LocationConfig: Location update configuration

• NotificationConfig: Notification configuration

The following methods are related to configuration in this SDK:

1
/**
2
* Set the support configuration for the AssetTracking SDK
3
* Invoke before 'startTracking()'
4
*/
5
assetTrackingSetDefaultConfig(config: DefaultConfig)
6

7
/**
8
* Get the support configuration for the AssetTracking SDK
9
*/
10
assetTrackingGetDefaultConfig()
11

12
/**
13
* Set the notification configuration for the AssetTracking SDK
14
* Invoke before 'startTracking()'
15
*/
16
assetTrackingSetNotificationConfig(config: NotificationConfig)
17

18
/**
19
* Update the notification configuration for the AssetTracking SDK
20
* Invoke after 'startTracking()'
21
*/
22
assetTrackingUpdateNotificationConfig(config: NotificationConfig)
23

24
/**
25
* Get the notification configuration for the AssetTracking SDK
26
*/
27
assetTrackingGetNotificationConfig()
28

29
/**
30
* Set the Location configuration for the AssetTracking SDK
31
* Invoke before 'startTracking()'
32
*/
33
assetTrackingSetLocationConfig(config: LocationConfig)
34

35
/**
36
* Update the Location configuration for the AssetTracking SDK
37
* Invoke after 'startTracking()'
38
*/
39
assetTrackingUpdateLocationConfig(config: LocationConfig)
40

41
/**
42
* Get the Location configuration for the AssetTracking SDK
43
*/
44
assetTrackingGetLocationConfig()
45

46
/**
47
* Set the DataTracking configuration for the AssetTracking SDK
48
* Invoke before 'startTracking()'
49
*/
50
assetTrackingSetDataTrackingConfig(config: DataTrackingConfig)
51

52
/**
53
* Update the DataTracking configuration for the AssetTracking SDK
54
* Invoke after 'startTracking()'
55
*/
56
assetTrackingUpdateDataTrackingConfig(config: DataTrackingConfig)
57

58
/**
59
* Get the DataTracking configuration for the AssetTracking SDK
60
*/
61
assetTrackingGetDataTrackingConfig()

DataTrackingConfig

DataTrackingConfig includes the following parameters that are configurable during SDK initialization:

1
data class DataTrackingConfig{
2
   var baseUrl: String
3
   var dataStorageSize: Int
4
   var dataUploadingBatchSize: Int
5
   var dataUploadingBatchWindow: Int
6
   var shouldClearLocalDataWhenCollision: Boolean
7
}

• baseUrl will be used for API related services.

• dataStorageSize is the maximum available local storage for the Asset Tracking SDK data caching (location record number in Int, default is 5000, each record contains dataUploadingBatchSize location data, and takes one API call to upload)

• dataUploadingBatchSize (default 30) and dataUploadingBatchWindow(in seconds, default 20 seconds) is for tracked location uploading. The SDK will upload data for every batch window, with no more than the batch size location data. So it is important to configure a proper value for this, otherwise, data will be uploaded with a huge delay.

• shouldClearLocalDataWhenCollision is the flag to control whether to clear locally cached location data if assetId is taken by another device

  • If enabled, all the unsent location data will be cleared once asset id is taken, may cause data loss

  • If disabled, unsent location data will remain cached and continue to upload once user rebinds, but this may cause dirty data issues.

DefaultConfig

DefaultConfig is used to configure the running status of the foreground service, Here is a summary of the properties:

• debug: A flag indicating the debug mode, determining whether to enable debug mode.

• enhanceService: A flag used to determine whether to enable the enhanced service. If set to true, it raises the priority of the service to ensure that the service stays alive until AssetTracking.stopTracking is called. However, it also increases power consumption.

• workerEnabled: A flag determining whether WorkManager can be used.

• crashRestartEnabled: A flag determining whether the application can be restarted when it crashes.

• workOnMainThread: A flag determining whether the service callback works on the main thread.

• restartIntent: The Intent used when the application is restarted.

LocationConfig

LocationConfig includes the following parameters that are configurable during SDK initialization:

Tracking Mode

Location Tracking Mode determines how frequently and accurately the location updates are obtained during tracking. There are three different tracking modes available:

When selecting a tracking mode, you should consider the specific needs of your application. If you require highly accurate and real-time location updates, choose TRACKING_MODE_ACTIVE (Default). If a balance between accuracy and battery usage is desired, TRACKING_MODE_BALANCED is a good option. And if power efficiency is a priority and lower accuracy is acceptable, TRACKING_MODE_PASSIVE is suitable. Moreover, You can also customize the related configurations for a LocationConfig object, to build a Customized Mode based on your need.

Tracking with specific Tracking Mode

• trackingMode is the mode used in location data tracking, as is explained in the previous section, different tracking modes will have different location accuracy, time interval, and distance interval, thus resulting in different battery consumption.

1
// Active mode
2
val locationConfig = LocationConfig(trackingMode = TrackingMode.ACTIVE)
3

4
// Balanced mode
5
val locationConfig = LocationConfig(trackingMode = TrackingMode.BALANCED)
6

7
// Passive mode
8
val locationConfig = LocationConfig(trackingMode = TrackingMode.PASSIVE)
9

10
AssetTracking.instance.setLocationConfig(locationConfig)

Tracking with Distance Interval

You can customize the update interval of every mode

• smallestDisplacement: Distance between location updates in meters, this displacement represents the minimum distance that needs to be covered before receiving a location update.

  1
  // Define the location tracking config with desired distance interval
  2
  val locationConfig = LocationConfig(smallestDisplacement = 100f)
  3
  
  4
  //Config the location config
  5
  AssetTracking.instance.setLocationConfig(locationConfig)

Tracking with Time Interval

1
**interval**: the desired time interval between location updates in milliseconds.
2
// Define the location tracking config with desired time interval
3
val locationConfig = LocationConfig(interval = 3000)
4

5
// Set the location config
6
AssetTracking.instance.setLocationConfig(locationConfig)

Other properties in LocationConfig

• desiredAccuracy is the desired accuracy when requiring location updates.

• maxWaitTime is the maximum wait time in milliseconds for location updates in milliseconds

• fastestInterval indicates for the fastest interval in milliseconds for location updates in milliseconds

• enableStationaryCheck indicates whether to enable stationary check for SDK if enabled, when SDK detects the asset is in stationary, will switch to energy saving tracking mode, and revert to the original mode when an asset moves again.

NotificationConfig

After launching asset tracking, we display a notification in the notification bar indicating that asset tracking is running. Users can customize the notification style using the NotificationConfig. They can set the title, text, icon, and other properties. When asset tracking is stopped, we also send a system notification to inform the user that asset tracking has stopped. The content of this notification can be customized using contentAssetDisable.

Here is a summary of the properties:

• serviceId: The ID of the notification service.

• channelId: The ID name of the notification channel.

• channelName: The name of the notification channel.

• title: The title of the notification view.

• content: The content of the notification view.

• smallIcon: The resource ID of the small icon image for the notification view.

• largeIcon: The resource ID of the large notification icon.

• largeIconBitmap: The bitmap for the big icon image of the notification view.

• remoteViews: Custom layout for the remote view.

• bigRemoteViews: Custom large layout for the remote view.

• pendingIntent: The PendingIntent instance for handling notification click.

• notification: The Notification instance set by the user.

• notificationChannel: The NotificationChannel set by the user.

• showLowBatteryNotification: A flag to determine whether to display the low battery notification. By default, the value is true

• lowBatteryNotification: Customization options for the low battery notification.

• contentAssetDisable: The content of the notification view when asset tracking is disabled.

• assetIdTakenContent: The content of the notification view when the asset id is taken by another device.

By default, when the battery level goes below a certain threshold, a notification is triggered to alert the user. Users can customize the title, text, icon, and other properties of the low-battery notification using LowBatteryNotificationConfig. If the user doesn't want to receive low battery notifications, they can disable it by setting the showLowBatteryNotification property in NotificationConfig. Here is a summary of the properties in LowBatteryNotificationConfig.

• threshold: The low battery warning threshold. If the battery level falls below this value and NotificationConfig.showLowBatteryNotification is true, a notification will be posted. By default the value is 20.

• channelId: The ID name of the notification channel for low battery notification.

• channelName: The name of the notification channel for low battery notification.

• title: The title of the low battery notification view.

• content: The content of the low battery notification view. It includes a placeholder ${threshold} that gets replaced with the actual threshold value.

• smallIcon: The resource ID of the small icon image for the low battery notification view.

• pendingIntent: The PendingIntent instance for handling notification click.