使用 @capgo/background-geolocation

精确的背景地理位置和本机地理围栏功能为 Capacitor 应用程序提供 iOS 和 Android 支持。使用它来流式传输精确的位置更新、监控圆形区域以及将地理围栏进入/退出转换传递给 JavaScript 或您的后端。

安装

bun add @capgo/background-geolocation
bunx cap sync

此插件暴露了什么

start - 实时获取前台或后台位置更新。
stop - 停止当前的位置跟踪。
openSettings - 打开原生设置以解决位置权限问题。
setPlannedRoute - 当用户离开规划好的路线时，播放原生声音。
setupGeofencing - 配置原生地理围栏的默认值和可选的过渡 webhook 发送。
addGeofence - 监听 iOS 或 Android 的圆形地理围栏区域。
removeGeofence / removeAllGeofences - 停止监控已注册的区域。
getMonitoredGeofences - 列出监控的区域标识符。
geofenceTransition listener - 在应用程序处于活动状态时接收进入和退出事件。
geofenceError listener - 分别处理原生监控错误和过渡事件。

示例用法

`start`

要开始监听设备的位置变化，请调用此方法。该方法返回一个 Promise，表示它完成了调用。回调将在每次获得新位置时或调用此方法时出现错误时被调用。不要依赖 promise 拒绝来处理此问题。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.start(
  {
    backgroundMessage: "App is using your location in the background",
    backgroundTitle: "Location Service",
    requestPermissions: true,
    stale: false,
    distanceFilter: 10
  },
  (location, error) => {
    if (error) {
      console.error('Location error:', error);
      return;
    }
    if (location) {
      console.log('New location:', location.latitude, location.longitude);
    }
  }
);

`stop`

停止位置更新。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.stop();

`openSettings`

打开设备的位置设置页面。有助于指导用户启用位置服务或调整权限。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

// Direct user to location settings
await BackgroundGeolocation.openSettings();

`setPlannedRoute`

当用户偏离规划路线时，播放声音文件。该功能应用于播放背景声音（仅限原生）。

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setPlannedRoute({
  soundFile: "notification.mp3",
  route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
});

原生地理围栏

使用原生 iOS 和 Android 地理围栏监控商店、工作地点、送货区域、校园或签到区域。添加 HTTP 或 HTTPS url 让原生 code 在 WebView 被挂起时 POST 转换负载：

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/geofences',
  notifyOnEntry: true,
  notifyOnExit: true,
  payload: { userId: '123' },
});

await BackgroundGeolocation.addGeofence({
  identifier: 'warehouse',
  latitude: 40.7128,
  longitude: -74.006,
  radius: 200,
});

const listener = await BackgroundGeolocation.addListener(
  'geofenceTransition',
  (event) => console.log(event.identifier, event.transition),
);

const errorListener = await BackgroundGeolocation.addListener(
  'geofenceError',
  (event) => console.error(event.identifier, event.message),
);

await BackgroundGeolocation.removeGeofence({ identifier: 'warehouse' });
await listener.remove();
await errorListener.remove();

在 Android 上，添加 ACCESS_BACKGROUND_LOCATION 仅当您需要背景地理围栏时，在您的应用清单中添加

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

全局参考

GitHub: https://github.com/Cap-go/capacitor-background-geolocation/
文档：/docs/plugins/background-geolocation/

继续使用 @capgo/background-geolocation

如果您正在使用 使用 @capgo/background-geolocation 为native插件工作计划，连接它与 @capgo/background-geolocation 在 @capgo/background-geolocation 中查看实现细节 Getting Started 在 Getting Started 中查看实现细节 Capgo 插件目录在 Capgo 插件目录中查看产品工作流程 Capacitor 由 Capgo 提供的插件在 Capacitor 由 Capgo 提供的插件中查看实现细节添加或更新插件为添加或更新插件提供实现细节。

背景地理位置