Merge branch 'docs'

README.md

@@ -14,11 +14,9 @@ The plugin's [Philosophy of Operation](https://github.com/transistorsoft/flutter
 
 Also available for [Cordova](https://github.com/transistorsoft/cordova-background-geolocation-lt), [React Native](https://github.com/transistorsoft/react-native-background-geolocation), [NativeScript](https://github.com/transistorsoft/nativescript-background-geolocation-lt) and [pure native](https://github.com/transistorsoft/background-geolocation-lt) apps.
 
-----------------------------------------------------------------------------
-
-The **[Android module](https://www.transistorsoft.com/shop/products/flutter-background-geolocation)** requires [purchasing a license](https://www.transistorsoft.com/shop/products/flutter-background-geolocation).  However, it *will* work for **DEBUG** builds.  It will **not** work with **RELEASE** builds [without purchasing a license](https://www.transistorsoft.com/shop/products/flutter-background-geolocation).
 
-(2018) This plugin is supported **full-time** and field-tested **daily** since 2013.
+> [!NOTE]  
+>The **[Android module](https://www.transistorsoft.com/shop/products/flutter-background-geolocation)** requires [purchasing a license](https://www.transistorsoft.com/shop/products/flutter-background-geolocation).  However, it *will* work for **DEBUG** builds.  It will **not** work with **RELEASE** builds [without purchasing a license](https://www.transistorsoft.com/shop/products/flutter-background-geolocation).  This plugin is supported **full-time** and field-tested **daily** since 2013.
 
 ----------------------------------------------------------------------------
 
@@ -70,7 +68,8 @@ dependencies:
 import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;
 ```
 
-⚠️ Note `as bg` in the `import`.  This is important to namespace the plugin's classes, which often use common class-names such as `Location`, `Config`, `State`.  You will access every `flutter_background_geolocation` class with the prefix `bg` (ie: "**b**ackground **g**eolocation").
+> [!WARNING]
+> Note `as bg` in the `import`.  This is important to namespace the plugin's classes, which often use common class-names such as `Location`, `Config`, `State`.  You will access every `flutter_background_geolocation` class with the prefix `bg` (ie: "**b**ackground **g**eolocation").
 
 ## 🔷 Example
 [Full Example](https://gist.github.com/christocracy/a0464846de8a9c27c7e9de5616082878)
@@ -81,6 +80,12 @@ There are three main steps to using `BackgroundGeolocation`:
 2. Configure the plugin with `#ready`.
 3. `#start` the plugin.
 
+> [!WARNING]
+> Do not execute *any* API method which will require accessing location-services until the **[`.ready(config)`](https://pub.dev/documentation/flutter_background_geolocation/latest/flt_background_geolocation/BackgroundGeolocation/ready.html)** method resolves ([Read its API docs](https://pub.dev/documentation/flutter_background_geolocation/latest/flt_background_geolocation/BackgroundGeolocation/ready.html)), For example: 
+>- `.getCurrentPosition` 
+>- `.start`
+
+
 ```dart
 
 import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;
@@ -133,9 +138,6 @@ class _MyHomePageState extends State<MyHomePage> {
 
 ```
 
-⚠️ Do not execute *any* API method which will require accessing location-services until the callback to **`#ready*` executes (eg: `#getCurrentPosition`, `#watchPosition`, `#start`).
-
-
 ## 🔷 Demo Application
 
 A fully-featured Demo App is available in the repo in the [`/example`](./example) folder.

help/INSTALL-ANDROID.md

@@ -20,14 +20,8 @@ Flutter seems to have a problem with 3rd-party Android libraries which merge the
 
 ```
 
-##### :warning: Failure to perform the step above will result in a **build error**
-
-```
-Execution failed for task ':app:processDebugManifest'.
-> Manifest merger failed : Attribute application@label value=(hello_world) from AndroidManifest.xml:17:9-36
-    is also present at [tslocationmanager-2.13.3.aar] AndroidManifest.xml:24:18-50 value=(@string/app_name).
-    Suggestion: add 'tools:replace="android:label"' to <application> element at AndroidManifest.xml:15:5-38:19 to override.
-```
+> [!WARNING]
+> Failure to perform the step above will result in a **build error**: __`Manifest merger failed`__
 
 
 ## :open_file_folder: `android/build.gradle`
@@ -78,8 +72,7 @@ buildscript {
 ## :open_file_folder: `android/app/build.gradle`
 
 > [!CAUTION]  
->- __DO NOT OMIT ANY OF THE FOLLOWING CHANGES__ in __green__.
->- If you ignore any of the following lines, your license key will __fail to validate__.
+> __DO NOT OMIT ANY OF THE FOLLOWING CHANGES__ in __green__ or your license key will __fail to validate__.
 
 ```diff
 // flutter_background_geolocation
@@ -153,7 +146,9 @@ If you've [purchased an *HMS Background Geolocation* License](https://shop.trans
   </application>
 </manifest>
 ```
-:warning: Huawei HMS support requires `flutter_background_geolocation >= 3.10.0`.
+
+> [!WARNING]
+> Huawei HMS support requires __`flutter_background_geolocation >= 3.10.0`__.
 
 
 ### Polygon Geofencing Add-on
@@ -190,7 +185,8 @@ The plugin uses __`AlarmManager`__ "exact alarms" for precise scheduling of even
       .
   </manifest>
 ```
-:warning: It has been announced that *Google Play Store* [has plans to impose greater scrutiny](https://support.google.com/googleplay/android-developer/answer/13161072?sjid=3640341614632608469-NA) over usage of this permission (which is why the plugin does not automatically add it).
+> [!WARNING]
+> It has been announced that *Google Play Store* [has plans to impose greater scrutiny](https://support.google.com/googleplay/android-developer/answer/13161072?sjid=3640341614632608469-NA) over usage of this permission (which is why the plugin does not automatically add it).
 
 ## Android Headless Mode with `enableHeadless: true`
 
@@ -206,3 +202,23 @@ BackgroundGeolocation.ready(Config(
 
 `flutter_background_geolocation` installs a dependency `background_fetch` (also created by [Transistor Software](https://www.transistorsoft.com)).  You can optionally perform the [Android Setup](https://github.com/transistorsoft/flutter_background_fetch/blob/master/help/INSTALL-ANDROID.md) for it as well.
 
+> [!TIP]
+> `background_fetch` is helpful for executing a periodic task (eg: every 15 minutes).  You could use `background_fetch` to periodically request the current location:
+
+```dart
+// 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
+})
+```
+
+

help/INSTALL-IOS.md

@@ -126,3 +126,21 @@ It's best to edit this file's XML manually.
 
 The BackgroundGeolocation SDK makes use internally on __`background_fetch`__ (also created by [Transistor Software](https://www.transistorsoft.com)).  Regardless of whether you instend to implement the BackgroundFetch Dart API in your app, you **must** perform the [Background Fetch iOS Setup](https://github.com/transistorsoft/flutter_background_fetch/blob/master/help/INSTALL-IOS.md) at the __`background_fetch`__ repo.
 
+> [!TIP]
+> `background_fetch` is helpful for executing a periodic task (eg: every 15 minutes).  You could use `background_fetch` to periodically request the current location:
+
+```dart
+// 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
+})
+```