Skip to content

Commit

Permalink
Clarify permissions requirements earlier in the documentation (#226)
Browse files Browse the repository at this point in the history 
* Improve documentation

* Fix typos

* Improve explanation

* Add note for applying permission to info.plist

* Change flutter package get to flutter pub get

* Add placeholder and caution to add description in ios config

* Fix some typo
  • Loading branch information
@gopelkujo
gopelkujo authored Oct 9, 2024
1 parent e0b2fe9 commit 5f03e86
Showing 1 changed file with 49 additions and 36 deletions.
85 changes: 49 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ A Flutter plugin to get location updates in the background for both Android and

## Getting Started

**1:** Add this to your package's pubspec.yaml file:
**1:** Add this to your `pubspec.yaml` file:

```yaml
dependencies:
Expand All @@ -14,11 +14,47 @@ dependencies:
**2:** Install packages from the command line:
```bash
$ flutter packages get
flutter pub get
```

Alternatively, your editor might support flutter packages get. Check the docs for your editor to learn more.

## Configuration

For using background_location package you need to add permissions to use location service. **Add** these permission to your platform.

### iOS Platform Permission

in `ios/Runner/Info.plist` add:

```xml
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>[Describe your purpose for using this permission]</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>[Describe your purpose for using this permission]</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>[Describe your purpose for using this permission]</string>
<key>UIBackgroundModes</key>
<array>
<string>fetch</string>
<string>location</string>
</array>
```

> *Note*: You need to describe your purpose for using the permission in to `string` value. If not, attempts to access the resource fail, and might even cause your app to crash. And when publishing to the App Store, this can cause your app to be rejected by Apple. Refer to [Provide a purpose string (Apple Docummentation)](https://developer.apple.com/documentation/uikit/protecting_the_user_s_privacy/requesting_access_to_protected_resources#3037322).
### Android Platform Permission

In `android/app/src/main/AndroidManifest.xml` add:

```xml
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
```

## How to use

Import the package where you wanna use it.
Expand All @@ -27,19 +63,19 @@ Import the package where you wanna use it.
import 'package:background_location/background_location.dart';
```

Request permissions from the user. You can use [permission_handler](https://pub.dev/packages/permission_handler) for this
Request permissions from the user. You can use [permission_handler](https://pub.dev/packages/permission_handler) for this.

Set the notification title, message and icon **(Android only)**. Use `await` or `.then` if you wanna start the location service immediatly after becuase its an asynchronous method
Set the notification title, message and icon **(Android only)**. Use `await` or `.then` if you wanna start the location service immediately after because it's an asynchronous method

```dart
BackgroundLocation.setAndroidNotification(
title: "Notification title",
message: "Notification message",
icon: "@mipmap/ic_launcher",
title: "Notification title",
message: "Notification message",
icon: "@mipmap/ic_launcher",
);
```

Set the interval between localisations in milliseconds **(Android only)**. Use `await` or `.then` if you wanna start the location service immediatly after becuase its an asynchronous method
Set the interval between localizations in milliseconds **(Android only)**. Use `await` or `.then` if you wanna start the location service immediately after because it's an asynchronous method

```dart
BackgroundLocation.setAndroidConfiguration(1000);
Expand All @@ -48,13 +84,15 @@ BackgroundLocation.setAndroidConfiguration(1000);
Start the location service. This will also ask the user for permission if not asked previously by another package.

```dart
BackgroundLocation.stopLocationService(); //To ensure that previously started services have been stopped, if desired
// To ensure that previously started services have been stopped, if desired
BackgroundLocation.stopLocationService();
// Then start the service
BackgroundLocation.startLocationService();
```

> *Note:* There is currently an open issue (#10) where, if the location service is started multiple times, the location callback will get called repeatedly. This can be worked around by calling BackgroundLocation.stopLocationService(); to stop any previous running services (such as from a previous run of the app) before starting a new one.

Start location service by specifying `distanceFilter`. Defaults to `0` if not specified

```dart
Expand All @@ -67,7 +105,7 @@ You can also force the use of Android `LocationManager` instead of Google's `Fus
BackgroundLocation.startLocationService(forceAndroidLocationManager: true);
```

`getLocationUpdates` will trigger everytime the location updates on the device. Provide a callback function to `getLocationUpdates` to handle location update.
`getLocationUpdates` will triggered whenever the location is updated on the device. Provide a callback function to `getLocationUpdates` to handle location updates.

```dart
BackgroundLocation.getLocationUpdates((location) {
Expand All @@ -94,31 +132,6 @@ To stop listening to location changes you can execute.
BackgroundLocation.stopLocationService();
```

Make sure to delcare all required permissions for both your android and ios app

info.plist
```xml
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs access to location.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs access to location.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location.</string>
<key>UIBackgroundModes</key>
<array>
<string>fetch</string>
<string>location</string>
</array>
```

AndroidManifest.xml
```xml
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
```
<!-- TODO: Fix example -->
<!-- ## Example -->
<!-- **[Complete working application Example](https://github.com/almoullim/background_location/tree/master/example)** -->

0 comments on commit 5f03e86

Please sign in to comment.