Skip to content

Latest commit

 

History

History
207 lines (161 loc) · 8.24 KB

INSTALL-ANDROID-AUTO.md

File metadata and controls

207 lines (161 loc) · 8.24 KB
Raw

Android Auto-linking Installation

react-native >= 0.60

With yarn

yarn add react-native-background-geolocation

yarn add react-native-background-fetch@^4.2.1

With npm

npm install react-native-background-geolocation --save

npm install react-native-background-fetch@^4.2.1

Configure react-native-background-fetch

You must perform the Android Setup for react-native-background-fetch.

Gradle Configuration

Add the following ext variables to control the version of Google dependency versions the plugin will align to.

ℹ️ You should always strive to use the latest available Google Play Services libraries. You can determine the latest available version here.

In addition, custom maven url for both background-geolocation and background-fetch are required.

ℹ️ Note: Some recent versions of the React Native Android template may not include the allprojects section. You should add this manually as a separate section along with the nested repositories section in the same android/build.gradle file.

📂 android/build.gradle

buildscript {
    ext {
+       minSdkVersion 		= 19	      // Required minimum
+       targetSdkVersion 	= 33          // Or higher.
+       compileSdkVersion 	= 33          // Or higher.
+       appCompatVersion 	= "1.4.2"      // Or higher.  Required for new AndroidX compatibility.
+       googlePlayServicesLocationVersion = "21.0.1"  // Or higher.
    }
    repositories {
        ...
    }
    ...
}

allprojects {   // <-- NOTE:  allprojects container -- If you don't see this, create it.
    repositories {
        .
        .
        .
+       // Required for react-native-background-geolocation
+       maven { url("${project(':react-native-background-geolocation').projectDir}/libs") }
+       maven { url 'https://developer.huawei.com/repo/' }
+       // Required for react-native-background-fetch
+       maven { url("${project(':react-native-background-fetch').projectDir}/libs") }
    }
}

📂 android/app/build.gradle

Caution

DO NOT OMIT ANY OF THE FOLLOWING INSTRUCTIONS. If you ignore any of the following lines, your license key will fail to validate.

apply plugin: "com.android.application"
apply plugin: "com.facebook.react"

+// background-geolocation
+Project background_geolocation = project(':react-native-background-geolocation')
+apply from: "${background_geolocation.projectDir}/app.gradle"

android {
    .
    .
    .
    buildTypes {
        release {
            .
            .
            .
            minifyEnabled enableProguardInReleaseBuilds
+           shrinkResources false
+           // background_geolocation requires custom Proguard Rules
+           proguardFiles "${background_geolocation.projectDir}/proguard-rules.pro"
        }
    }
}

AndroidManifest.xml (License Configuration)

Note

If you've not purchased a license, ignore this step — the plugin is fully functional in DEBUG builds so you can try before you buy.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.transistorsoft.backgroundgeolocation.react">

  <application
    android:name=".MainApplication"
    android:allowBackup="true"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:theme="@style/AppTheme">

    <!-- react-native-background-geolocation licence -->
+   <meta-data android:name="com.transistorsoft.locationmanager.license" android:value="YOUR_LICENCE_KEY_HERE" />
    .
    .
    .
  </application>
</manifest>

Polygon Geofencing Add-on

Note

If you've purchased a license for the Polygon Geofencing add-on, add the following license key to your AndroidManifest (Polygon Geofencing is fully functional in DEBUG builds so you can try before you buy):

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.your.package.id">

  <application>
    <!-- flutter_background_geolocation licence -->
    <meta-data android:name="com.transistorsoft.locationmanager.license" android:value="YOUR_LICENCE_KEY_HERE" />
    <!-- Background Geolocation Polygon Geofencing Licence -->
+   <meta-data android:name="com.transistorsoft.locationmanager.polygon.license" android:value="YOUR_POLYGON_LICENCE_KEY_HERE" />
    .
    .
    .
  </application>
</manifest>

Huawei Mobile Services (HMS) Support

Note

If you've purchased an HMS Background Geolocation License for installing the plugin on Huawei devices without Google Play Services installed, add your HMS Background Geolocation license key:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.your.package.id">

  <application>
    <!-- react-native-background-geolocation licence -->
    <meta-data android:name="com.transistorsoft.locationmanager.license" android:value="YOUR_LICENCE_KEY_HERE" />
    <!-- HMS Background Geolocation licence -->
+   <meta-data android:name="com.transistorsoft.locationmanager.hms.license" android:value="YOUR_HMS_LICENCE_KEY_HERE" />
    .
    .
    .
  </application>
</manifest>

Warning

Huawei HMS support requires react-native-background-geolocation >= 3.11.0.

AlarmManager "Exact Alarms" (optional)

The plugin uses AlarmManager "exact alarms" for precise scheduling of events (eg: Config.stopTimeout, Config.motionTriggerDelay, Config.schedule). Android 14 (SDK 34), has restricted usage of "AlarmManager exact alarms". To continue using precise timing of events with Android 14, you can manually add this permission to your AndroidManifest. Otherwise, the plugin will gracefully fall-back to "in-exact AlarmManager scheduling". For more information about Android's AlarmManager, see the Android API Docs.

📂 In your AndroidManifest, add the following permission (exactly as-shown):

  <manifest>
      <uses-permission android:minSdkVersion="34" android:name="android.permission.USE_EXACT_ALARM" />
      .
      .
      .
  </manifest>

Warning

It has been announced that Google Play Store has plans to impose greater scrutiny over usage of this permission (which is why the plugin does not automatically add it).

Configure react-native-background-fetch

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 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:

// 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
})