> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/core/llms.txt) # Android Core library Current version:`v3.1.0` [View changelog](https://github.com/mapbox/mapbox-events-android/blob/master/CHANGELOG.md) - Real-time device location - Checking and requesting permissions [Contribute on GitHub](https://github.com/mapbox/mapbox-events-android) ![](https://docs.mapbox.com/android/assets/ideal-img/java-overview-header-image.480.png) The **Mapbox Core Libraries** for Android are a set of utilities that help you with permissions, device location, and connectivity within your Android project. With these libraries, you can: - Check for, request, and respond to any number of Android system permissions such as device location or camera. - Check for and respond to a change in the device's internet connectivity status. - Retrieve a device's real-time location. This core module has no dependencies on any of the other Mapbox Java modules and only depends on having the Android API plugin inside your project. ## Installation ### Gradle 1. Open Android Studio. 2. Open up your application's `build.gradle` file. 3. Make sure that your project's `minSdkVersion` is at API 14 or higher. 4. Under dependencies, add a new build rule for the latest `mapbox-android-core` version (see below). 5. Click on `Sync Project with Gradle Files` near the toolbar in Android Studio. ```groovy implementation 'com.mapbox.mapboxsdk:mapbox-android-core:3.1.0' ``` ***Note:** ProGuard directives are included in the Android dependencies to preserve the required classes.* ## `PermissionsManager` If you build your Android project targeting API level 23 or higher, then your application will need to request permission during runtime. Handling this directly in your activity produces boilerplate code and can often be hard to manage. That's where the `PermissionsManager` class comes into play. With the `PermissionsManager` class, you can check whether the user has granted location permission and request permissions if the user hasn't granted them yet. You can use `PermissionsManager permissionsManager = new PermissionsManager(this);` if you're implementing `PermissionsListener`. Once you have set up your permissions manager, you will still need to override `onRequestPermissionsResult()` and call the `permissionsManager`'s same method. ***Note:** The `PermissionsManager` can be used for requesting other permissions besides location.* **Java** ```java PermissionsManager permissionsManager; if (PermissionsManager.areLocationPermissionsGranted(this)) { // Permission sensitive logic called here, such as activating the Maps SDK's LocationComponent to show the device's location } else { permissionsManager = new PermissionsManager(this); permissionsManager.requestLocationPermissions(this); } @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { permissionsManager.onRequestPermissionsResult(requestCode, permissions, grantResults); } ``` **Kotlin** ```kt var permissionsManager: PermissionsManager if (PermissionsManager.areLocationPermissionsGranted(this)) { // Permission sensitive logic called here, such as activating the Maps SDK's LocationComponent to show the device's location } else { permissionsManager = PermissionsManager(this) permissionsManager.requestLocationPermissions(this) } override fun onRequestPermissionsResult(requestCode: Int, permissions: Array, grantResults: IntArray) { permissionsManager.onRequestPermissionsResult(requestCode, permissions, grantResults) } ``` > **Related content (example): [Showing device location](https://docs.mapbox.com/android/legacy/maps/examples/show-a-users-location/)** > > See how the PermissionsManager is used to check permissions before showing the device location puck. ## `PermissionsListener` The `PermissionsListener` is an interface that returns information about the state of permissions. Set up the interface and pass it into the `PermissionsManager`'s constructor. The permission result is invoked once the user decides whether to allow or deny the permission. A boolean value is supplied, which you can then use to write an `if` statement. Both cases should be handled correctly. Continue with your permission-sensitive logic if the user approves. Otherwise, if the user denies, display a message that tells the user that the permission is required for your application to work. An explanation isn't required but strongly encouraged to allow the user to understand why you are requesting this permission. **Java** ```java PermissionsListener permissionsListener = new PermissionsListener() { @Override public void onExplanationNeeded(List permissionsToExplain) { } @Override public void onPermissionResult(boolean granted) { if (granted) { // Permission sensitive logic called here, such as activating the Maps SDK's LocationComponent to show the device's location } else { // User denied the permission } } }; ``` **Kotlin** ```kt var permissionsListener: PermissionsListener = object : PermissionsListener { override fun onExplanationNeeded(permissionsToExplain: List) { } override fun onPermissionResult(granted: Boolean) { if (granted) { // Permission sensitive logic called here, such as activating the Maps SDK's LocationComponent to show the device's location } else { // User denied the permission } } } ``` > **Related content (example): [Showing device location](https://docs.mapbox.com/android/legacy/maps/examples/show-a-users-location/)** > > See how the PermissionsListener is used to respond to changes in permissions. ## `LocationEngine` If your application needs location information, the `LocationEngine` class can help you get this information while also simplifying the process and being flexible enough to use different services. The `LocationEngine` found in the core module now supports the following location providers: - Google's Fused Location Providers - Android GPS and Network Providers If you are using the Mapbox Maps SDK for Android, create a `LocationEngine` object using: **Java** ```java LocationEngine locationEngine = LocationEngineProvider.getBestLocationEngine(this); ``` **Kotlin** ```kt var locationEngine = LocationEngineProvider.getBestLocationEngine(this) ``` This will get the best location engine that is available and stop the need to create a new `LocationEngine` from scratch. ## Requesting location updates You'll need a class that implements `LocationEngineCallback`. Make sure the class requires Android system `Activity` as a constructor parameter. This class will serve as a "callback" and it's needed because a `LocationEngine` memory leak is possible if the activity/fragment directly implements the `LocationEngineCallback`. The `WeakReference` setup avoids the leak. When implementing the `LocationEngineCallback` interface, you are also required to override the `onSuccess()` and `onFailure()` methods. `OnSuccess()` runs whenever the Mapbox Core Libraries identifies a change in the device's location. `result.getLastLocation()` gives you a `Location` object that contains the latitude and longitude values. Now you can display the values in your app's UI, save it in memory, send it to your backend server, or use the device location information how you'd like. **Java** ```java private static class LocationListeningCallback implements LocationEngineCallback { private final WeakReference activityWeakReference; LocationListeningCallback(MainActivity activity) { this.activityWeakReference = new WeakReference<>(activity); } @Override public void onSuccess(LocationEngineResult result) { // The LocationEngineCallback interface's method which fires when the device's location has changed. Location lastLocation = result.getLastLocation(); } @Override public void onFailure(@NonNull Exception exception) { // The LocationEngineCallback interface's method which fires when the device's location can not be captured } } ``` **Kotlin** ```kt private class LocationListeningCallback internal constructor(activity: MainActivity) : LocationEngineCallback { private val activityWeakReference: WeakReference init {this.activityWeakReference = WeakReference(activity)} override fun onSuccess(result: LocationEngineResult) { // The LocationEngineCallback interface's method which fires when the device's location has changed. result.getLastLocation() } /** * The LocationEngineCallback interface's method which fires when the device's location can not be captured * * @param exception the exception message */ override fun onFailure(exception: Exception) { // The LocationEngineCallback interface's method which fires when the device's location can not be captured } } ``` Globally declare an instance of the class you created above: **Java** ```java private LocationListeningCallback callback = new LocationListeningCallback(this); ``` **Kotlin** ```kt private val callback = LocationListeningCallback(this) ``` Request location updates once you know location permissions have been granted: **Java** ```java long DEFAULT_INTERVAL_IN_MILLISECONDS = 1000L; long DEFAULT_MAX_WAIT_TIME = DEFAULT_INTERVAL_IN_MILLISECONDS * 5; LocationEngine locationEngine = LocationEngineProvider.getBestLocationEngine(this); LocationEngineRequest request = new LocationEngineRequest.Builder(DEFAULT_INTERVAL_IN_MILLISECONDS) .setPriority(LocationEngineRequest.PRIORITY_NO_POWER) .setMaxWaitTime(DEFAULT_MAX_WAIT_TIME) .build(); locationEngine.requestLocationUpdates(request, callback, getMainLooper()); locationEngine.getLastLocation(callback); ``` **Kotlin** ```kt val DEFAULT_INTERVAL_IN_MILLISECONDS = 1000L val DEFAULT_MAX_WAIT_TIME = DEFAULT_INTERVAL_IN_MILLISECONDS * 5 locationEngine = LocationEngineProvider.getBestLocationEngine(this) var request = LocationEngineRequest.Builder(DEFAULT_INTERVAL_IN_MILLISECONDS) .setPriority(LocationEngineRequest.PRIORITY_NO_POWER) .setMaxWaitTime(DEFAULT_MAX_WAIT_TIME) .build() locationEngine.requestLocationUpdates(request, callback, mainLooper) locationEngine.getLastLocation(callback) ``` To prevent your application from having a memory leak, it is a good idea to stop requesting location updates inside of your activity's `onStop()` method. **Java** ```java @Override protected void onStop() { super.onStop(); if (locationEngine != null) { locationEngine.removeLocationUpdates(callback); } mapView.onStop(); } ``` **Kotlin** ```kt override fun onStop() { super.onStop() locationEngine?.removeLocationUpdates(callback) mapView.onStop() } ```