SDK

Location Services

In this page you'll dive deeper into functionality like using GPS signals to get the user's location or monitor their visits to regions and proximity to BTLE devices.

These services will bring a new level of contextuality to your app, allowing you to create geo-triggers to send notifications or categorize users based on their location behaviour.

Tracking a user location in iOS will require the user's authorization. This means that your app must declare usage description texts explaining why it needs to track location. It is mandatory the use of the key NSLocationAlwaysUsageDescription. In iOS 11, a new permission was introduced, and you are required to include both NSLocationAlwaysAndWhenInUseUsageDescription and NSLocationWhenInUseUsageDescription in your Info.plist file. In short, if you want to support all versions, you need to include the following:

<plist version="1.0">
<dict>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>We will need to make use of your location to present relevant information about offers around you.</string>
    <key>NSLocationAlwaysUsageDescription</key>
    <string>We will need to make use of your location to present relevant information about offers around you.</string>
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>We will need to make use of your location to present relevant information about offers around you.</string>
</dict>
</plist>

Make sure you provide a text that best describes why and how you are going to use the user’s location. This text will be displayed to the user the first time you request the use of location services. Users are more likely to trust your app with location data if they understand why you need it.

As mentioned in the Implementation page, if you are going to use location services, you must include the following dependency:

cordova plugin add cordova-plugin-notificare-geo

Requesting Permissions

Additional to the manifest permissions and plist entries, applications will need to request the user permission to use location.

These permissions need to be requested by your app, after which you can safely enable location updates.

In order to fully leverage the geo functionality, the users needs to allow access to background location. To allow for an easier handling of permissions between versions, your app needs to make a distinction between foreground and background location updates permissions.

It is important to note the Notificare library is not notified of authorization status changes, therefore you have to call NotificareGeo.enableLocationUpdates() on every authorization status change. This allows us to check the latest authorization and act accordingly by enabling location tracking, geofencing or clearing up location data based on the user's decision.

In order to achieve what was mentioned above, here is a rough implementation to serve as a guide. You'll have to adjust this sample to match your application.

async function onEnableLocationUpdatesClicked() {
  try {
    const hasFullCapabilities =
      (await ensureForegroundLocationPermission()) &&
      (await ensureBackgroundLocationPermission()) &&
      (await ensureBluetoothScanPermission());

    // Calling enableLocationUpdates() will evaluate the given permissions, if any, and enable the available capabilities.
    await NotificareGeo.enableLocationUpdates();
  } catch (e) {
    // Handle the platform error.
  }
}

async function ensureForegroundLocationPermission(): Promise<boolean> {
  const status = await NotificareGeo.checkPermissionStatus('location_when_in_use');
  if (status == 'granted') return true;

  if (status == 'permantly_denied') {
    // TODO: Show some informational UI, educating the user to change the permission via the Settings app.
    await NotificareGeo.openAppSettings();
    return false;
  }

  if (await NotificareGeo.shouldShowPermissionRationale('location_when_in_use')) {
    await NotificareGeo.presentPermissionRationale('location_when_in_use', {
      title: 'Sample',
      message: 'We need access to foreground location in order to show relevant content.',
    });
  }

  return (await NotificareGeo.requestPermission('location_when_in_use')) == 'granted';
}

async function ensureBackgroundLocationPermission(): Promise<boolean> {
  const status = await NotificareGeo.checkPermissionStatus('location_always');
  if (status == 'granted') return true;

  if (status == 'permantly_denied') {
    // TODO: Show some informational UI, educating the user to change the permission via the Settings app.
    await NotificareGeo.openAppSettings();
    return false;
  }

  if (await NotificareGeo.shouldShowPermissionRationale('location_always')) {
    await NotificareGeo.presentPermissionRationale('location_always', {
      title: 'Sample',
      message: 'We need access to background location in order to show relevant content.',
    });
  }

  return (await NotificareGeo.requestPermission('location_always')) == 'granted';
}

async function ensureBluetoothScanPermission(): Promise<boolean> {
  const status = await NotificareGeo.checkPermissionStatus('bluetooth_scan');
  if (status == 'granted') return true;

  if (status == 'permantly_denied') {
    // TODO: Show some informational UI, educating the user to change the permission via the Settings app.
    await NotificareGeo.openAppSettings();
    return false;
  }

  if (await NotificareGeo.shouldShowPermissionRationale('bluetooth_scan')) {
    await NotificareGeo.presentPermissionRationale('bluetooth_scan', {
      title: 'Sample',
      message: 'We need access to bluetooth scan in order to show relevant content.',
    });
  }

  return (await NotificareGeo.requestPermission('bluetooth_scan')) == 'granted';
}

The snippet above uses the convenience methods available in the NotificareGeo plugin to handle the bridge into native permissions. You can use any other plugin or implement the bridge yourself. The focus of the snippet is guiding you on the necessary permissions and recommended upgrade path.

To make sure the location updates aren't started before the library is ready to be used, you should wait until it is safe to do so, by listening to the ready event. Once you have requested the appropriate permissions, and they have been granted, you can call NotificareGeo.enableLocationUpdates() to start receiving location updates. Our library will automatically collect the user location and start monitoring for regions you've created via the dashboard or API.

When authorized, you will also want to start using location data whenever your app is launched. You simply have to add the following when Notificare becomes ready:

Notificare.onReady(async (application) => {
  if (await NotificareGeo.hasLocationServicesEnabled) {
    await NotificareGeo.enableLocationUpdates();
  }
});

Using Bluetooth Low-Energy Beacons

Once you've implemented the location functionality, we automatically monitor BTLE beacons in the user's vicinity.

Since Android 12, your app needs explicit permission for Bluetooth scanning in order to detect beacons. On devices running older versions of Android, the permission will be granted automatically.

However, you might want to retrieve the proximity level of any beacons around you. This is only possible while the app is in foreground. To get this information you will need to implement the following listener:

NotificareGeo.onBeaconsRanged(({ region, beacons }) => {

});

This is not a mandatory step in order to use beacons, as geo-triggers created in the dashboard will trigger notifications whenever you are in the vicinity of a beacon, even when your app is not being used.

Beacon scanning with a foreground service

In Oreo and up, background scans are more limited. First scans of a beacon in a region will come in very quickly, but detection of changes or leaving the beacon's range will take up to 15 minutes when in background. This limitation is posed by Android itself and there is no workaround to do this in background mode.

The only way to have your app scan for beacons more often on Android version Oreo and up, is by starting the scan as a foreground service. Foreground services will be shown to the user as an ongoing notification. You can opt in to this feature by adding the following to your AndroidManifest.xml:

<application>
  <meta-data
      android:name="re.notifica.geo.beacons.foreground_service_enabled"
      android:value="true" />
</application>

By default, the notification will be shown in the default channel from the Push module. If you are not using it, or would like to customise how the notification looks like, you can use the following meta-data properties.

<application>
    <meta-data
        android:name="re.notifica.geo.beacons.service_notification_channel"
        android:value="custom_beacon_notification_channel" />

    <meta-data
        android:name="re.notifica.geo.beacons.service_notification_small_icon"
        android:resource="@drawable/ic_baseline_bluetooth_searching_24" />

    <meta-data
        android:name="re.notifica.geo.beacons.service_notification_content_title"
        android:value="Scanning for beacons" />

    <meta-data
        android:name="re.notifica.geo.beacons.service_notification_content_text"
        android:value="A relevant piece of text informing the user why the app is scanning for beacons." />

    <meta-data
        android:name="re.notifica.geo.beacons.service_notification_progress"
        android:value="true" />
</application>

Using Visits API (iOS-only)

As part of our location services feature, you will be able to use Apple's Visits API. This API will allow you to get events whenever users visit a location. This might be a great way to discover which areas a user visits. To use this feature you will need to turn the VISITS_API_ENABLED property to YES in your app's NotificareOptions.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>VISITS_API_ENABLED</key>
	<true/>
</dict>
</plist>

When enabled, as soon as you start location updates you will be receiving visits events too. To handle those visits make sure you implement the following delegate method:

NotificareGeo.onVisit((visit) => {

});

Using Heading API (iOS-only)

Also part of our location services feature, Apple's Heading API will allow you to obtain the user's current heading. To use this feature you will need to turn the HEADING_API_ENABLED property to YES in your app's NotificareOptions.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>HEADING_API_ENABLED</key>
	<true/>
</dict>
</plist>

When enabled, as soon as you start location updates you will be receiving heading events too. To handle those events make sure you implement the following delegate method:

NotificareGeo.onHeadingUpdated((heading) => {

});

Disable Location

The same way you enable location, you can stop tracking the user location by invoking the following method:

await NotificareGeo.disableLocationUpdates();