Background Location

This guide will help you integrate background location tracking into your app, enabling you to receive device location updates even when the app is running in the background. You can also store these location updates on your server.

Key Features

• Background Location Tracking: Get device location updates while the app is running in the background.
• Server Storage: Option to send and store location data on your server.

Setting Up Background Location Tracking

1. Add Background Location to Cart:

   • Add the background location feature to your cart.

2. Enable Background Location:

   • Go to the plugin section of your app settings.
   • Navigate to the background location settings.
   • Enable or disable the background location tracking option.
   • Save your settings and rebuild the app.

Import the JavaScript File

Before starting, import the necessary JavaScript file into your website using the provided link.

Implementing Background Location Tracking

Start Receiving Location Updates

Plain JavaScript:

window.WTN.backgroundLocation.start({
  callback: locationCallback,
  apiUrl: 'https://your-api-endpoint.com/location',
  timeout: 60000, // 1 minute
  data: { userId: 'yourUserId' },
  backgroundIndicator: false, // iOS only
  pauseAutomatically: true, // iOS only
  distanceFilter: 10.0,
  desiredAccuracy: "best",
  activityType: "fitness", // iOS only
});
 
// Example callback function
function locationCallback(location) {
  console.log(location);
}

ES6+:

import { start, stop } from "webtonative/BackgroundLocation";
 
// Start receiving location updates
start({
  callback: locationCallback,
  apiUrl: 'https://your-api-endpoint.com/location',
  timeout: 60000, // 1 minute
  data: { userId: 'yourUserId' },
  backgroundIndicator: false, // iOS only
  pauseAutomatically: true, // iOS only
  distanceFilter: 10.0,
  desiredAccuracy: "best",
  activityType: "fitness", // iOS only
});
 
// Example callback function
function locationCallback(location) {
  console.log(location);
}

Stop Receiving Location Updates

Plain JavaScript:

window.WTN.backgroundLocation.stop();

ES6+:

import { stop } from "webtonative/BackgroundLocation";
 
// Stop receiving location updates
stop();

Configuration Options

• callback: (Optional if apiUrl is provided) A JavaScript function called to send you location updates.
• apiUrl: (Optional if callback is provided) An API endpoint that will be called using the POST method to send location updates.
• data: (Optional) Extra data to send along with location updates. Useful for identifying users or other custom data.
• backgroundIndicator: (Optional, Default: false, iOS only) Modifies the status bar on iOS to indicate that the app is using location services when backgrounded.
• pauseAutomatically: (Optional, Default: true, iOS only) Pauses updates to save battery life when location data is unlikely to change.
• distanceFilter: (Optional, Default: 0.0 meters) The minimum distance a device must move horizontally before generating an update event.
• desiredAccuracy: (Optional, Default: "best", iOS only) The accuracy of the location data. Options: "best", "bestForNavigation", "tenMeters", "hundredMeters", "kilometer", "threeKilometers".
• activityType: (Optional, Default: "other", iOS only) The type of user activity. Options: "other", "automotiveNavigation", "otherNavigation", "fitness", "airborne".

Location Object

When a location update is sent to your callback or apiUrl, the location object will contain:

• latitude: The latitude in degrees.
• longitude: The longitude in degrees.
• altitude: The altitude in meters.
• timestamp: Time of the location update in milliseconds since Jan 1, 1970.
• data: The extra data sent during the call to the start method.
• floor: (iOS only) The logical floor of the building.
• deviceID: Device ID.
• playerId: OneSignal Player ID (if OneSignal is enabled).
• speed: The instantaneous speed of the device in meters per second.
• direction: (iOS only) The direction the device is pointing (e.g., N, NE, E, SE, S, SW, W, NW).
• horizontalAccuracy: (iOS only) The radius of uncertainty for the location in meters.
• verticalAccuracy: The validity of the altitude values and their estimated uncertainty in meters.

Note

• Foreground Updates: Location updates will be sent to both the callback function and the apiUrl when the app is in the foreground.
• Background Updates: Only the apiUrl will be used to send location updates when the app is in the background.