NativeScript 上下文 API

为您的 NativeScript 应用轻松访问上下文信息。您的应用需要知道用户的位置吗？查看他们周围的 Wi-Fi AP？或许附近的 BLE 设备？或者可能想知道他们在做什么活动？如果对这些问题的任何一个答案是肯定的，那么这个插件就是您的选择。

目前我们提供

我们计划在未来提供

• 对设备上传感器的底层访问（加速度计、陀螺仪、指南针等）。
• 在 iOS 上也进行人类活动检测。
• 一种全新的基于实时传感器监控的细粒度人类活动检测机制。
• 用户位置反向地理编码。
• 当前用户位置的天气情况。

先决条件

仅限Android

由于此插件依赖于@triniwiz/nativescript-couchbase，因此至少需要Android SDK 22 (5.1)

Google Play服务冲突

鉴于我们依赖于nativescript-geolocation并使用Google Play服务API在Android设备上进行活动检测，您可能会发现Google Play服务版本与其他已安装插件冲突。

为了避免这种情况，我们建议您强制指定特定的Google Play服务版本。为了获得更好的人类活动检测功能，强烈推荐使用版本17或更高版本。为此，请在您的app/App_Resources/Android/before-plugins.gradle文件中指定Google Play服务版本号（如果该文件不存在，请创建它）

android {  
  // other things here

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

权限

接下来，对于此插件提供的每个信息源，您可以在位于App_Resources/Android/src/main目录中的您的应用程序的AndroidManifest.xml中看到需要添加的权限。

注意：如果您的应用程序需要使用此插件提供的多个信息源，我们建议您不要直接复制和粘贴以下各节的全部内容到您的应用程序清单中。请仔细检查是否有重复的权限（例如，用于位置和Wi-Fi都需要的位置权限），以避免可能的清单合并错误。

点击下面的可折叠部分，查看每个信息源所需的具体权限

<!-- 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" />

<!-- 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"/>

<!-- 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"/>

<!-- 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"/>

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

安装

在项目根目录中运行以下命令。

NS7+

ns plugin add nativescript-context-apis

NS6

tns plugin add nativescript-context-apis@1

（可选）您还需要RxJS来正确处理地理定位流

NS7+

npm install rxjs --save

NS6

npm install rxjs@6 --save

用法

仅用于人类活动检测

为了使活动检测正常工作，我们需要在某个地方将本地和JavaScript/TypeScript代码连接起来。

最佳位置是在您的应用程序的入口点脚本中。您需要向其中添加几行代码

// 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);

地理定位

如果您想获取地理定位更新，首先需要检查您是否有权限这样做，如果没有，请按照以下方式请求权限

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();
    }
}

完成操作后（请注意，isReady() 和 prepare() 方法是异步的），您将能够获取当前用户的位置或位置流。

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)
    });
}

人类活动检测

如果您想获取粗粒度的人类活动变化，首先您需要检查是否有权限这样做，如果没有，请按照以下方式请求：

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`);
}

注意：如果您想使用中等粒度的识别器，只需将 Resolution.LOW 替换为 Resolution.MEDIUM。

然后您将能够添加或删除活动变化监听器。

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();

注册监听器后，您就可以指示活动识别器开始或停止识别活动变化了。

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();

注意：感谢插件设计，即使在您的应用程序关闭或设备重启的情况下，识别状态也会保留。可以多次调用 startRecognizing 方法。如果您想更改启动参数，请先停止识别。也可以多次调用 stopRecognizing 方法，即使识别器没有运行。

附近的Wi-Fi AP更新

如果您想获取Wi-Fi扫描更新，首先您需要检查是否有权限这样做，如果没有，请按照以下方式请求：

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();
    }
}

完成操作后（请注意，isReady() 和 prepare() 方法是异步的），您将能够获取当前附近Wi-Fi AP的信息或Wi-Fi扫描更新的流。

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.cn/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),
    });
}

附近的BLE设备更新

如果您想获取BLE扫描更新，首先您需要检查是否有权限这样做，如果没有，请按照以下方式请求：

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();
    }
}

完成操作后（请注意，isReady() 和 prepare() 方法是异步的），您将能够获取当前附近BLE设备的信息或BLE扫描更新的流。

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}`),
    });
}

注意：请查看插件示例应用程序以获取更多使用细节。

API

点击下面的可折叠部分以查看每个信息源的更多API细节。

插件作者

致谢

本插件的开发得益于西班牙政府。具体来说，来自西班牙教育部、文化和体育部（资助编号FPU17/03832），以及“面向社会挑战的R&D+i国家计划”（编号RTI2018-099939-BI-00）。

此项目是从SyMptOMS项目（位于Geotec）中提取的开放源代码摘录。具体来说，它在SyMptOMS移动应用程序中已经重用了两年多，并包含了我们在那里学到的一切。