From 81c1b719fe69acd4771a64339e803696cd762c30 Mon Sep 17 00:00:00 2001 From: Chris Scott Date: Fri, 20 Sep 2024 11:45:05 -0400 Subject: [PATCH] docs --- README.md | 18 ++++++++++-------- help/INSTALL-ANDROID.md | 40 ++++++++++++++++++++++++++++------------ help/INSTALL-IOS.md | 18 ++++++++++++++++++ 3 files changed, 56 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 9b1f4355..159d6f9b 100644 --- a/README.md +++ b/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 { ``` -⚠️ 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. diff --git a/help/INSTALL-ANDROID.md b/help/INSTALL-ANDROID.md index 9312abbf..bfd08793 100644 --- a/help/INSTALL-ANDROID.md +++ b/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 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 ``` -: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 . ``` -: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 +}) +``` + + diff --git a/help/INSTALL-IOS.md b/help/INSTALL-IOS.md index dc0c5ab9..e09d07b5 100644 --- a/help/INSTALL-IOS.md +++ b/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 +}) +``` \ No newline at end of file