Configuration

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

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

1
let assetTracking = AssetTracking.shared
2

3
//init notificationConfig
4
let notificationConfig = NotificationConfig()
5
notificationConfig.showAssetEnableNotification = true
6
notificationConfig.showLowBatteryNotification = true
7
assetTracking.setNotificationConfig(config: notificationConfig)
8

9
let dataTrackingConfig = DataTrackingConfig(baseUrl: "api.nextbillion.io", dataStorageSize: 5000, dataUploadingBatchSize: 30, dataUploadingBatchWindow: 20, shouldClearLocalDataWhenCollision: true)
10

11
assetTracking.setDataTrackingConfig(config: dataTrackingConfig)
12

13
assetTracking.initialize(apiKey: "YOUR_ACCESS_KEY")

The classes corresponding to the configuration are:

DataTrackingConfig: Data caching and reporting configuration
LocationConfig: Location update configuration
NotificationConfig: Notification configuration

The following methods are related to the configuration in this SDK:

1
/**
2
    * Set the location configuration.
3
    * Invoke before 'startTracking()'
4
    
5
    - Parameter config: The location configuration to set.
6
    */
7
AssetTracking.shared.setLocationConfig(config: LocationConfig)
8

9
/**
10
    * Update the location configuration.
11
    * Invoke after 'startTracking()'
12
    
13
    - Parameter config: The location configuration to be updated.
14
    */
15
AssetTracking.shared.updateLocationConfig(config: LocationConfig)
16

17
/**
18
    * Get the current LocationConfig of the Tracking SDK
19
    */
20
AssetTracking.shared.getLocationConfig()
21

22
/**
23
    * Set the data tracking configuration.
24
    * Invoke before 'startTracking()'
25
    
26
    - Parameter config: The data tracking configuration to be set.
27
    */
28
AssetTracking.shared.setDataTrackingConfig(config: DataTrackingConfig)
29

30
/**
31
    * Update the data tracking related configuration.
32
    * Invoke after 'startTracking()'
33
    
34
    - Parameter config: The data tracking configuration to be updated.
35
    */
36
AssetTracking.shared.updateDataTrackingConfig(config: DataTrackingConfig)
37

38
/*
39
    * Provide an interface to get the current data tracking config for other module to use
40
    */
41
AssetTracking.shared.getDataTrackingConfig()
42

43

44
/**
45
    * Set the Configuration of the notification
46
    * Invoke before 'startTracking()'
47
    
48
    - Parameter config: The data notification configuration to be set.
49
    */
50
AssetTracking.shared.setNotificationConfig(config: NotificationConfig)
51

52
/**
53
    * Update the Configuration of the notification
54
    * Invoke after 'startTracking()'
55
    
56
    - Parameter config: The data notification configuration to be updated.
57
    */
58
AssetTracking.shared.updateNotificationConfig(config: NotificationConfig)
59

60
/**
61
    * Get the current Notification config of the Tracking SDK
62
    */
63
AssetTracking.shared.getNotificationConfig()

DataTrackingConfig

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

1
open class DataTrackingConfig: NSObject {
2
    
3
    /*
4
     * BaseUrl that will be used in the asset tracking SDK.
5
     */
6
    private var baseUrl: String
7
    
8
    /*
9
     * The maximum data storage size that is allowed in the location data local cache.
10
     */
11
    private var dataStorageSize: Int
12
    
13
    /*
14
     * how many location data will be sent within one api call (maximum).
15
     * this should be configured according to your maximum data collection frequency
16
     * If inappropriate value is set, backend will receive data with huge delay
17
     * recommended value:
18
     *      dataUploadingBatchSize: 30
19
     *      dataUploadingBatchWindow: 20(seconds)
20
     */
21
    private var dataUploadingBatchSize: Int
22
    
23
    /*
24
     * the minimum time interval between two data uploading api call (in seconds)
25
     * this should be configured according to your maximum data collection frequency
26
     * If inappropriate value is set, backend will receive data with huge delay
27
     * recommended value:
28
     *      dataUploadingBatchSize: 30
29
     *      dataUploadingBatchWindow: 20(seconds)
30
     */
31
    private var dataUploadingBatchWindow: Int
32
    
33
    /*
34
     * determine whether to clear local data once assetId is taken by another device
35
     * If do not clear local cache, backend might receive dirty data
36
     * recommend to set as false only when user temporarily switch to another device
37
     * or any other condition that may fit your use case
38
     */
39
    private var shouldClearLocalDataWhenCollision: Bool
40
}

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 local 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, which 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.

LocationConfig

The LocationConfig is used to configure the location tracking settings. It allows customization of various parameters that influence the behavior of location updates.

1
open class LocationConfig: NSObject {
2
    
3
    let trackingMode: TrackingMode
4
    
5
    /*
6
     *  distanceFilter
7
     *
8
     *  Discussion:
9
     *      Specifies the minimum update distance in meters. Client will not be notified of movements of less
10
     *      than the stated value, unless the accuracy has improved. Pass in kCLDistanceFilterNone to be
11
     *      notified of all movements. By default, 5 is used.
12
     */
13
    public var distanceFilter: Double = 5
14
    
15
    /*
16
     *  desiredAccuracy
17
     *
18
     *  Discussion:
19
     *      The desired location accuracy. The location service will try its best to achieve
20
     *      your desired accuracy. However, it is not guaranteed. To optimize
21
     *      power performance, be sure to specify an appropriate accuracy for your usage scenario (eg,
22
     *      use a large accuracy value when only a coarse location is needed). Use kCLLocationAccuracyBest to
23
     *      achieve the best possible accuracy. Use kCLLocationAccuracyBestForNavigation for navigation.
24
     *      The default value varies by platform.
25
     */
26
    public var desiredAccuracy: Double = kCLLocationAccuracyBest
27

28
    /*
29
     *  enableStationaryCheck
30
     *
31
     *  Discussion:
32
     *      Whether to enable stationary check for location data tracking
33
     *      Enable this will slightly increase battery consumption
34
     *      But will provide more accurate speed capture guidance
35
     */
36
    public var enableStationaryCheck: Bool = true
37

38
}

trackingMode: Enumerates the tracking mode, which influences the frequency and accuracy of location updates. Options include TrackingMode.ACTIVE, TrackingMode.BALANCED and TrackingMode.PASSIVE. For details, please refer to Tracking Mode.
distanceFilter: Specifies the minimum distance (in meters) that a device must move before a new location update is generated. Movement less than this distance will not trigger updates unless accuracy improves. The default is 5 meters.
desiredAccuracy: Specifies the desired accuracy for location updates. The location service will attempt to achieve this accuracy, but it's not guaranteed. Options include kCLLocationAccuracyBest for the best accuracy and kCLLocationAccuracyBestForNavigation for navigation. Default values depend on the platform.
enableStationaryCheck: Whether to enable stationary check when doing data tracking, enable this will increase battery consumption and the speed capturing accuracy

Tracking Mode

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

Tracking Mode	Accuracy	Distance interval	Description
ACTIVE	High (the most accurate location)	5m	This mode is suitable for applications that require precise and real-time location updates. It provides high accuracy at the cost of increased battery usage.
BALANCED	Medium (optimized for battery usage)	20m	This mode strikes a balance between accuracy and battery usage. It provides moderately accurate location updates at a lower frequency, resulting in better battery performance compared to the active mode.
PASSIVE	Low (coarse ~ 10 km accuracy location)	100m	This mode is designed for minimal battery consumption. It provides low-accuracy location updates at longer intervals, making it suitable for scenarios where periodic location updates are sufficient and power efficiency is critical.

When selecting a tracking mode, you should consider the specific needs of your application.

TRACKING_MODE_ACTIVE (Default): When you require highly accurate and real-time location updates.
TRACKING_MODE_BALANCED: When a balance between accuracy and battery usage is desired.
TRACKING_MODE_PASSIVE: When power efficiency is a priority and lower accuracy is acceptable.

In the meantime, you are also able to update the related configuration value after the initialization of LocationConfig, and do the data tracking with the updated CUSTOM MODE.

Initializing with Default Settings

Create a LocationConfig instance with default settings. The trackingMode, desiredAccuracy, and distanceFilter properties are initialized with their default values. This is suitable if you want to use the default settings for location tracking.

1
var locationConfig: LocationConfig = LocationConfig()

Initializing with Specific Tracking Mode

Create a LocationConfig instance, and custom the trackingMode property. The desiredAccuracy and distanceFilter properties are then automatically adjusted based on the specified tracking mode. This is useful if you want to prioritize a specific tracking mode and let the other properties adapt accordingly.

1
var locationConfig: LocationConfig = LocationConfig(trackingMode: TrackingMode.BALANCED)

Customizing After Initialization

Create a LocationConfig instance, and custom the trackingMode property, the desireAccuracy and distanceFilter properties are then customized.

1
var locationConfig: LocationConfig = LocationConfig(trackingMode: TrackingMode.BALANCED)
2
locationConfig.desiredAccuracy = kCLLocationAccuracyBest
3
locationConfig.distanceFilter = 100

NotificationConfig

The NotificationConfig is used to manage the notification-related configurations. It allows customization of various parameters that influence the behavior of different types of notifications.

1
open class NotificationConfig: NSObject {
2
    
3
    /**
4
     Configuration for asset enable notification
5
     */
6
    public var assetEnableNotificationConfig = AssetEnableNotificationConfig.init(identifier: "startTrackingIdentifier")
7
    
8
    /**
9
     Configuration for asset disable notification
10
     */
11
    public var assetDisableNotificationConfig = AssetDisableNotificationConfig.init(identifier: "stopTrackingIdentifier")
12
    
13
    /**
14
     Configuration for low battery notification
15
     */
16
    public var lowBatteryNotificationConfig = LowBatteryNotificationConfig.init(identifier: "lowBatteryIdentifier")
17
    
18
    /**
19
     A Boolean value to determine whether to show the asset enable notification.
20
     */
21
    public var showAssetEnableNotification: Bool = true
22
    
23
    /**
24
     A Boolean value to determine whether to show the asset disable notification.
25
     */
26
    public var showAssetDisableNotification: Bool = true
27
    
28
    /**
29
     A Boolean value to determine whether to show the low battery notification.
30
     */
31
    public var showLowBatteryNotification: Bool = false
32
    
33
}

assetEnableNotificationConfig: The configuration for starting asset tracking notifications.
assetDisableNotificationConfig: The configuration for stopping asset tracking notifications.
lowBatteryNotificationConfig: The configuration for low-battery notifications.
showAssetEnableNotification: Determines whether to display notifications for start asset tracking.
showAssetDisableNotification: Determines whether to display notifications for stop asset tracking.
showLowBatteryNotification: Determines whether to display notifications for low battery conditions.

Initializing with Default Settings

Use the default notification settings

1
var notificationConfig = NotificationConfig()

Customizing Notification Configuration

Create a NotificationConfig instance with default settings. Customize the assetEnableNotificationConfig by creating an AssetEnableNotificationConfig instance with specific parameters like identifier, title, and content.

1
var notificationConfig11 = NotificationConfig()
2
notificationConfig.assetEnableNotificationConfig = AssetEnableNotificationConfig(identifier: "id", title: "custom notification title", content: "custom notification content")