Skip to Content
Installation

Installation

Installing Tracelet involves adding the Flutter dependency and making a few native project configurations.

1. Add the Dependency

Add tracelet to your pubspec.yaml using the Flutter CLI:

flutter pub add tracelet

2. iOS Setup

You must define usage descriptions and background modes in your ios/Runner/Info.plist. Without these, Apple will reject your app or kill the background task.

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to track your route.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need background location to record your route even when the app is closed.</string>
<key>NSMotionUsageDescription</key>
<string>Motion detection allows battery-efficient tracking by pausing GPS when stationary.</string>
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>fetch</string>
  <string>processing</string>
</array>

Ensure you have added the location UIBackgroundMode, otherwise your app will be suspended when pushed to the background.

3. Android Setup

To get the fused location provider (best accuracy + battery), hardware activity recognition, and hardware geofencing, add Google Play Services Location to your app. It is not bundled by Tracelet (to stay lightweight and support Google-less devices), so you opt in:

// android/app/build.gradle.kts
dependencies {
    implementation("com.google.android.gms:play-services-location:21.3.0")
}

Without this dependency, Tracelet falls back to the AOSP LocationManager (plain GPS) — tracking still works, but you lose the FusedLocationProviderClient’s accuracy/battery benefits, hardware activity recognition, and hardware geofencing. Add it unless you specifically target Google-less / AOSP devices. See Android platform setup for the full comparison.

Optional dependency: Play Integrity (device attestation)

If you enable Tracelet’s device attestation feature (AttestationConfig), also add Google Play Integrity to your app. Like the GMS location dependency, it is not bundled by Tracelet, so you opt in:

// android/app/build.gradle.kts
dependencies {
    implementation("com.google.android.play:integrity:1.6.0")
}

Only needed if you use attestation. Without it, all other features work normally — Tracelet.getAttestationToken() just returns null instead of a Play Integrity token. See Android platform setup for details.

Permissions

By default, Tracelet automatically injects all required permissions into your compiled Android manifest via Manifest Merger. You do not need to manually add <uses-permission> tags to your AndroidManifest.xml unless you want to override them.

The injected permissions are:

  • android.permission.ACCESS_COARSE_LOCATION
  • android.permission.ACCESS_FINE_LOCATION
  • android.permission.ACCESS_BACKGROUND_LOCATION
  • android.permission.ACTIVITY_RECOGNITION
  • android.permission.FOREGROUND_SERVICE
  • android.permission.FOREGROUND_SERVICE_LOCATION
  • android.permission.POST_NOTIFICATIONS
  • android.permission.WAKE_LOCK
  • android.permission.RECEIVE_BOOT_COMPLETED
  • android.permission.INTERNET
  • android.permission.ACCESS_NETWORK_STATE

Removing Unused Permissions

If you don’t need a specific feature (like motion detection or boot startup), you can forcefully remove those permissions to reduce your app’s requested scopes on the Google Play Store.

To do this, add the tools:node="remove" attribute in your app’s android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.your.app">
    
    <!-- Remove motion detection permission -->
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" tools:node="remove" />
    
    <!-- Remove start on boot permission -->
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" tools:node="remove" />
 
    <application>
      ...
    </application>
</manifest>

If you remove ACTIVITY_RECOGNITION, Tracelet will fall back to using standard location stationary updates, which may consume slightly more battery than using the hardware pedometer.

4. Next Steps

With installation complete, you can now write some Dart code!

iOS SDKBasic Example