NativeScript RadarIO

安装

tns plugin add nativescript-radar-io

要获取 Radar 发布可用的 API 密钥，请注册 Radar 账户。

IOS

配置项目

要在前台跟踪用户的位置，如果您尚未添加，必须在您的 Info.plist 文件中添加一个字符串用于 NSLocationWhenInUseUsageDescription 键。此字符串将在请求用户前台位置权限时显示。

要跟踪用户的后台位置，如果您尚未添加，还必须在您的 Info.plist 文件中添加一个字符串用于 NSLocationAlwaysUsageDescription（iOS 10 及之前）和 NSLocationAlwaysAndWhenInUseUsageDescription（iOS 11 及之后）键。这些字符串将在请求用户后台位置权限时显示。

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Your iOS 11 and higher background location usage description goes here. e.g., "This app uses your location in the background to recommend places nearby."</string>

<key>NSLocationAlwaysUsageDescription</key>
<string>Your iOS 10 and lower background location usage description goes here. e.g., "This app uses your location in the background to recommend places nearby."</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your foreground location usage description goes here. e.g., "This app uses your location in the foreground to recommend places nearby."</string>

为了提高后台的可靠性和响应速度，您还应该开启位置更新。注意，这需要在 App Store 审查期间提供额外的证明。了解更多信息。

添加到 Info.plist

<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>
  <string>location</string>
</array>

用法

导入模块

首先，导入模块

import { RadarIO } from 'nativescript-radar-io';

启用地点

如果您正在使用地点，您必须将 Facebook 设置为您的地点数据提供商。

要将 Facebook 设置为您的地点数据提供商，请调用

RadarIO.setPlacesProvider('facebook');

要稍后禁用地点，请调用

RadarIO.setPlacesProvider('none');

有关地点的更多信息。

识别用户

在您识别用户之前，Radar 会自动通过设备 ID 识别用户。

要识别登录时的用户，请调用

RadarIO.setUserId(userId);

其中 userId 是用户的稳定唯一 ID 字符串。

请勿为 userId 发送任何 PII，如姓名、电子邮件地址或公开可用的 ID。有关更多信息，请参阅隐私最佳实践。

要设置用户的可选自定义元数据字典，请调用

RadarIO.setMetadata(metadata);

其中 metadata 是一个最多有 16 个键的 JSON 对象，其值类型为字符串、布尔值或数字。

最后，要设置用户在仪表板中显示的可选描述，请调用

RadarIO.setDescription(description);

其中 description 是一个字符串。

您只需调用这些函数一次，因为这些设置将在应用会话之间持久存在。

请求权限

在跟踪用户的位置之前，用户必须已为该应用授予位置权限。

要确定用户是否已为该应用授予位置权限，请调用

RadarIO.getPermissionsStatus().then((status) => {
  // do something with status
});

status 将是一个字符串，其中之一是

• GRANTED
• DENIED
• UNKNOWN

要请求应用的位置权限，请调用

RadarIO.requestPermissions(background);

其中 background 是一个布尔值，表示是否请求后台位置权限或前台位置权限。在 Android 上，background 将被忽略。

前台跟踪

一旦您已初始化 SDK，已识别用户，并且用户已授予权限，您就可以跟踪用户的位置。

要跟踪用户的前台位置，请调用

RadarIO.trackOnce().then((result) => {
  // do something with result.location, result.events, result.user.geofences
}).catch((err) => {
  // optionally, do something with err
});

err 将是一个字符串，其中之一是

• ERROR_PUBLISHABLE_KEY：SDK 未初始化
• ERROR_PERMISSIONS：用户未为应用授予位置权限
• ERROR_LOCATION：位置服务不可用，或位置请求超时
• ERROR_NETWORK：网络不可用，或网络连接超时
• ERROR_UNAUTHORIZED：可发布API密钥无效
• ERROR_SERVER：发生内部服务器错误
• ERROR_UNKNOWN：发生未知错误

后台追踪

一旦初始化了SDK，识别了用户，并且用户已经授权，就可以开始追踪用户的后台位置。

要开始追踪用户的后台位置，请调用

RadarIO.startTracking();

假设您已正确配置项目，当用户移动时（通常每3-5分钟），SDK会唤醒，当用户停止时（通常在5-10分钟内）关闭。为了节省电量，SDK在停止时不会唤醒，用户至少需要移动100米（有时更多）才能唤醒SDK。注意，iOS的低电量模式、Android的休眠模式和应用空闲模式和后台位置限制，或设备连接问题、电量低或Wi-Fi关闭时，可能会导致位置更新延迟。这些限制适用于iOS和Android上所有后台位置服务的使用，而不仅仅是Radar。有关精度和可靠性的更多信息。

可选地，您可以配置高级追踪选项。有关这些选项的描述，请参阅iOS后台追踪文档和Android后台追踪文档。

RadarIO.startTracking({
  priority: 'responsiveness', // // use 'efficiency' to avoid Android vitals bad behavior thresholds (ignored on iOS)
  sync: 'possibleStateChanges', // use 'all' to sync all location updates ('possibleStateChanges' recommended)
  offline: 'replayStopped' // use 'replayOff' to disable offline replay ('replayStopped' recommended)
});

要停止追踪用户的后台位置（例如，当用户登出时），请调用

RadarIO.stopTracking();

您只需要调用这些方法一次，因为这些设置将跨应用会话持续存在。

要监听事件、位置更新和错误，您可以添加事件监听器

RadarIO.on('events', (result) => {
  // do something with result.events, result.user
});

RadarIO.on('location', (result) => {
  // do something with result.location, result.user
});

RadarIO.on('error', (err) => {
  // do something with err
});

如果您希望在应用处于后台时使用这些监听器，请将事件监听器添加到组件生命周期之外（例如，在componentDidMount之外）。

您也可以移除事件监听器

RadarIO.off('events');

RadarIO.off('location');

RadarIO.off('error');

电池使用

对于大多数用户，使用原生iOS和Android SDK的后台追踪每天消耗1-2%的电量。更多详情请参阅SDK文档。

在Android上，当应用在后台启动时，接收器会加载并解析JavaScript包。如果您不想在JavaScript中接收事件并想禁用此功能，请在您的清单中添加一个覆盖

<receiver
  tools:replace="android:enabled"
  android:name="com.github.triniwiz.radario.Receiver"
  android:enabled="false"
  android:exported="false" />

手动追踪

您可以通过调用来手动更新用户的位置

const location = {
  latitude: 39.2904,
  longitude: -76.6122,
  accuracy: 65
};

RadarIO.updateLocation(location).then((result) => {
  // do something with result.events, result.user.geofences
}).catch((err) => {
  // optionally, do something with err
});

许可

Apache License Version 2.0，2004年1月