Merge branch 'docs'

transistorsoft · Sep 20, 2024 · 60a9ff6 · 60a9ff6
2 parents a04c65f + 796861a
commit 60a9ff6
Show file tree

Hide file tree

Showing 4 changed files with 94 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -18,11 +18,8 @@ The plugin's [Philosophy of Operation](../../wiki/Philosophy-of-Operation) is to
 
 Also available for [Flutter](https://github.com/transistorsoft/flutter_background_geolocation), [Cordova](https://github.com/transistorsoft/cordova-background-geolocation-lt), [NativeScript](https://github.com/transistorsoft/nativescript-background-geolocation-lt) and pure native apps.
 
-----------------------------------------------------------------------------
-
-The **[Android module](http://www.transistorsoft.com/shop/products/react-native-background-geolocation)** requires [purchasing a license](http://www.transistorsoft.com/shop/products/react-native-background-geolocation).  However, it *will* work for **DEBUG** builds.  It will **not** work with **RELEASE** builds [without purchasing a license](http://www.transistorsoft.com/shop/products/react-native-background-geolocation).
-
-(2018) This plugin is supported **full-time** and field-tested **daily** since 2013.
+> [!NOTE]
+> The **[Android module](http://www.transistorsoft.com/shop/products/react-native-background-geolocation)** requires [purchasing a license](http://www.transistorsoft.com/shop/products/react-native-background-geolocation).  However, it *will* work for **DEBUG** builds.  It will **not** work with **RELEASE** builds [without purchasing a license](http://www.transistorsoft.com/shop/products/react-native-background-geolocation).  This plugin is supported **full-time** and field-tested **daily** since 2013.
 
 ----------------------------------------------------------------------------
 
@@ -141,10 +138,11 @@ There are three main steps to using `BackgroundGeolocation`
 2. `.ready(config)` the plugin.
 3. `.start()` the plugin.
 
-:warning: Do not execute *any* API method which will require accessing location-services until the **[`.ready(config)`](https://transistorsoft.github.io/react-native-background-geolocation/classes/backgroundgeolocation.html#ready)** method resolves ([Read its API docs](https://transistorsoft.github.io/react-native-background-geolocation/classes/backgroundgeolocation.html#ready)), For example: 
-- `.getCurrentPosition` 
-- `.watchPosition`
-- `.start`
+> [!WARNING]
+> Do not execute *any* API method which will require accessing location-services until the **[`.ready(config)`](https://transistorsoft.github.io/react-native-background-geolocation/classes/backgroundgeolocation.html#ready)** method resolves ([Read its API docs](https://transistorsoft.github.io/react-native-background-geolocation/classes/backgroundgeolocation.html#ready)), For example: 
+>- `.getCurrentPosition` 
+>- `.watchPosition`
+>- `.start`
 
 ```javascript
 // NO!  .ready() has not resolved.

diff --git a/help/INSTALL-ANDROID-AUTO.md b/help/INSTALL-ANDROID-AUTO.md
@@ -63,8 +63,8 @@ allprojects {   // <-- NOTE:  allprojects container -- If you don't see this, cr
 
 ### :open_file_folder: **`android/app/build.gradle`**
 
-- :exclamation: __DO NOT OMIT ANY OF THE FOLLOWING INSTRUCTIONS__ :exclamation:
-- If you ignore any of the following lines, your license key will __fail to validate__.
+>[!CAUTION]
+> __DO NOT OMIT ANY OF THE FOLLOWING INSTRUCTIONS__.  If you ignore any of the following lines, your license key will __fail to validate__.
 
 ```diff
 apply plugin: "com.android.application"
@@ -96,7 +96,8 @@ android {
 
 ## AndroidManifest.xml (License Configuration)
 
-If you've **not** [purchased a license](https://www.transistorsoft.com/shop/products/react-native-background-geolocation#plans), **ignore this step** &mdash; the plugin is fully functional in *DEBUG* builds so you can try before you [buy](https://www.transistorsoft.com/shop/products/react-native-background-geolocation#plans).
+> [!NOTE]
+> If you've **not** [purchased a license](https://www.transistorsoft.com/shop/products/react-native-background-geolocation#plans), **ignore this step** &mdash; the plugin is fully functional in *DEBUG* builds so you can try before you [buy](https://www.transistorsoft.com/shop/products/react-native-background-geolocation#plans).
 
 ```diff
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
@@ -120,7 +121,8 @@ If you've **not** [purchased a license](https://www.transistorsoft.com/shop/prod
 
 ### Polygon Geofencing Add-on
 
-If you've purchased a license for the [Polygon Geofencing add-on](https://shop.transistorsoft.com/products/polygon-geofencing), add the following license key to your __`AndroidManifest`__ (Polygon Geofencing is fully functional in DEBUG builds so you can try before you buy):
+> [!NOTE]
+> If you've purchased a license for the [Polygon Geofencing add-on](https://shop.transistorsoft.com/products/polygon-geofencing), add the following license key to your __`AndroidManifest`__ (Polygon Geofencing is fully functional in DEBUG builds so you can try before you buy):
 
 ```diff
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
@@ -140,7 +142,8 @@ If you've purchased a license for the [Polygon Geofencing add-on](https://shop.t
 
 ### Huawei Mobile Services (HMS) Support
 
-If you've [purchased an *HMS Background Geolocation* License](https://shop.transistorsoft.com/collections/frontpage/products/huawei-background-geolocation) for installing the plugin on _Huawei_ devices without *Google Play Services* installed, add your *HMS Background Geolocation* license key:
+> [!NOTE]
+> If you've [purchased an *HMS Background Geolocation* License](https://shop.transistorsoft.com/collections/frontpage/products/huawei-background-geolocation) for installing the plugin on _Huawei_ devices without *Google Play Services* installed, add your *HMS Background Geolocation* license key:
 
 ```diff
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
@@ -157,7 +160,8 @@ If you've [purchased an *HMS Background Geolocation* License](https://shop.trans
   </application>
 </manifest>
 ```
-:warning: Huawei HMS support requires `react-native-background-geolocation >= 3.11.0`.
+> [!WARNING]
+> Huawei HMS support requires `react-native-background-geolocation >= 3.11.0`.
 
 ## `AlarmManager` "Exact Alarms" (optional)
 
@@ -173,8 +177,30 @@ 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).
 
+## [Configure `react-native-background-fetch`](https://github.com/transistorsoft/react-native-background-fetch/blob/master/docs/INSTALL-AUTO-IOS.md#configure-background-capabilities)
 
+The BackgroundGeolocation SDK makes use internally on __`react-native-background-fetch`__.  Regardless of whether you instend to implement the BackgroundFetch Javascript API in your app, you **must** perform the [Background Fetch iOS Setup](https://github.com/transistorsoft/react-native-background-fetch/blob/master/docs/INSTALL-AUTO-IOS.md#configure-background-capabilities) at __`react-native-background-fetch`__.
+
+> [!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({
+  minimumFetchInterval: 15
+}, async (taskId) => { // <-- This is your periodic-task callback  
+  const location = await BackgroundGeolocation.getCurrentPosition({
+    samples: 3,
+    extras: {   // <-- your own arbitrary meta-data
+      "event": "getCurrentPosition"
+    }
+  });
+  console.log('[getCurrentPosition]', location);
+  BackgroundFetch.finish(taskId);   // <-- signal that your task is complete
+})
+```
 
 
diff --git a/help/INSTALL-EXPO.md b/help/INSTALL-EXPO.md
@@ -52,7 +52,8 @@ If you've purchased the [*Polygon Geofencing* add-on](https://shop.transistorsof
 }
 ```
 
-:warning: Polygon Geofencing support for *Expo* requires `react-native-background-geolocation >= 4.16.4`.
+> [!WARNING]
+> Polygon Geofencing support for *Expo* requires `react-native-background-geolocation >= 4.16.4`.
 
 ### Huawei Mobile Services (HMS) Support
 
@@ -74,7 +75,8 @@ If you've [purchased an *HMS Background Geolocation* License](https://shop.trans
 }
 ```
 
-:warning: Huawei HMS support requires `react-native-background-geolocation >= 3.11.0`.
+> [!WARNING]
+> Huawei HMS support requires `react-native-background-geolocation >= 3.11.0`.
 
 ### `Info.plist`:  *Usage Descriptions*
 
@@ -169,10 +171,40 @@ You must rebuild your Android app for the added plugins to be evaluated.
 npx expo prebuild
 ```
 
+> [!NOTE]
+> When using `prebuild`, you must run your app as follows:
+
+```console
+$ npx expo run:android
+$ npx expo run:ios
+```
+
 - If you're using *Expo EAS*, you must first run `eas build`.
 - Adjust `--profile` as desired.
 - You must build __ALL__ platforms, both *iOS* and *Android*:
 
 ```bash
  eas build --profile development
 ```
+
+## [`react-native-background-fetch`](https://github.com/transistorsoft/react-native-background-fetch)
+
+> [!TIP]
+> [`react-native-background-fetch`](https://github.com/transistorsoft/react-native-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({
+  minimumFetchInterval: 15
+}, async (taskId) => { // <-- This is your periodic-task callback  
+  const location = await BackgroundGeolocation.getCurrentPosition({
+    samples: 3,
+    extras: {   // <-- your own arbitrary meta-data
+      "event": "getCurrentPosition"
+    }
+  });
+  console.log('[getCurrentPosition]', location);
+  BackgroundFetch.finish(taskId);   // <-- signal that your task is complete
+})
+```
+
diff --git a/help/INSTALL-IOS-AUTO.md b/help/INSTALL-IOS-AUTO.md
@@ -127,3 +127,23 @@ It's best to edit this file's XML manually.
 ## [Configure `react-native-background-fetch`](https://github.com/transistorsoft/react-native-background-fetch/blob/master/docs/INSTALL-AUTO-IOS.md#ios-auto-linking-setup)
 
 The BackgroundGeolocation SDK makes use internally on __`react-native-background-fetch`__.  Regardless of whether you intend to implement the BackgroundFetch Javascript API in your app, you **must** perform the [Background Fetch iOS Setup](https://github.com/transistorsoft/react-native-background-fetch/blob/master/docs/INSTALL-AUTO-IOS.md#configure-background-capabilities) at __`react-native-background-fetch`__.
+
+> [!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({
+  minimumFetchInterval: 15
+}, async (taskId) => { // <-- This is your periodic-task callback  
+  const location = await BackgroundGeolocation.getCurrentPosition({
+    samples: 3,
+    extras: {   // <-- your own arbitrary meta-data
+      "event": "getCurrentPosition"
+    }
+  });
+  console.log('[getCurrentPosition]', location);
+  BackgroundFetch.finish(taskId);   // <-- signal that your task is complete
+})
+```
+