背景位置

跟踪背景中的精确位置,并监控iOS和Android上的本土地缘. 用于快递,健身和外地服务应用,持续跟踪屏幕关闭后.

🤖 建筑与AI编码代理? 安装 Capgo 技能 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 @capgo/background-geolocation 在您的电容应用程序中: npx skills add Cap-go/capgo-skills。然后问你的经纪人: 添加@capgo/ 背地- 地理定位到我的 Capacitor app 并把它连接起来。" 代理设置指南 • 妇女 主机磁共振

主要特点

• 背景跟踪数字 : start() 包含选项的流位置更新, 如 distanceFilter 和一个背景通知信息, stop() 结束他们.
• 原生上传: 向您发送位置 url 从本地代码,并更改苍蝇上的标题 updateHeaders()。 。 。 .
• 地平线数字 : addGeofence(), (中文(简体) ), removeGeofence(), (中文(简体) ), removeAllGeofences() 财务报告和审定财务报表 getMonitoredGeofences(),与 geofenceTransition 财务报告和审定财务报表 geofenceError 事件.
• 路线指导数字 : setPlannedRoute() 当用户离开计划路线时播放声音.
• 权限数字 : checkPermissions(), (中文(简体) ), requestPermissions() 财务报告和审定财务报表 openSettings()。 。 。 .
• 平台: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. iOS使用Core Location,Android使用Google Play服务定位并具有前瞻服务.

IOS和Android上用于精确背景位置跟踪和本土地取地取地的Capacitor插件. 用它来流出精确位置更新,监视循环地缘区域,在JavaScript中反应出出出入出事件,而POST地缘过渡在WebView被暂停时在本土进行.

特征

• 没有付费许可证的准确前景和背景地理定位.
• 在iOS和Android上进行原生地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地.
• 进入和退出事件通过 geofenceTransition 当应用程序还活着.
• 当WebView被暂停时, 本地的 Webhook 交付用于地缘过渡 .
• 用于开发和基于浏览器的测试的网络回落.

此插件的历史

有趣的是,这个插件有很多历史. 最初的解决办法来自: 晶体管软 是一个伟大的软件,我(哈雷尔姆如果符合您的需要,鼓励使用.
我尝试了它,并理解它优先 电池寿命比精度, 这不适合我的徒步应用.
有一个非常好的叉子 毛龙85 我很高兴能帮你维持它.
但在某些时候, 毛龙85 停止对GitHub上的消息作出回应,没有人可以继续维护.
我希望Mauron85安全无事.

于是我创建了叉子并开始维持它 这里。 。 。 .
半个多世纪以来,它对我很有用 但我觉得由于它的历史 特征 和虫子修复 很难维持.
我也觉得由于它的复杂性,在引入新的特征方面存在着障碍.

于是我开始探索 减少这种复杂程度需要什么 同时,我羡慕到 @capacitor-community/background-geolocation 没错.
我选择了两个世界中最好的:尝试减少原Cordova插件中的代码库,并在Capacitor插件上加入一些强力.

所以我才留着这个.
我希望你会喜欢的!

插件比较

Capacitor apps中常用的三个主要背景-地心插件的简短比较.

注释:

• 社区插件是轻量级的并持续在后台工作,但已知其准确性低于下方的选项.
• 这个 Cap-go 插件旨在提供准确的定位修正,可靠的背景操作,以及本土的地峡出入口处理,而不需要付费许可证.
• 当iOS或Android为区域过渡唤醒了本地代码,但Capacitor WebView没有运行时,原生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生地生.
• Transistorsoft的插件是一个成熟而准确的解决方案,其中也包括了更宽的HTTP上传器. 这是一种商业产品,需要领取全额使用许可证.

使用量

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

BackgroundGeolocation.start(
    {
        backgroundMessage: "Cancel to prevent battery drain.",
        backgroundTitle: "Tracking You.",
        requestPermissions: true,
        stale: false,
        distanceFilter: 50
    },
    (location, error) => {
        if (error) {
            if (error.code === "NOT_AUTHORIZED") {
                if (window.confirm(
                    "This app needs your location, " +
                    "but does not have permission.\n\n" +
                    "Open settings now?"
                )) {
                    // It can be useful to direct the user to their device's
                    // settings when location permissions have been denied. The
                    // plugin provides the 'openSettings' method to do exactly
                    // this.
                    BackgroundGeolocation.openSettings();
                }
            }
            return console.error(error);
        }
        return console.log(location);
    }
).then(() => {
    // When location updates are no longer needed, the plugin should be stopped by calling
    BackgroundGeolocation.stop();
});

// Set a planned route to get a notification sound when a new location arrives and it's not on the route:
        
BackgroundGeolocation.setPlannedRoute({soundFile: "assets/myFile.mp3", route: [[1,2], [3,4]], distance: 30 });

原生地缘

需要商店,工作站点,送货区,校园或报到区等轻量级位置界限时,使用本地地圈. 该插件在应用程序活动时,对地理栅栏进行本土监测并释放出JavaScript事件. Android背景投递是可选的,只有在你选择加入时才会请求.

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

// Geofencing can notify JavaScript while the app is alive.
await BackgroundGeolocation.setupGeofencing({
    notifyOnEntry: true,
    notifyOnExit: true,
    payload: { userId: "123" }
});

await BackgroundGeolocation.addGeofence({
    identifier: "office",
    latitude: 37.33182,
    longitude: -122.03118,
    radius: 150
});

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

await BackgroundGeolocation.removeGeofence({ identifier: "office" });
handle.remove();

Android背景地圈权限

插件不添加 ACCESS_BACKGROUND_LOCATION 除非您明确选择加入,否则不请求。 只有使用前景定位的应用程序可以省略此权限.

仅在应用程序处于背景时需要Android地缘变换时才选择:

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

await BackgroundGeolocation.setupGeofencing({
    url: "https://api.example.com/geofences",
    backgroundLocation: true
});

// If you just want the current location, try something like this. The longer
// the timeout, the more accurate the guess will be. I wouldn't go below about 100ms.
function guessLocation(callback, timeout) {
    let last_location;
    BackgroundGeolocation.start(
        {
            requestPermissions: false,
            stale: true
        },
        (location) => {
            last_location = location || undefined;
        }
    ).then(() => {
        setTimeout(() => {
            callback(last_location);
            BackgroundGeolocation.stop();
        }, timeout);
    });
}

位置日志

召回只运行在 WebView 运行时, 和一个 POST 地址 url 请求失败时放弃。 与 locationLog 上,每个位置也被添加到设备上的文件。 由原生代码所写出,因此它记录的时间与跟踪运行的时间一样长,它能活下来的应用重启并重新出道.

await BackgroundGeolocation.start(
    {
        backgroundMessage: "Sharing your location.",
        locationLog: true
    },
    (location, error) => console.log(location, error)
);

// Later, when the app returns to the foreground or the network is back
const { entries } = await BackgroundGeolocation.getLocationLog();
if (entries.length > 0) {
    // Use the entries, for example upload them, then remove the ones that were read
    await BackgroundGeolocation.clearLocationLog({ upToId: entries[entries.length - 1].id });
}

每个条目都是 Location 带有 idID只向上,所以与 upToId 从不删除读取后到达的位置。 日志可维持 locationLogMaxEntries 地点,以及 limit 财务报告和审定财务报表 afterId 以页读取. 它从设备备份中被放出,所以在一个被恢复的设备上,它开始是空的,而ID又从1开始.

可选 SQLite 位置日志

默认构建将日志存储在滚动文件中,而不编译SQLite代码. 要选择 SQLite 后端( 每个条目的 POST 状态, 和 原 PR # 92 的 型号相同), 请设置为 capacitor.config 运行 npx cap sync数字 :

plugins: {
  BackgroundGeolocation: {
    locationLogSqlite: true
  }
}

那就通过 locationLogSqlite: true 内 start() 合并 locationLog: true。如果您请求 locationLogSqlite 不让它进入 capacitor.config, (中文(简体) ), start() 以明显的错误拒绝.

在iOS上, npx cap sync 切换可选选项 ios/SqliteLocationLog 并添加这些源加 sqlite3 目标 Package.swift (默认退出不编译或链接 SQLite). 在Android上,同步集 backgroundGeolocation.locationLogSqlite.include 内 android/gradle.properties。 。 。 .

要确认默认依赖性图不包括 SQLite : cd android && ./gradlew :dependencies --configuration releaseCompileClasspath (无) sqliteEnabled 来源)和在 Package.swift 编号 : CapgoBackgroundGeolocation.podspec sQLite 线条在同步启用前会保留注释 .

文档

这里有最完整的医生: https://capgo.app/docs/plugins/背地-地心定位/

兼容性

说明: 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

然后使用下列提示:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/background-geolocation` plugin in my project.

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

此插件支持 Capacitor v8 :

bun add @capgo/background-geolocation
bunx cap update

iOS系统

添加以下密钥到 Info.plist.数字 :

<dict>
  ...
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>We need to track your location</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>We need to track your location while your device is locked.</string>
  <key>UIBackgroundModes</key>
  <array>
    <string>location</string>
  </array>
  ...
</dict>

机器人

设置 android.useLegacyBridge 选项到 true 在您的电容配置中。 这样可以防止位置更新在背景5分钟后停止. 见 https://capcorjs.com/docs/config (中文(简体) ) 财务报告和审定财务报表 https://github.com/concessor-community/background-geolocation/issues/89 互联网档案馆的存檔,存档日期2013-12-02。 。 。 .

在Android 13+上,应用程序需要 POST_NOTIFICATIONS 运行时允许显示持续通知,告知用户其位置正在背景中使用。 此运行时间许可是在位置许可获得后请求的.

对于Android 10+上的背景地平面,应用程序也需要 ACCESS_BACKGROUND_LOCATION 财务报告和审定财务报表 backgroundLocation: true 内 setupGeofencing()。Android可能要求用户在授予前景位置后从系统设置中批准;使用 openSettings() 如果拒绝批准。 离开 backgroundLocation 未设置或 false 如果您的应用程序没有获得Android背景位置的 Google Play 批准 .

如果您的应用程序实时向服务器转发位置更新, 请注意在背景 Android 5分钟后, 从 WebView 启动的 HTTP 请求将会被节制 。 解决方案是使用本地的 HTTP 插件, 如 电容Http。见 https://github.com/concessor-community/后地地-地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地取地。 。 。 .

Android 的特定配置可以在 strings.xml数字 :

<resources>
    <!--
        The channel name for the background notification. This will be visible
        when the user presses & holds the notification. It defaults to
        "Background Tracking".
    -->
    <string name="capacitor_background_geolocation_notification_channel_name">
        Background Tracking
    </string>

    <!--
        The icon to use for the background notification. Note the absence of a
        leading "@". It defaults to "mipmap/ic_launcher", the app's launch icon.

        If a raster image is used to generate the icon (as opposed to a vector
        image), it must have a transparent background. To make sure your image
        is compatible, select "Notification Icons" as the Icon Type when
        creating the image asset in Android Studio.

        An incompatible image asset will cause the notification to misbehave in
        a few telling ways, even if the icon appears correctly:

          - The notification may be dismissable by the user when it should not
            be.
          - Tapping the notification may open the settings, not the app.
          - The notification text may be incorrect.
    -->
    <string name="capacitor_background_geolocation_notification_icon">
        drawable/ic_tracking
    </string>

    <!--
        The color of the notification as a string parseable by
        android.graphics.Color.parseColor. Optional.
    -->
    <string name="capacitor_background_geolocation_notification_color">
        yellow
    </string>
</resources>

API 密码

• start(...)
• stop()
• updateHeaders(...)
• openSettings()
• setPlannedRoute(...)
• setupGeofencing(...)
• addGeofence(...)
• removeGeofence(...)
• removeAllGeofences()
• getMonitoredGeofences()
• getLocationLog(...)
• clearLocationLog(...)
• addListener('geofenceTransition', ...)
• addListener('geofenceError', ...)
• checkPermissions()
• requestPermissions(...)
• getPluginVersion()
• 接口
• 类型异名

背景地理定位功能的主要插件接口. 提供管理位置更新和访问设备设置的方法.

启动(...)

start(options: StartOptions, callback: (position?: Location | undefined, error?: CallbackError | undefined) => void) => Promise<void>

要开始监听设备位置的变化,请使用这种方法. 一个承诺被退回 表示它完成了电话。 每次新地点都会呼叫回调 ,或如果调用此方法时出错。 不要依赖承诺拒绝这一点.

自: 7.0.9 联合国

停止( )

stop() => Promise<void>

停止位置更新 .

自: 7.0.9 联合国

更新页眉(...)

updateHeaders(options: UpdateHeadersOptions) => Promise<void>

替换本地 POST 使用的 HTTP 头头而不重新启动跟踪 .

当访问符过期时使用此选项 url 正在发送. 信头适用于运行中的位置监视器和在 这些特性已配置 url。 。 。 .

自: 8.3.3 国家

打开设置( C)

openSettings() => Promise<void>

打开设备的位置设置页面. 用于引导用户启用位置服务或调整权限.

自: 7.0.0 (单位:千美元)

设置 PlannedRoute (...)

setPlannedRoute(options: SetPlannedRouteOptions) => Promise<void>

当用户偏离计划路线时播放声音文件. 这应该用来演奏一个声音(在背景中也是,只用于本土).

自: 7.0.11 联合国

设置Geofencing(...)

setupGeofencing(options: GeofenceSetupOptions) => Promise<void>

配置本土地缘过渡处理.

当您需要默认的出/出设置时, 请在添加地理栅栏前先调用此选项 或本地背景 POST 。 安卓背景 POST 需要 backgroundLocation: true。 。 。 .

自: 8.0.30 联合国

添加Geofence(...) 语句

addGeofence(options: AddGeofenceOptions) => Promise<void>

开始监测圆形本土地缘.

自: 8.0.30 联合国

删除 Geofence (...)

removeGeofence(options: RemoveGeofenceOptions) => Promise<void>

停止监视一个地峡.

自: 8.0.30 联合国

删除全部邮件( )

removeAllGeofences() => Promise<void>

停止监视此插件注册的每一个地缘 .

自: 8.0.30 联合国

获得监测

getMonitoredGeofences() => Promise<MonitoredGeofencesResult>

列出此插件目前监控的地缘识别符 .

回返情况: Promise<MonitoredGeofencesResult>

自: 8.0.30 联合国

获取LocationLog(...)

getLocationLog(options?: GetLocationLogOptions | undefined) => Promise<LocationLogResult>

读取由 QQlink 保存的位置 启动选项. locationLog,无论或 没有跟踪正在运行 。 网络上没有任何东西 所以结果是 那边是空的.

回返情况: Promise<LocationLogResult>

自: 8.5.0 (中文(简体) )

清除LocationLog(...)

clearLocationLog(options?: ClearLocationLogOptions | undefined) => Promise<void>

从位置日志中删除条目, 例如当它们已经存在时 读取或上传.

自: 8.5.0 (中文(简体) )

添加倾听器( “ geofence Transition ” ,...)

addListener(eventName: 'geofenceTransition', listenerFunc: (event: GeofenceTransitionEvent) => void) => Promise<PluginListenerHandle>

在WebView活着时聆听地峡的入出过渡.

土著 url 通过配置 setupGeofencing 用于 提供背景安全服务.

回返情况: Promise<PluginListenerHandle>

自: 8.0.30 联合国

添加倾听器( 'geofence Error', ...)

addListener(eventName: 'geofenceError', listenerFunc: (event: GeofenceErrorEvent) => void) => Promise<PluginListenerHandle>

在WebView活着时监听原生地缘栅监测出错.

回返情况: Promise<PluginListenerHandle>

自: 8.0.30 联合国

检查( )

checkPermissions() => Promise<BackgroundGeolocationPermissionStatus>

在不提示或副作用的情况下读取当前位置授权 .

IOS 地图 CLAuthorizationStatus 这样你就可以永远区分 在使用App. On Android时,报告前景位置, ACCESS_BACKGROUND_LOCATION,以及相关情况下的通知许可.

回返情况: Promise<BackgroundGeolocationPermissionStatus>

自: 8.0.43 (中文(简体) )

请求(...)

requestPermissions(options?: RequestBackgroundGeolocationPermissionsOptions | undefined) => Promise<BackgroundGeolocationPermissionStatus>

向用户请求与位置相关的权限.

Ưμ㼯A 设置屏幕中的状态。 只有在用户选择加入时才调用 .

回返情况: Promise<BackgroundGeolocationPermissionStatus>

自: 8.0.43 (中文(简体) )

获取 PluginVersion ()

getPluginVersion() => Promise<{ version: string; }>

获取本地 Capacitor 插件版本

回返情况: Promise<{ version: string; }>

接口

开始选项

位置更新配置的选项 .

地点

代表具有各种属性的地理位置. 包含GPS/网络提供者返回的所有标准位置属性.

回拨错误

可能传递到位置开始召回的错误对象 . 以可选错误代码扩展标准出错.

更新标题选项

QQlink 背景Geogination Plugin.updateheaders 的选项 .

设定已规划的路由选项

地栅设置选项

配置本土地缘花序过渡处理选项.

何时 url 提供,本地代码可以发送 JSON POST 任何时候 被监测区域进入或退出。 Android背景 POST 传送 需求 backgroundLocation: true。 。 。 .

添加

圆形地缘区域.

删除选择

清除受监测地缘的备选办法.

监测到的地理成果

列入监测到的地峡时返回结果.

地点日志

由 QQlink 背景Geographic Plugin. getLocationLog 返回结果 .

位置日志条目

位置日志中保存的地址 .

访问日志选项

链接背景GeoginPlugin.getLocationLog 的选项 .

清除日志选项

QQlink 背景定位 Plugin. ClearLocationLog 的选项 .

| Prop Prop 型 | 说明