Get Started

This section helps developers quickly get started with the Tracking SDK. It covers the prerequisites, requirements, and installation steps needed to add background location tracking to an Android application.

---

Prerequisites and requirements

The Tracking SDK's Android 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.
• IDE (Android Studio): to build and develop the Android application. Use the latest stable Android Studio version recommended by Google.
• Android SDK levels
  • minSdkVersion 24
  • targetSdkVersion 36
  • compileSdkVersion 36
• Use the Google Play services location version compatible with your project and this SDK release. Refer to the latest release notes for the recommended version.

---

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 (Maven)

1. Add the dependency

In /app/build.gradle under dependencies add:

dependencies {
    implementation "com.sovereignsolutions:tracking-sdk:0.0.57"
}

2. Add the artifact repository

If the SDK is hosted on your organisation's private artifact registry, add the Maven repository in android/settings.gradle:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        maven {
            url = uri("https://artifact.sovereignsolutions.tech/artifactory/YOUR_ANDROID_REPO")
            credentials {
                username = "YOUR_ARTIFACT_USERNAME"
                password = "YOUR_ARTIFACT_TOKEN"
            }
        }
    }
}

3. Register the tracking service

If the service is not automatically merged from the SDK's own manifest, add this under the <application> tag in AndroidManifest.xml:

<service
    android:name="com.ss.tslocationmanager.HeadlessTask"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:exported="true" />

4. Add permissions

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

Also make sure a notification icon exists at android/app/src/main/res/drawable/app_logo.png - the foreground service notification uses it.

5. Sync, build and run

Sync the project, then build and run your app.

---

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 Android Map SDK.