iOS Installation

Cocoapods

If you're not using Swift Package Manager, you must adjust the use_frameworks! declaration to add the following property in your ios/Podfile:

use_frameworks! should already exist — just append :linkage => :static:

target 'Runner' do
  use_frameworks! :linkage => :static   # <-- append :linkage => :static
  .
  .
  .
end

:warning: If you don't add the above line, you're going to get the following error when running flutter build ios

-> Installing flutter_background_geolocation (5.0.0)
      - Running pre install hooks
    [!] The 'Pods-Runner' target has transitive dependencies that include statically linked binaries:
    (/ios/Pods/TSBackgroundGeolocation/TSBackgroundGeolocation.xcframework)

Permissions & Background Modes

Open the Xcode project ios/Runner/Runner.xcworkspace

• Enable the background modes:
  • Location updates
  • Background fetch
  • Audio ( ℹ️ optional for debug-mode sound FX )

• Add the following permissions to Info.plist:

Key	Type	Value
Privacy - Location Always and When in Use Usage Description	String	CHANGEME: Location required in background
Privacy - Location When in Use Usage Description	String	CHANGEME: Location required when app is in use
Privacy - Motion Usage Description	String	CHANGEME: Motion permission helps detect when device in in-motion

Or edit Info.plist directly

:open_file_folder: ios/Runner/Info.plist

<plist>
<dict>
+    <key>NSMotionUsageDescription</key>
+    <string>Motion usage description</string>
+    <key>NSLocationWhenInUseUsageDescription</key>
+    <string>When in use description</string>
+    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+    <string>Always/When in use description</string>

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

+    <key>BGTaskSchedulerPermittedIdentifiers</key>
+    <array>
+        <string>com.transistorsoft.fetch</string>
+    </array>
</dict>
</plist>

Configure Your License

In your Info.plist, add the following key:

Key	Type	Value
TSLocationManagerLicense	String	<PASTE YOUR LICENSE KEY HERE>

TSLocationManagerLicense. Paste the contents of your license key into the value.

Background Fetch

The Background Geolocation SDK has internal handling for periodic Background Fetch events (if enabled). It can use these periodic events to gather current state information (is the device moving?), evaluating the schedule (if you configured one) or checking if there are any location records in the queue, waiting to be uploaded to your configured url:

1. Open your Info.plist and add the key "Permitted background task scheduler identifiers"

Key	Type	Value
Permitted background task scheduler identifiers	Array
Item 0	String	com.transistorsoft.fetch

2. Add the required identifier com.transistorsoft.fetch.

Transistor Software manages a helpful free plugin you can optionally add to your app named background_fetch.

// Execute a task about every 15 minutes:
BackgroundFetch.configure(BackgroundFetchConfig(
  minimumFetchInterval: 15
), (String taskId) async { // <-- This is your periodic-task callback
  var location = await BackgroundGeolocation.getCurrentPosition(
    samples: 3,
    extras: {   // <-- your own arbitrary meta-data
      "event": "getCurrentPosition"
    }
  );
  print('[getCurrentPosition] $location');
  BackgroundFetch.finish(taskId);   // <-- signal that your task is complete
})