Skip to content

Commit 5f03e86

Browse files
gopelkujogopelkujo
authored
Clarify permissions requirements earlier in the documentation (#226)
* 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
1 parent e0b2fe9 commit 5f03e86

File tree

1 file changed

+49
-36
lines changed

1 file changed

+49
-36
lines changed

‎README.md‎

Lines changed: 49 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ A Flutter plugin to get location updates in the background for both Android and
44

55
## Getting Started
66

7-
**1:** Add this to your package's pubspec.yaml file:
7+
**1:** Add this to your `pubspec.yaml` file:
88

99
```yaml
1010
dependencies:
@@ -14,11 +14,47 @@ dependencies:
1414
**2:** Install packages from the command line:
1515
1616
```bash
17-
$ flutter packages get
17+
flutter pub get
1818
```
1919

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

22+
## Configuration
23+
24+
For using background_location package you need to add permissions to use location service. **Add** these permission to your platform.
25+
26+
### iOS Platform Permission
27+
28+
in `ios/Runner/Info.plist` add:
29+
30+
```xml
31+
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
32+
<string>[Describe your purpose for using this permission]</string>
33+
<key>NSLocationAlwaysUsageDescription</key>
34+
<string>[Describe your purpose for using this permission]</string>
35+
<key>NSLocationWhenInUseUsageDescription</key>
36+
<string>[Describe your purpose for using this permission]</string>
37+
<key>UIBackgroundModes</key>
38+
<array>
39+
<string>fetch</string>
40+
<string>location</string>
41+
</array>
42+
```
43+
44+
> *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).
45+
46+
### Android Platform Permission
47+
48+
In `android/app/src/main/AndroidManifest.xml` add:
49+
50+
```xml
51+
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
52+
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
53+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
54+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
55+
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
56+
```
57+
2258
## How to use
2359

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

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

32-
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
68+
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
3369

3470
```dart
3571
BackgroundLocation.setAndroidNotification(
36-
title: "Notification title",
37-
message: "Notification message",
38-
icon: "@mipmap/ic_launcher",
72+
title: "Notification title",
73+
message: "Notification message",
74+
icon: "@mipmap/ic_launcher",
3975
);
4076
```
4177

42-
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
78+
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
4379

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

5086
```dart
51-
BackgroundLocation.stopLocationService(); //To ensure that previously started services have been stopped, if desired
87+
// To ensure that previously started services have been stopped, if desired
88+
BackgroundLocation.stopLocationService();
89+
90+
// Then start the service
5291
BackgroundLocation.startLocationService();
5392
```
5493

5594
> *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.
5695
57-
5896
Start location service by specifying `distanceFilter`. Defaults to `0` if not specified
5997

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

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

72110
```dart
73111
BackgroundLocation.getLocationUpdates((location) {
@@ -94,31 +132,6 @@ To stop listening to location changes you can execute.
94132
BackgroundLocation.stopLocationService();
95133
```
96134

97-
Make sure to delcare all required permissions for both your android and ios app
98-
99-
info.plist
100-
```xml
101-
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
102-
<string>This app needs access to location.</string>
103-
<key>NSLocationAlwaysUsageDescription</key>
104-
<string>This app needs access to location.</string>
105-
<key>NSLocationWhenInUseUsageDescription</key>
106-
<string>This app needs access to location.</string>
107-
<key>UIBackgroundModes</key>
108-
<array>
109-
<string>fetch</string>
110-
<string>location</string>
111-
</array>
112-
```
113-
114-
AndroidManifest.xml
115-
```xml
116-
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
117-
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
118-
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
119-
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
120-
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
121-
```
122135
<!-- TODO: Fix example -->
123136
<!-- ## Example -->
124137
<!-- **[Complete working application Example](https://github.com/almoullim/background_location/tree/master/example)** -->

0 commit comments

Comments
 (0)