nativescript-context-apis v4.1.3

NativeScript Context APIs

Painless access to contextual information for your NativeScript apps. Does your app need to know where are your users located? See the Wi-Fi APs that surround them? Maybe the nearby BLE devices? Or perhaps which kind of activities are they doing? If the answer to any of these questions is yes, then, this is your plugin.

Currently we offer:

What we plan to offer in the future:

• Low level access to on-device sensors (accelerometer, gyroscope, compass, etc.).
• Human activity detection in iOS too.
• A whole new fine-grained human activity detection mechanism, based on real-time sensor monitoring.
• User location reverse geocoding.
• Weather at current user location.

Prerequisites

Android only

Android SDK 22 (5.1) is required as a minimum due to the dependency of this plugin on @triniwiz/nativescript-couchbase

Google Play Services conflicts

Given that we rely on nativescript-geolocation and use Google Play Services APIs for activity detection on Android devices, you might find Google Play Services version conflicts with other installed plugins.

In order to avoid them, we advise you to force a specific Google Play Services version. For a better human activity detection functionality, version 17 or above is highly recommended. In order to do so, please, indicate the Google Play Services Version number in your app/App_Resources/Android/before-plugins.gradle file (if the file does not exist, just create it):

android {  
  // other things here

  project.ext {
    googlePlayServicesVersion = "17.+"
  }
}

Permissions

Next, for each one of the information sources that this plugin offers, you can see the permissions that need to be added to you app's AndroidManifest.xml located inside the App_Resources/Android/src/main directory.

Note: If your app is expected to use more than one of the information sources offered by this plugin, we advise to avoid just copying and pasting the content of each of the following sections inside your application manifest. Check twice for duplicated permissions (e.g., location permissions necessary for both location and Wi-Fi to work) to avoid possible manifest merging errors.

Click on each of the collapsible sections bellow to see the specific permissions required by each information source:

In order to access geolocation in Android, you'll need to add the following permission(s) to your app's AndroidManifest.xml:

<!-- Always include this permission if your app needs location access -->
<!-- This permission is for "approximate" location data -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- Include only if your app benefits from precise location access. -->
<!-- This permission is for "precise" location data -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Required only when requesting background location access on Android 10 (API level 29) and higher. -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

More information can be found in the Android docs here.

Source: https://github.com/NativeScript/nativescript-geolocation

In order to receive human activity changes in Android, you'll need to add the following permission(s) to your app's AndroidManifest.xml:

<!-- The following two permissions are required if your app wants to receive human activity changes -->
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION"/>
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>

More information can be found in the Android docs here.

In order to receive Wi-Fi scan updates in Android, you'll need to add the following permission(s) to your app's AndroidManifest.xml:

<!-- ALL the following permissions are required in order to ask and retrieve Wi-Fi scan updates -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

More information can be found in the Android docs here.

In order to receive BLE scan updates in Android, you'll need to add the following permission(s) to your app's AndroidManifest.xml:

<!-- ALL the following permissions are required in order to ask and retrieve BLE scan updates -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>

More information can be found in the Android docs here.

Additionally, the BLE scanning API uses the well-known scanning library developed by Nordic Semiconductors. To ensure this library is only included when the BLE scanning apis are meant to be accessed. To do that, you'll have to update your app's app.gradle file located inside the App_Resources/Android/src folder as follows:

// Uncomment
dependencies {
    implementation 'no.nordicsemi.android.support.v18:scanner:1.6.0'
}

Installation

Run the following command in your project's root folder.

NS7+:

ns plugin add nativescript-context-apis

NS6:

tns plugin add nativescript-context-apis@1

(Optional) You'll need RxJS also to properly work with geolocation streams

NS7+:

npm install rxjs --save

NS6:

npm install rxjs@6 --save

Usage

For human activity detection only

For activity detection to properly work, we need to wire native and JavaScript/TypeScript code somewhere.

The best place to do it is in your app's entry point script. You'll need to add a couple of lines to it:

// app.ts / main.ts
// TypeScript App:
import * as app from "tns-core-modules/application";
// or Angular App:
import { platformNativeScriptDynamic } from "nativescript-angular/platform";
import { AppModule } from "./app/app.module";

// NativeScript Task Context APIs plugin import
// (always between imports and app initialization)
import { contextApis } from "nativescript-context-apis";

contextApis.init().catch((err) => {
  // You can catch initialization errors here
});

// TypeScript App:
app.run({ moduleName: "app-root" });
// Angular App:
platformNativeScriptDynamic().bootstrapModule(AppModule);

Geolocation

In case you want to obtain geolocation updates, first you'll need to check if you have permissions to do so and if not, ask for them as follows:

import { contextApis } from "nativescript-context-apis";

async function checkGeolocationAccessStatus(): Promise<void> {
    const provider = contextApis.geolocationProvider;
    const isReady = await provider.isReady();
    if (!isReady) {
      await provider.prepare();
    }
}

Once done (keep in mind that isReady() and prepare() methods are asynchronous), you'll be able to ask for current user's location or a stream of locations:

import { contextApis } from "nativescript-context-apis";

// You can get the current location like this
async function printCurrentLocation() {
    const provider = contextApis.geolocationProvider;
    const location = await provider.acquireLocation({
            highAccuracy: true, // Accuracy is high by default
            timeout: 5000, // You can also specify the operation timeout (highly advised)
        });
    console.log("Current location:", location);
}

// Or a location stream
import { Subscription } from "rxjs";

async function printLocationUpdates(): Promise<Subscription> {
    const provider = contextApis.geolocationProvider;
    
    const stream = provider.locationStream({
          highAccuracy: true, // Again, accuracy is high by default
          stdInterval: 1000, // The location fetch interval
          minInterval: 100, // Opportunistic interval (another app asked for a location)
          timeout: 5000, // You can also specify the operation timeout (highly advised)
          maxAge: 60000, // And filter-out old locations
      });

    return stream.subscribe({
        next: (location) =>
            console.log("New location acquired!:", location),
        error: (error) =>
            console.error("Location updates could not be acquired:", error)
    });
}

Human activity detection

In case you want to obtain coarse grained human activity changes, first you'll need to check if you have permissions to do so and if not, ask them for as follows:

import { contextApis } from "nativescript-context-apis";
import { Resolution } from "nativescript-context-apis/activity-recognition";

async function checkActivityRecognitionStatus(): Promise<void> {
    const recognizer = contextApis.getActivityRecognizer(Resolution.LOW);
    const isReady = recognizer.isReady();
    if (!isReady) {
        console.log(
            `Up to prepare coarse-grained activity recognizer...`
        );
        await recognizer.prepare();
    }
    console.log(`Coarse-grained activity recognizer is ready`);
}

Note: If you want to use the medium-grained recognizer, just replace Resolution.LOW with Resolution.MEDIUM.

Then you will be able to add or remove activity change listeners.

import { contextApis } from "nativescript-context-apis";
import { Resolution } from "nativescript-context-apis/activity-recognition";

const recognizer = contextApis.getActivityRecognizer(Resolution.LOW);

// Register a listener
const listenerId = recognizer.listenActivityChanges((activityChange) => {
  console.log("ActivityChange:", activityChange);
});
console.log(`Coarse-grained activity recognizer has registered a listener (id: ${listenerId})`);

// ...
// Somewhere else
// ...

// Deregister a concrete listener
recognizer.stopListening(listenerId);
// Or all of them
recognizer.stopListening();

After registering your listeners, you will be all set to indicate the activity recognizer to start or stop recognizing activity changes

import { contextApis } from "nativescript-context-apis";
import { Resolution } from "nativescript-context-apis/activity-recognition";

const recognizer = contextApis.getActivityRecognizer(Resolution.LOW);

// Start recognizing
recognizer.startRecognizing();

// ...
// Somewhere else
// ...

// Stop recognizing
recognizer.stopRecognizing();

Note: Thanks to plugin design recognition state will be kept even if your app gets closed, or the device gets rebooted. It is safe to call multiple times to startRecognizing method. If you want to change your start parameters, stop recognizing first. It is also safe to call multiple times to stopRecognizing method, even if the recognizer is not running.

Nearby Wi-Fi APs updates

In case you want to obtain Wi-Fi scan updates, first you'll need to check if you have permissions to do so and if not, ask for them as follows:

import { contextApis } from "nativescript-context-apis";

async function checkWifiScanAccessStatus(): Promise<void> {
    const provider = contextApis.wifiScanProvider;
    const isReady = await provider.isReady();
    if (!isReady) {
      await provider.prepare();
    }
}

Once done (keep in mind that isReady() and prepare() methods are asynchronous), you'll be able to ask for current nearby Wi-Fi APs' information or a stream of Wi-Fi scan updates:

import { contextApis } from "nativescript-context-apis";

// You can get the current nearby Wi-Fi APs' information like this
async function printCurrentNearbyWiFiAPs() {
    const provider = contextApis.wifiScanProvider;
    const scanResult = await provider.acquireWifiFingerprint(
            true // Ensures the scan result is new (true by default), 
                 // thus adhering to Android OS Wi-Fi scanning limits: 
                 // https://developer.android.com/guide/topics/connectivity/wifi-scan#wifi-scan-throttling
        );
    console.log("Current nearby Wi-Fi APs:", scanResult);
}

// Or a Wi-Fi scan updates stream
import { Subscription } from "rxjs";
import { FingerprintGrouping } from "nativescript-context-apis/wifi";

async function printWifiScanUpdates(): Promise<Subscription> {
    const provider = contextApis.wifiScanProvider;
    
    const stream = provider.wifiFingerprintStream({
        ensureAlwaysNew: true, // Identical in purpose to the parameter in acquireWifiFingerpint()
        grouping: FingerprintGrouping.NONE, // Configure Wi-Fi scan updates batching (see API bellow)
        continueOnFailure: true, // Determines if the stream has to report any scanning error and close
      });

    return stream.subscribe({
        next: (fingerprint) =>
            console.log("New wifi scan result!:", fingerprint),
        error: (error) =>
            console.error("Wifi scan result could not be acquired:", error),
    });
}

Nearby BLE devices updates

In case you want to obtain BLE scan updates, first you'll need to check if you have permissions to do so and if not, ask for them as follows:

import { contextApis } from "nativescript-context-apis";

async function checkBleScanAccessStatus(): Promise<void> {
    const provider = contextApis.bleScanProvider;
    const isReady = await provider.isReady();
    if (!isReady) {
      await provider.prepare();
    }
}

Once done (keep in mind that isReady() and prepare() methods are asynchronous), you'll be able to ask for current nearby BLE devices' information or a stream of BLE scan updates:

import { contextApis } from "nativescript-context-apis";
import { BleScanMode } from "nativescript-context-apis/ble";

// You can get the current nearby BLE devices' information like this
async function printCurrentNearbyBleDevices() {
    const provider = contextApis.bleScanProvider;
    const scanResult = await provider.acquireBleScan({
        scanTime: 5000, // (optional) when not specified it will wait until seeing a device and inmediatelly return, 
                        // otherwise it accumulates the seen devices and outputs after the scan time finishes.
                        // It may throw a timeout when used in conjunction with a list of iBeacon UUIDs 
                        // (in case no known beacon has been detected in the meantime)  
        scanMode: BleScanMode.BALANCED, // (optional) Can be LOW_POWER or LOW_LATENCY too. BALANCED by default
        iBeaconUuids: [
            // (optional) add a list of iBeacon UUIDs if you're just looking for known beacons
        ],
    });
    console.log("Current nearby BLE devices:", scanResult);
}

// Or a BLE scan updates stream
import { Subscription } from "rxjs";

async function printWifiScanUpdates(): Promise<Subscription> {
    const provider = contextApis.bleScanProvider;
    
    const stream = provider.bleScanStream({
        reportInterval: 2000, // (optional) when not specified it will output a result as soon as a device is seen, 
                              // otherwise it accumulates the detected devices and outputs when told
        scanMode: BleScanMode.LOW_LATENCY, // (optional) same as for the acquire method
        iBeaconUuids: [
            // (optional) Same as for the acquire method
        ],
    })

    return stream.subscribe({
        next: (bleScanResult) =>
            console.log(
                `New ble scan result!: ${JSON.stringify(bleScanResult)}`
            ),
        error: (error) =>
            console.error(`Ble scan result could not be acquired: ${error}`),
    });
}

Note: Check plugin demo app for further usage details

API

Click on each of the collapsible sections bellow to see more API details for each information source:

Geolocation

GeolocationLike (Interface)

Same as Geolocation, but only latitude and longitude are mandatory. The rest of the attributes are optional.

Geolocation acquire options

Before requesting user's current location some options can be customized in order to achieve the expected result.

Note: These options are identical (only the name changes) to the ones from nativescript-geolocation. Check plugin docs in case of doubt.

Geolocation stream options

Before requesting user's location updates some options can be customized in order to achieve the expected result.

Note: These options are identical (only the name changes) to the ones from nativescript-geolocation. Check plugin docs in case of doubt.

GeolocationProvider

Available recognizer resolutions

Available human activities

Available activity transitions

ActivityChange

Activity recognizer StartOptions

ActivityRecognizer

WifiFingerprint

WifiApInfo

ChannelBandwidth

WifiStandard

WifiChainInfo

Wi-Fi fingerprint acquire parameters

Before requesting current information about the nearby Wi-Fi APs some options can be customized in order to achieve the expected result.

Wi-Fi fingerprint stream options

Before requesting updates on information about the nearby Wi-Fi APs some options can be customized in order to achieve the expected result.

FingerprintGrouping

WifiScanProvider

BleScanResult

BleDeviceInfo

PhyType

IBeaconData

BLE scan acquire options

Before requesting current information about the nearby BLE devices some options can be customized in order to achieve the expected result.

BleScanMode

BLE scan stream options

Before requesting updates on information about the nearby BLE devices some options can be customized in order to achieve the expected result.

BleScanProvider

Plugin authors

Acknowledgements

The development of this plugin has been made possible thanks to the Spanish Government. Concretely from, Spanish Ministry of Education, Culture and Sports (grant reference FPU17/03832), and “Programa Estatal de I+D+i Orientada a los Retos de la Sociedad" (reference RTI2018-099939-BI-00).

This project is an open-sourced excerpt coming from SyMptOMS project at Geotec. Concretely, it has been heavily used in SyMptOMS mobile app for more than two years and contains all the lessons we have learned there.