Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify permissions requirements earlier in the documentation #226

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
+49 −36
Open

Clarify permissions requirements earlier in the documentation #226

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f9bb222
Improve documentation
gopelkujo Oct 7, 2024
b940b00
Fix typos
gopelkujo Oct 7, 2024
7cf1eb7
Improve explanation
gopelkujo Oct 7, 2024
83b9bf4
Add note for applying permission to info.plist
gopelkujo Oct 8, 2024
cb2b4e4
Change flutter package get to flutter pub get
gopelkujo Oct 8, 2024
14dd28b
Merge branch 'improve-documentation' of https://github.com/gopelkujo/…
gopelkujo Oct 8, 2024
24dfea3
Add placeholder and caution to add description in ios config
gopelkujo Oct 8, 2024
cd929e6
Fix some typo
gopelkujo Oct 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 49 additions & 36 deletions README.md
View file
Open in desktop
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
MoralCode marked this conversation as resolved.
Show resolved Hide resolved
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)** -->