Getting started

To begin your journey with NextBillion.ai's Asset Tracking iOS SDK, make sure you have met the necessary prerequisites, as outlined in the "Prerequisites" section. Then, proceed with the step-by-step installation instructions to integrate the SDK into your iOS project.

Prerequisites

Before integrating the SDK into your application, ensure that your development environment meets the following prerequisites:

  1. NextBillion.ai API Key: Obtain a valid access key from our platform. This access key is essential for authentication and enables you to utilize the SDK's services.

  2. Platform Compatibility: Make sure you're using the right tools and versions:

    • IDE: Xcode 13.2.1 or a more recent version.

    • Minimum Deployment Target: iOS 11.0.

  3. Location Data Access Explanation: In your Info.plist, add the required location permission keys.

    1
    <key>NSLocationWhenInUseUsageDescription</key>
    2
    <string>[Your explanation here]</string>
    3
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    4
    <string>[Your explanation here]</string>

By meeting these prerequisites, you can guarantee a smooth and successful integration of our SDK into your application. These requirements have been established to ensure compatibility and optimal performance, enabling you to leverage the full potential of the SDK's features.

Installation

Installation steps are streamlined for faster integration, aligned with mainstream SDK docs (SPM-first, optional alternatives).

Quick Integration (Recommended)

  1. Add SDK dependency (SPM recommended).
  2. Configure Info.plist permissions.
  3. Initialize SDK with apiKey.
  4. Create/Bind assets and start tracking.

Install SDK via Carthage (Optional)

Carthage is kept for existing projects only. If your project already uses Carthage, keep using it. For new projects, use Swift Package Manager.

Carthage reference: https://github.com/Carthage/Carthage#installing-carthage

Carthage Quick Steps

  1. Create Cartfile and add dependencies below:

    Cartfile example:

    1
    binary "https://github.com/nextbillion-ai/nextbillion-asset-tracking-ios/releases/download/v1%2Fcarthage/NBAssetDataCollectLib.json" ~> 1.4.1
    2
    binary "https://github.com/nextbillion-ai/nextbillion-asset-tracking-ios/releases/download/v1%2Fcarthage/NBAssetTracking.json" ~> 1.4.1

  2. Run Carthage update command below:

    1
    carthage update --use-xcframeworks

  3. Link and embed listed frameworks in Xcode target

    1
    NBAssetDataCollectLib
    2
    NBAssetTracking

Install SDK via Swift Package Manager (Recommended)

Recommended for all new integrations.

  1. In Xcode, go to File > Add Package Dependencies....
  2. Enter package URL: https://github.com/nextbillion-ai/asset-tracking-distribution
  3. Add product NBAssetTracking to your app target (Version: 1.4.1 or Up to Next Major from 1.4.1).
  4. Import SDK: import NBAssetTracking.

Install SDK via CocoaPods (Optional)

Use this only if your project already uses CocoaPods.

  1. Podfile example:

    1
    use_frameworks!
    2
    target 'TargetNameForYourApp' do
    3
        pod NextBillionAssetTracking, '1.4.1'
    4
    end

  2. Run pod repo update && pod install, then open the .xcworkspace file.

After dependency installation, continue with Initialization and Asset Binding sections.

Location Data Access Explanation

Add the following to the Info.plist to explain why you need access to the location data:

1
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
2
	<string>Request for location update</string>
3
	<key>NSLocationAlwaysUsageDescription</key>
4
	<string>Request for location update</string>
5
	<key>NSLocationWhenInUseUsageDescription</key>
6
	<string>Request for location update</string>

Initialization

A common way to initialize the SDK is to put the following code in your AppDelegate, otherwise, please make sure you have called the code below before you start using any functionalities of the SDK.

1
let assetTracking = AssetTracking.shared
2


3
// Customize asset tracking configuration
4
// Enable notifications for asset status changes
5
// And Customize data tracking configuration
6


7
let notificationConfig = NotificationConfig()
8
notificationConfig.showAssetEnableNotification = true
9
notificationConfig.showLowBatteryNotification = true
10
assetTracking.setNotificationConfig(config: notificationConfig)
11


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


14
assetTracking.setDataTrackingConfig(config: dataTrackingConfig)
15


16
assetTracking.initialize( Key: "YOUR_ACCESS_KEY")

Replace YOUR_ACCESS_KEY with the access key provided to you by NextBillion.ai. This initialization step is essential to authenticate your app and enable seamless communication with NextBillion.ai's services.

Asset Binding and Tracking

To initiate asset binding and tracking with the NextBillion.ai iOS Tracking SDK, follow these steps:

Creating an Asset

If you don't have an asset yet, you can create one using the following API: AssetTracking.shared.createAsset(baseUrl, assetProfile, completionHandler, errorHandler)

Retrieve the assetId from the API response.

Here's a sample class structure for handling the response:

1
open class AssetCreationResponse {
2
    public let status: String
3
    public let data: AssetCreationResponseData{
4
        public let id: String
5
    }
6
}
7

Binding the Asset to Your Device

Once you have the assetId, use the following API to bind the asset to your current device:

1
AssetTracking.shared.bindAsset(baseUrl, assetId, completionHandler, errorHandler)

After a successful binding, you're ready to start tracking the location of the asset.

Start and Stop Tracking

You have the flexibility to initiate or halt tracking on your device, with location tracking and uploading adhering to your predefined configurations:

To start data tracking:

1
// start data tracking
2
AssetTracking.shared.startTracking()

To stop data tracking:

1
// stop data tracking
2
AssetTracking.shared.stopTracking()

By following these steps, you'll effectively bind assets to your iOS device and commence location tracking as per your configuration settings. This allows you to seamlessly monitor and manage your assets using the NextBillion.ai iOS Tracking SDK.