# Geolocation

* [Bubble.io Plugin](#bubble.io-plugin)
* [JavaScript SDK](#javascript-sdk)

{% hint style="info" %}
If you're planning to use browser [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation), make sure you've enabled the Geolocation feature for iOS (For Android, this feature is enabled by default)
{% endhint %}

{% hint style="info" %}
To avoid system conflicts and battery drain, follow these simple rules:

* Need tracking only when the app is open? Use the `Foreground Geolocation` feature only.
* Need tracking even when the app is closed? Use the `Background Geolocation` feature only. The background service automatically handles foreground tracking; you do not need to run both simultaneously.

Warning: Running both services concurrently will lead to unpredictable behavior and rapid battery depletion. Always stop one before starting the other.
{% endhint %}

## 🧋 Bubble.io Plugin

### \[Element] Natively - Location

**Natively - Location** element contains Foreground & Background location services: 

#### 📍 Foreground Location Tracking

#### Events:

* **Location received** - **User's location longitude & latitude** values updated.
* **Location failed** - called whenever Location service was not able to get user's location (check **Latest location request status** for more details)
* **Location Permission Received -** called whenever **Get location permission** return a result
* **v2.13.4 - Location Background Service Status Received** - called afrer **Get background location service status**

#### States:

* **Latest location longitude** - [Longitude](https://en.wikipedia.org/wiki/Longitude) as number
* **Latest location latitude** - [Latitude](https://en.wikipedia.org/wiki/Latitude) as number
* **Latest location response status** - Status of the latest geolocation request call.
  * SUCCESS - Got a location and desired accuracy level was achieved successfully.
  * TIMEOUT - Got a location, but the desired accuracy level was not reached before timeout.
  * FAILED - An error occurred while using the system location services.
* **Location permission**
  * IN\_USE - foreground allowed
  * ALWAYS - background allowed
  * DENIED - not determined or denied
* **v2.13.4 -BG Location Is Running** - yes/no (will be changed on Stop/Start Background Location or **Get background location service status**)

#### Actions:

* **Get current location**
  * minAccuracy \[iOS] - Radius in meters. All other values will be filtered!
  * accuractType \[iOS] - Affects on location accuracy and battery life. BestForNavigation,Best,NearestTenMeters,HundredMeters,Kilometer,ThreeKilometers. More details [here](https://developer.apple.com/documentation/corelocation/cllocationaccuracy)
  * Priority \[Android] - "BALANCED" (To save battery, recommended) & "HIGH"
  * Open Settings - If enabled and user's Location permission is denied, will display a pop-up with the option to open the app settings and turn on permission. - v2.18.0
* **Start foreground location service** - start fetching device location 
  * minAccuracy \[iOS] - Radius in meters. All other values will be filtered!
  * accuractType \[iOS] - Affects on location accuracy and battery life. BestForNavigation,Best,NearestTenMeters,HundredMeters,Kilometer,ThreeKilometers. More details [here](https://developer.apple.com/documentation/corelocation/cllocationaccuracy)
  * Priority \[Android] - "BALANCED" (To save battery, recommended) & "HIGH"
  * Fetching Interval - Determines how often the location will be fetched. Interval in milliseconds. 5000ms -> 5s
  * Open Settings - If enabled and user's Location permission is denied, will display a pop-up with the option to open the app settings and turn on permission. - v2.18.0
* **Stop foreground location service** - stop fetching device location
* **Get location permission** - request location permission status update
* **v2.13.4 -Get background location service status** - check if BG Location Service already running

{% hint style="info" %}
On page reload, the foreground location tracking service will be automatically stopped. You need to run the **Start foreground location service** action.
{% endhint %}

#### 🚙 Background location tracking - v2.1.0

{% hint style="info" %}
Before using background geolocation, make sure you've enabled it in your Natively App Dashboard + Created a new build.
{% endhint %}

#### States:

* **Latest location response status** - Status of the latest background location service start/stop.
  * SUCCESS - Background location started/stopped successfully
  * FAILED - Background location started/stopped with an error.

#### Events:

* **Location background failed** - Whenever starting of background service will fail
* **Location background success** -  Whenever starting of background service will succeed

#### Actions:

* **Start background location service** - start fetching device location 
  * minAccuracy \[iOS] - Radius in meters. All other values will be filtered!
  * accuractType \[iOS] - Affects on location accuracy and battery life. BestForNavigation,Best,NearestTenMeters,HundredMeters,Kilometer,ThreeKilometers. More details [here](https://developer.apple.com/documentation/corelocation/cllocationaccuracy)
  * Priority \[Android] - "BALANCED" (To save battery, recommended) & "HIGH"
  * Fetching Interval - Determines how often the location will be fetched. Interval in milliseconds. 5000ms -> 5s
  * Response Identifier - Identifier that will be sent with a user's location (We're recommending using the user's unique id)
  * Open Settings - If enabled and user's Location permission is denied, will display a pop-up with the option to open the app settings and turn on permission. - v2.18.0
* **Stop background location service** - stop fetching device location

{% hint style="warning" %}
Background geolocation can be automatically stopped in such cases: If the user or system closes the app,  or if the device receives more than 3 errors in response from your endpoint.
{% endhint %}

{% hint style="info" %}
Unlike foreground location service, the background will not stop on page reload
{% endhint %}

### Coordinates -> Marker address

To convert longitude and latitude to the bubble's geolocation, you need to use this formula:

![](https://3352617162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F90tV7pYflEQdiAr2VfWu%2Fuploads%2Fgit-blob-520169af1496acb034040d84d2f661a2b9fa6daf%2Fimage_b44k2.png?alt=media)

## 🛠 JavaScript SDK

### NativelyLocation

{% code overflow="wrap" lineNumbers="true" %}

```javascript
const locationService = new NativelyLocation()
const location_callback = function (resp) {
        console.log(resp.status); // "Success"/"Timeout"/"Error"
        console.log(resp.longitude); // 50.1231231
        console.log(resp.latitude); // 50.1231231
};
const minAccuracy = 50 // only available in 2.7.0 minAccuracy [iOS] - Radius in meters. All other values will be filtered!

const accuracyType = "Best" // only available in 2.7.0 accuractType [iOS] - Affects on location accuracy and battery life. BestForNavigation,Best,NearestTenMeters,HundredMeters,Kilometer,ThreeKilometers. More details here https://developer.apple.com/documentation/corelocation/cllocationaccuracy

const priority_android = "BALANCED" // "BALANCED" or "HIGH" [Android only]
const inerval = 10000 // in milliseconds 
const fallback_to_settings = true; // available from v2.15.16. If true and user's Location permission is denied, will display a pop-up with the option to open the app settings and turn on permission.

// Foreground Location
locationService.current(minAccuracy, accuracyType, priority_android, location_callback, fallback_to_settings);
locationService.start(interval, minAccuracy, accuracyType, priority_android, location_callback, fallback_to_settings);
locationService.stop();

const location_bg_callback = function (resp) {
        console.log(resp.status); // "SUCCESS"/"FAILED" - Start of background service was successfully or failed
};
const location_status_bg_callback = function (resp) {
        console.log(resp.status); // true/false - BG Location Service running or not
};
// Background Location
const responseId = "my-user-id" // SHOULD BE A STRING! Identifer that you will receive together with coordinates to your webhook endpoint
locationService.startBackground(interval, minAccuracy, accuracyType, priority_android, responseId, location_bg_callback, fallback_to_settings);
locationService.stopBackground(location_bg_callback);
locationService.statusBackground(location_status_bg_callback); // >=v2.12.3
```

{% endcode %}