Get Started

This section covers the prerequisites, requirements and installation steps needed to add background location tracking to a native iOS application.

---

Prerequisites and requirements

The Tracking SDK's iOS SDK requires the following prerequisites:

• Access Key: an API key issued during onboarding - see Contact us to request access.
• Tenant, username and password: the Tracking SDK sends tracking logs for a tracked object to a specific tenant and requires authentication to do so - see Contact us to request access.
• Xcode: use the newest available version.
• iOS deployment target
  • Minimum iOS version: 13.0
  • Target iOS version: 26+
• CocoaPods: the SDK is distributed as a pod.

---

Exchange your credentials for a token

curl -X POST 'https://api-gw.sovereignsolutions.com/gateway/authen/oauth/token?api-key=$API_KEY' \
  -d 'grant_type=password' \
  -d 'username=$USERNAME' \
  -d 'password=$PASSWORD'

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<token>"
}

Keep the access_token. Every other endpoint needs it.

Full details: Authentication reference

---

Installation (CocoaPods)

1. Add the pod

In ios/Podfile, inside the Runner target:

platform :ios, '13.0'

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  pod 'Sovereigniostracking',
      :http => 'https://YOUR_USERNAME:[email protected]/artifactory/sstracking-ios-tracking/Sovereigniostracking/0.0.7/Sovereigniostracking-0.0.7.tar.gz'
end

Add a post-install block to keep the deployment target consistent across pods:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
    end
  end
end

2. Install

cd ios
pod install --repo-update
cd ..

Always open Runner.xcworkspace, not Runner.xcodeproj, after this step.

3. Add permissions

In Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app uses your location to enable duty tracking.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app collects location in the background to keep your tracking session active.</string>

<key>NSLocationAlwaysUsageDescription</key>
<string>This app collects location in the background to keep your tracking session active.</string>

<key>NSMotionUsageDescription</key>
<string>This app uses motion activity to improve tracking accuracy.</string>

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>fetch</string>
  <string>processing</string>
</array>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>com.sovereignsolutions.tracking.refresh</string>
  <string>com.sovereignsolutions.tracking.processing</string>
</array>

4. Enable Background Modes in Xcode

In Runner → Signing & Capabilities, add Background Modes and enable:

• Location updates
• Background fetch
• Background processing

---

Next steps

• Usage - initialize the SDK and start tracking
• Authentication - credentials the SDK needs
• Sample apps - reference source code on GitHub

---

Looking for the map rendering SDK instead? See the iOS Map SDK.