更新记录

1.0.1（2026-10-13）

• 新增 Android、iOS 地理围栏功能，支持圆形、多边形、POI、行政区围栏
• 新增后台围栏监控、事件回调、持久化恢复和示例页面

1.0.0（2025-11-17）

• 新版发布

平台兼容性

uni-app(4.66)

uni-app x(4.66)

其他

高德猎鹰轨迹、定位、后台定位、保活定位与地理围栏 SDK

开发文档

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS

特别提醒

• 购买本插件前，请先试用、并充分自测后再购买，购买后无法退款；
• 如有使用上的疑问、bug，可以进交流群联系作者；
• 结合文档和示例代码集成使用；
• 试用必须先打基座、试用必须先打基座、试用必须先打基座重要事情说三遍；
• 本插件支持uniapp/uniapp-x项目，支持vue2/vue3,支持iOS、Android
• Android手机型号太多，各品牌对手机的限制不尽相同，需要保活而进行的设置也不一样。随着Android系统的更新迭代，保活的难度也在不断加大。最有效的保活方式还是联系厂家添加白名单以实现进程保活。
• uniapp使用本插件保活、后台定位功能iOS需在manifest.json/其他设置中后台运行能力配置location
• android uniapp使用需设置targetSdkVersion >=29(在manifest.json->安卓/iOS常用其他设置)
• iOS/Android需更换appKey,更换位置见下面集成步骤
• 结合示例工程集成和试用 uniappx的示例工程在uniapp项目的static/GDTrackSample.zip。

插件功能

• 高德猎鹰轨迹采集、上传和查询
• 单次定位、连续定位、后台定位、保活定位
• 圆形、多边形、POI 和行政区地理围栏
• GCJ-02、WGS-84、BD-09 坐标转换
• 定位权限检查及应用设置页跳转

插件模块总览

业务侧统一使用下面的方式导入插件

import * as GDLocation from '@/uni_modules/yt-gdtrack'

各模块调用流程

1. 通用接入流程

1. 在高德控制台创建与 Android 包名/签名、iOS Bundle ID 匹配的 Key。
2. 将 Android Key 配置到 utssdk/app-android/AndroidManifest.xml，将 iOS Key 配置到 utssdk/app-ios/info.plist。
3. 在宿主应用展示隐私政策并取得用户同意。
4. 重新制作自定义基座或重新云打包。只修改原生配置后热刷新不会生效。
5. 在页面或业务模块中导入插件。
6. 根据需要调用基础配置，然后启动定位、轨迹或围栏模块。
7. 页面或业务任务结束时调用对应停止/销毁接口释放资源。

可选的全局基础配置：

GDLocation.configureBasicConfiguration({
    onceLocationTimeout: 5000,
    locationInterval: 10000,
    notificationTitle: 'App 后台定位',       // Android
    notificationContentText: '正在后台定位'  // Android
})

每次定位调用传入的同名参数优先于全局配置。locationInterval 小于 1000 毫秒时，插件会按 1000 毫秒处理。

2. 单次定位模块

功能：申请前台定位权限并获取一次位置；可选逆地理编码，不会启动长期前台服务。

调用流程：

1. 调用 onceLocation(options)。
2. 插件检查或申请前台定位权限。
3. Android 使用单次定位管理器，iOS 使用 AMapLocationManager 发起一次定位。
4. 插件将平台结果转换为统一的 LocationInfo。
5. 配置了 locationHandler 时返回兼容格式；配置了 locationResultBackcall 时返回结构化格式。两个回调同时配置时都会执行。
6. 单次定位完成或超时后，本次定位流程结束。

GDLocation.onceLocation({
    onceLocationTimeout: 8000,
    reGeocode: true,
    locationHandler: location => {
        if (location.code === 200) {
            console.log('定位成功', location)
        } else {
            console.log('定位失败', location.code, location.mes)
        }
    }
})

3. 连续定位模块

功能：按照时间间隔或 iOS 最小移动距离持续回调位置，适合页面实时定位、地图跟随等场景。

调用流程：

1. 调用 updateLocation(options) 或其同义接口 startUpdatingLocation(options)。
2. 插件根据 isAllow/enableBackgroundLocation 判断是否需要后台能力。
3. 插件完成权限检查并创建连续定位客户端。
4. 每次获得定位结果后，通过 locationHandler 和/或 locationResultBackcall 回调。
5. 业务结束时调用 stopUpdateLocation() 或 stopUpdatingLocation()。

distanceFilter 仅在 iOS 生效；设置后由移动距离控制回调，locationInterval 不再作为主要触发条件。Android 使用 locationInterval 控制定位间隔。

4. 保活定位模块

功能：在用户明确开启后台任务后，尽量保证设备息屏或 App 退到后台时仍能持续定位。

推荐调用流程：

1. 用户在可见页面点击“开始后台定位”。
2. 调用 keepLive(options) 或同义接口 keepLiveLocation(options)。
3. Android 申请前台定位和通知相关权限，随后启动 location 类型前台服务及常驻通知；iOS 开启允许后台更新的连续定位。
4. 定位结果持续通过回调返回。
5. 任务结束时调用 stopKeepLive() 或 offKeepLiveLocation()。

Android 保活实现还会使用广播、唤醒锁及定时恢复机制，但这不代表进程绝对不会被系统或厂商策略终止。Android 12 及以上应在 App 前台启动前台服务，不能依赖后台广播首次启动服务。

5. 猎鹰轨迹模块

功能：将设备位置按采集周期记录、按上报周期上传至高德猎鹰服务，并提供终端、轨迹、最新位置、历史轨迹及里程查询。

5.1 前置关系

• serviceID：在高德猎鹰 REST API 中创建服务后获得，不是 Key。
• tid：终端 ID，可通过 queryTerminal 查询，终端不存在时通过 addTerminal 创建。
• trid：轨迹 ID，可通过 addTrack 创建。传 -1 表示不绑定指定轨迹，沿用散点或当前轨迹行为。

5.2 推荐完整流程

1. 调用 initTrack(serviceID, handler)，统一接收所有猎鹰异步结果。
2. 调用 queryTerminal(serviceID, terminalName) 查询终端。
3. 若 onQueryTerminalCallback 返回终端不存在，调用 addTerminal，从 onCreateTerminalCallback 取得 tid。
4. 如需按独立轨迹归档，调用 addTrack(serviceID, tid)，从 onAddTrackCallback 取得 trid。
5. 可选调用 setInterval、setLocalCacheMaxSize 配置采集参数。
6. 调用 startTrack(serviceID, tid, trid) 启动猎鹰轨迹服务。
7. 收到成功的 onStartTrackCallback 后调用 startGather()。如果提前调用，插件会排队并在轨迹服务启动成功后继续。
8. 收到 onStartGatherCallback 成功结果后，SDK 开始采集、缓存并上传轨迹点。
9. 结束任务时依次调用 stopGather()、stopTrack()。
10. 页面或业务不再使用猎鹰时调用 destroyTrackClient() 释放客户端。

GDLocation.initTrack(serviceID, result => {
    const type = result['callbackType']
    const success = result['isSuccess'] === true

    if (type === 'onStartTrackCallback' && success) {
        GDLocation.startGather()
    }
})

GDLocation.setInterval(2, 20)
GDLocation.setLocalCacheMaxSize(60)
GDLocation.startTrack(serviceID, tid, trid)

Android 开始采集时会启动猎鹰专用前台服务；iOS 会使用后台定位能力。插件停止轨迹时会优先停止采集，避免最后一批轨迹点尚未完成打包。

5.3 采集周期和上传周期要求

setInterval(gatherTimeInterval, packTimeInterval) 的两个参数单位都是秒：

• gatherTimeInterval：轨迹点采集周期，有效范围为 1～60 秒。
• packTimeInterval：轨迹点打包上传周期，有效范围为 5～3000 秒。
• 上传周期必须是采集周期的整数倍，即 packTimeInterval % gatherTimeInterval === 0。

// 正确：20 是 2 的 10 倍
GDLocation.setInterval(2, 20)

// 正确：60 是 5 的 12 倍
GDLocation.setInterval(5, 60)

// 错误：20 不是 3 的整数倍
// GDLocation.setInterval(3, 20)

如果不满足整数倍关系，高德 SDK 可能拒绝参数、通过 onParamErrorCallback 返回错误，或者无法按预期的周期打包上传。建议在调用前由业务层完成参数校验。

5.4 猎鹰回调类型

任何回调都应先判断 isSuccess，不能只根据 callbackType 认定操作成功。

6. 地理围栏模块

功能：监听设备进入、离开或在围栏内停留，支持圆形、多边形、关键字 POI、周边 POI 和行政区围栏。

调用流程：

1. 在 App 可见页面调用 initGeoFence(options)，注册统一事件回调并配置监听行为。
2. 插件检查精确定位权限。Android 后台模式会启动围栏专用前台服务；iOS 会申请或升级定位权限。
3. 收到 initialized 成功事件后即可确认管理器初始化完成。权限请求期间提交的 Android 围栏会暂存，客户端启动后继续创建。
4. 调用任意 add*GeoFence 接口创建围栏。
5. 必须等待 created 事件，并检查 isSuccess。一个 POI 请求可能创建多个 SDK 围栏，可通过 createdCount 查看数量。
6. 围栏状态变化后收到 statusChanged，其中 status 为 inside、outside 或 stayed。
7. 使用同一个 customId 调用暂停、恢复或删除接口。
8. 不再使用围栏时调用 removeAllGeoFences()；需要同时释放回调、广播和前台服务时调用 destroyGeoFence()。

Android 会保存已成功创建的围栏，并在围栏前台服务被系统重建时恢复；iOS 会在下次调用 initGeoFence() 时恢复。customId 必须由业务保证稳定且唯一。

7. 坐标转换模块

转换接口都是同步方法，不申请定位权限，也不会启动定位服务。入参顺序统一为 latitude, longitude，返回值包含 latitude 和 longitude。

高德定位和高德地理围栏使用 GCJ-02。把 GPS/WGS-84 坐标直接作为围栏坐标会产生位置偏移，应先调用 wgs84_gcj02。

8. 权限、设置与资源释放模块

页面隐藏不等于业务任务结束。需要跨页面运行的定位、轨迹或围栏任务不应在普通页面 onHide 中直接停止；应由业务任务的开始/结束状态统一管理。

特别提醒：

1 、猎鹰sdk不提供创建服务方法，服务(service id)的创建请参考猎鹰rest api接口，是Web服务类型的key，不是Web端(JS API)，高德地图官网申请Web服务API类型KEY

iOS错误码对照表 Android错误码对照表

2、引入插件import * as GDTrackUtil from '@/uni_modules/yt-gdtrack'

3、配置高德 Key。项目根目录下存在 uni_modules/yt-gdtrack 文件夹即表示插件已导入。

Android配置key步骤：uni_modules/yt-gdtrack/utssdk/app-android/AndroidManifest.xml文件中<meta-data android:name="com.amap.api.v2.apikey" android:value="换成自己的高德key" />

iOS配置key步骤：uni_modules/yt-gdtrack/utssdk/app-ios/info.plist中

<key>GDAPIKey</key>
<string>换成自己的高德key</string>

*4、替换完在需要的页面引入（import as GDTrackUtil from '@/uni_modules/yt-gdtrack' 这点很重要）插件再打自定义基座调试。**

1、引入插件

import * as GDTrackUtil from '@/uni_modules/yt-gdtrack'

示例代码：

<script>
    //猎鹰轨迹插件对象
    import * as GDTrackUtil from '@/uni_modules/yt-gdtrack'

    export default {
        data() {
        }
    }
</script>

2、初始化

GDTrackUtil.initTrack(serviceID, res => {})

示例代码：

GDTrackUtil.initTrack(this.serviceID, res => {
        //回调类型
                let callbackType = res["callbackType"]
        //是否成功isSuccess == false会有错误码 let errorCode = res["errorCode"]
                let isSuccess = res["isSuccess"]
                if (callbackType == "onStartTrackCallback") { //开启服务回调
                    console.log(callbackType + "开启服务回调")
                } else if (callbackType == "onStopTrackCallback") { //停止服务回调
                    console.log(callbackType + "停止服务回调")
                } else if (callbackType == "onStartGatherCallback") { //开始采集回调
                    console.log(callbackType + "开始采集回调")
                } else if (callbackType == "onStopGatherCallback") { //停止采集回调
                    console.log(callbackType + "停止采集回调")
                } else if (callbackType == "onCreateTerminalCallback") { //新增终端回调
                    console.log(callbackType + "新增终端回调")
                } else if (callbackType == "onAddTrackCallback") { //新增轨迹回调
                    console.log(callbackType + "新增轨迹回调")
                } else if (callbackType == "onDeleteTrackCallback") { //删除轨迹回调
                    console.log(callbackType + "删除轨迹回调")
                } else if (callbackType == "onQueryTerminalCallback") { //查询终端回调
                    console.log(callbackType + "查询终端回调")
                } else if (callbackType == "onLatestPointCallback") { //查询最新位置回调
                    console.log(callbackType + "查询最新位置回调")
                } else if (callbackType == "onQueryTrackCallback") { //查询历史轨迹回调
                    console.log(callbackType + "查询历史轨迹回调")
                } else if (callbackType == "onDistanceCallback") { //查询轨迹距离回调
                    console.log(callbackType + "查询轨迹距离回调")
                } else if (callbackType == "onHistoryTrackCallback") { //查询轨迹历史数据和行驶距离回调
                    console.log(callbackType + "查询轨迹历史数据和行驶距离回调")
                }
})

3、添加终端

GDTrackUtil.addTerminal(terminal : string, serviceID : number) 需先初始化,添加结果通过初始化回调返回："onCreateTerminalCallback"

示例代码：GDTrackUtil.addTerminal("新设备", 1053869)

4、开启轨迹服务

GDTrackUtil.startTrack(serviceID : number, tid : number, trid : number) 需先初始化,添加结果通过初始化回调返回："onStartTrackCallback"

Android、iOS 均会在 trid 有效（不等于 -1）时自动绑定到指定轨迹。旧代码仍可继续调用 setTrackId(trid)，该接口可用于启动服务后切换轨迹。

5、开始采集

GDTrackUtil.startGather() 需先初始化,添加结果通过初始化回调返回："onStartGatherCallback"

后台轨迹说明：

• Android 调用 startGather() 时会自动启动 location 类型前台服务，并显示“轨迹采集中”常驻通知，以支持息屏及 App 退到后台后继续采集、缓存和上传。
• Android 必须在 App 页面可见时启动轨迹；Android 12 及以上系统通常不允许普通后台状态直接创建前台服务。
• iOS 已启用 UIBackgroundModes/location，启动轨迹时会申请或升级后台定位权限。
• startGather() 如果早于轨迹服务启动成功，两端都会先保存请求，并在 onStartTrackCallback 成功后开始采集。
• 用户强制停止 App、关闭定位权限或设备厂商强制清理进程后，系统不保证继续采集。

6、停止采集

GDTrackUtil.stopGather() 需先初始化,添加结果通过初始化回调返回："onStopGatherCallback"

7、停止服务

GDTrackUtil.stopTrack() 需先初始化,添加结果通过初始化回调返回："onStopTrackCallback"

8、添加轨迹

addTrack(serviceID : number, tid : number) 添加结果通过初始化回调返回："onAddTrackCallback"

GDTrackUtil.addTrack(1053869, 1568147832)

9、设置采集和上报位置数据的时间间隔

GDTrackUtil.setInterval(gatherTimeInterval:number, packTimeInterval:number) 注意：上传周期必须为采集周期的整数倍

GDTrackUtil.setInterval(2, 20)

10、查询最新定位

GDTrackUtil.queryLatestPoint(serviceID : number, tid : number, trid : number) 添加结果通过初始化回调返回："onLatestPointCallback"

GDTrackUtil.queryLatestPoint(1053869, 1568147832, 19)

11、查询里程

GDTrackUtil.queryDistance(serviceID : number, tid : number, startTime : number, endTime : number, trid : number, correction : number, recoup : number, gap : number) 添加结果通过初始化回调返回："onDistanceCallback"

GDTrackUtil.queryDistance(1053869, 1568147832, 1761580800000, 1761620086000, 19, 0, 1, 50)

12、查询历史轨迹

GDTrackUtil.queryHistoryTrack(serviceID : number, tid : number, startTime : number, endTime : number) 添加结果通过初始化回调返回："onQueryTrackCallback"

GDTrackUtil.queryHistoryTrack(1053869, 1568147832, 1761580800000, 1761620086000)

13、查询终端下某轨迹的轨迹点

GDTrackUtil.queryTerminalTrack(serviceID : number, tid : number, trid : number, startTime : number, endTime : number) 添加结果通过初始化回调返回："onHistoryTrackCallback"

GDTrackUtil.queryTerminalTrack(1053869, 1568147832,19, 1761580800000, 1761620086000)

14、查询终端

GDTrackUtil.queryTerminal(serviceID : number, terminal : string) 查询结果通过初始化回调返回："onQueryTerminalCallback"

GDTrackUtil.queryTerminal(1053869, "小米手机")

15、设置轨迹（上报到指定轨迹）

GDTrackUtil.setTrackId(trid : number) 该方法只有在已经启动轨迹服务后才会生效

GDTrackUtil.setTrackId(19)

16、配置本地缓存大小

GDTrackUtil.setLocalCacheMaxSize(maxSize : number) 本地缓存最大值，单位MB，默认+∞，有效值范围[50,+∞)。

GDTrackUtil.setLocalCacheMaxSize(60)

高德定位/连续定位/坐标转换文档

特别提醒：

1、选择项目导入插件（试用/购买），项目根目录下存在 uni_modules/yt-gdtrack 文件夹即表示插件已导入。

2、配置高德 Key，并确认项目根目录下存在 uni_modules/yt-gdtrack 文件夹。

3、Android配置key步骤：uni_modules/yt-gdtrack/utssdk/app-android/AndroidManifest.xml文件中<meta-data android:name="com.amap.api.v2.apikey" android:value="换成自己的高德key" />

4、iOS配置key步骤：uni_modules/yt-gdtrack/utssdk/app-ios/info.plist中

<key>GDAPIKey</key>
<string>换成自己的高德key</string>

*4、替换完在需要的页面引入（import as GDTrackUtil from '@/uni_modules/yt-gdtrack' 这点很重要）插件再打自定义基座调试。**

1、引入插件

import * as GDLocation from '@/uni_modules/yt-gdtrack'

2、单次定位

GDLocation.onceLocation(options : LocationOptions) LocationOptions见下表说明

GDLocation.onceLocation({
        locationMode: 'HundredMeters',
        reGeocode: true,
        anLocationMode: "Hight_Accuracy",
        locationHandler: (location) => {
            if (location.code == 200) {
                console.log(location)
            }
        }
})

3、连续定位

GDLocation.updateLocation(options : LocationOptions) LocationOptions见下表说明

GDLocation.updateLocation({
        locationMode: 'HundredMeters',
        anLocationMode: "Hight_Accuracy",
        reGeocode: true,
        isAllow: false,
        locationInterval: 10000,
        locationHandler: (location) => {
            if (location.code == 200) {
                console.log(location)
            }
        }
})

4、停止连续定位

GDLocation.stopUpdateLocation()

5、保活定位

GDLocation.keepLive(options : LocationOptions) LocationOptions见下表说明

GDLocation.keepLive({
    locationMode: 'HundredMeters',
    reGeocode: true,
    isAllow: true,
    locationInterval: 5000,
    anLocationMode: "Battery_Saving",
    locationHandler: (location) => {
        if (location.code == 200) {
            console.log(location)
        }
    }
})

6、停止保活

GDLocation.stopKeepLive()

7、LocationOptions说明：

8、LocationInfo：说明

9、AddressInfo说明

10、打开设置页面

GDLocation.openAppSettings()

11、是否有定位权限

let value = GDLocation.hasLocationPermission() 返回值value == true ? "有定位权限" : "没有定位权限"

12、是否有后台定位能力

let value = GDLocation.hasBackgroundLocationPermission() value == true ? "有后台定位权限" : "没有后台定位权限"

13、坐标转换

//gcj02转wgs84
let result = GDLocation.gcj02ToWgs84(30.34524, 120.154624);
console.log(result)
//bd09转wgs84
let result = GDLocation.bd09ToWgs84(30.34524, 120.154624);
console.log(result)
//bd09转gcj02
let result = GDLocation.bd09ToGcj02(30.34524, 120.154624);
console.log(result)
//gcj02转bd09
let result = GDLocation.gcj02ToBd09(30.34524, 120.154624);
console.log(result)
//wgs84转gcj02
let result = GDLocation.wgs84_gcj02(30.34524, 120.154624);
console.log(result)
//wgs84转bd09
let result = GDLocation.wgs84ToBd09(30.34524, 120.154624);
console.log(result)

14、Android端修改通知图标

Android 修改通知栏图标时，请替换 uni_modules/yt-gdtrack/utssdk/app-android/res/drawable/notifi_icon.png。文件名必须保持为 notifi_icon.png，替换后需要重新制作自定义基座或重新打包才能生效。

15、地理围栏

地理围栏支持 Android 和 iOS，包含圆形、多边形、关键字 POI、周边 POI、行政区五种围栏。所有坐标必须使用高德 GCJ-02 坐标系。

import * as GDLocation from '@/uni_modules/yt-gdtrack'

// 初始化时默认开启后台围栏，并监听进入、离开、停留10分钟三种状态。
GDLocation.initGeoFence({
    enableBackground: true,
    actions: ['inside', 'outside', 'stayed'],
    notificationTitle: '地理围栏监控中', // 仅 Android
    notificationContentText: '正在后台检测围栏事件', // 仅 Android
    eventHandler: event => {
        console.log('围栏事件', event)
    }
})

GDLocation.addCircleGeoFence({
    customId: 'warehouse_1',
    center: { latitude: 30.34524, longitude: 120.154624 },
    radius: 300
})

其他新增接口：

GDLocation.addPolygonGeoFence({
    customId: 'polygon_1',
    points: [
        { latitude: 39.9100, longitude: 116.3950 },
        { latitude: 39.9100, longitude: 116.4000 },
        { latitude: 39.9060, longitude: 116.4000 }
    ]
})

GDLocation.addKeywordPOIGeoFence({
    customId: 'poi_1', keyword: '北京大学', poiType: '高等院校', city: '北京', size: 1
})

GDLocation.addAroundPOIGeoFence({
    customId: 'around_1',
    center: { latitude: 39.908692, longitude: 116.397477 },
    aroundRadius: 3000, keyword: '便利店', poiType: '060100', size: 3
})

GDLocation.addDistrictGeoFence({ customId: 'district_1', district: '海淀区' })

控制接口：

GDLocation.pauseGeoFence('warehouse_1')
GDLocation.resumeGeoFence('warehouse_1')
GDLocation.removeGeoFence('warehouse_1')
GDLocation.removeAllGeoFences()
GDLocation.destroyGeoFence() // 清空围栏并完全释放资源

事件说明：

后台说明：

• Android 默认启动独立的 location 类型前台服务和常驻通知；应在 App 页面可见时调用 initGeoFence()。Android 11+ 的“始终允许”建议开启，但不会阻止用户在前台启动围栏。
• iOS 默认设置 allowsBackgroundLocationUpdates = true，插件已配置 UIBackgroundModes/location，用户应授权“始终允许”和精确位置。
• Android 会持久化成功创建的围栏，在前台服务被系统重建时自动恢复；iOS 会在下次调用 initGeoFence() 时恢复。
• customId 应在业务中保持唯一。创建成功后 SDK 会自动开始检测，无需调用普通定位的 keepLive()。
• 用户强制停止应用、关闭定位权限或厂商强制清理进程后，系统不保证继续触发围栏。

常见问题

1. 配置了高德 Key，仍然提示鉴权失败或没有定位结果？

依次检查：

1. Android Key 绑定的包名、SHA1 与当前自定义基座或正式包是否一致。
2. iOS Key 绑定的 Bundle ID 是否与当前应用一致。
3. 修改 AndroidManifest.xml 或 info.plist 后是否重新制作了自定义基座/重新打包。
4. 宿主应用是否已展示隐私政策并取得同意，再开始调用插件能力。
5. 设备网络、系统定位总开关和应用定位权限是否正常。

2. 为什么真机有效，标准基座或热刷新无效？

本插件包含原生 SDK、原生配置、权限和 Service。新增插件、修改 Key、权限、通知图标或 info.plist 后，都必须重新制作自定义基座或重新打包；热刷新只能更新前端资源。

3. Android 已授予位置权限，为什么后台定位或地理围栏仍然失败？

前台位置权限、精确位置、后台位置和通知权限是不同能力：

• Android 12 及以上用户可能只授予“大致位置”，地理围栏需要“精确位置”。
• Android 11 及以上通常需要用户进入应用设置页手动选择“始终允许”。
• Android 13 及以上可能需要通知权限；即使通知权限被拒绝，系统仍可能以受限形式显示前台服务通知。
• 省电模式、自启动管理和厂商后台限制不属于 Android 标准权限，需要结合目标设备单独设置。

权限不足时可调用 openAppSettings() 引导用户处理，再返回 App 重试启动流程。

4. Android 调用保活定位、轨迹采集或后台围栏时提示不允许启动前台服务？

Android 12 及以上限制 App 在普通后台状态首次创建前台服务。应由用户在 App 可见页面点击按钮后调用 keepLive()、startGather() 或 initGeoFence()，不要在已进入后台的定时器、普通广播或无界面任务中首次启动。

5. iOS 切到后台后为什么定位停止？

检查以下项目：

• info.plist 是否包含 UIBackgroundModes/location。
• 用户是否授予“始终允许”定位，而不是仅“使用 App 期间”。
• 是否允许精确位置。
• 是否确实使用 keepLive()，或为连续定位设置了 isAllow: true/enableBackgroundLocation: true。
• 用户是否从多任务界面主动结束了 App。用户强制结束后，系统不会保证后台定位继续运行。

6. startGather() 调用了但没有开始上传轨迹？

确认调用顺序和回调结果：

1. 已调用 initTrack() 并保存统一回调。
2. serviceID、tid 有效，且 Key 有对应猎鹰服务权限。
3. startTrack() 的 onStartTrackCallback 返回成功。
4. startGather() 的 onStartGatherCallback 返回成功。
5. 设备定位和网络可用。

插件支持在轨迹服务启动完成前调用 startGather()，此时会暂存请求，但最终是否成功仍以 onStartGatherCallback 为准。

7. startTrack 的 trid 应该传什么？

• 需要把点归档到指定轨迹时，传 addTrack 或查询接口获得的有效 trid。
• 不指定轨迹时传 -1，插件不会覆盖当前轨迹绑定。
• 轨迹服务已经启动后需要切换轨迹，可调用 setTrackId(trid)。

8. 为什么轨迹点没有立即出现在平台？

setInterval(gatherTimeInterval, packTimeInterval) 中，第一个参数是采集周期，第二个参数是打包上传周期，两个参数的单位都是秒，且 packTimeInterval 必须是 gatherTimeInterval 的整数倍。位置会先采集和缓存，到达上传周期并且网络可用后再上传，因此平台展示通常晚于单次采集时间。弱网时 SDK 会使用本地缓存，网络恢复后再继续上报。

9. 为什么坐标或围栏位置有明显偏移？

高德定位及围栏使用 GCJ-02。GPS 原始坐标通常是 WGS-84，百度地图通常使用 BD-09。创建围栏或在高德地图展示前，应先转换为 GCJ-02，并确认传参顺序始终是纬度在前、经度在后。

10. 围栏创建后为什么没有状态事件？

先检查是否收到 created 且 isSuccess === true，再检查：

• 设备是否授予精确定位权限。
• customId 是否为空或与其他业务围栏冲突。
• 圆形半径、多边形点、POI 关键字或行政区名称是否有效。
• 测试设备是否真正跨越了围栏边界；一直在边界同一侧不会产生进入/离开变化。
• iOS 是否允许始终定位，Android 前台服务是否仍在运行。

11. 为什么重新打开 App 后旧围栏还在？

这是持久化恢复机制：Android 在前台服务被系统重建时恢复成功创建的围栏，iOS 在下次 initGeoFence() 时恢复。业务已经废弃围栏时应调用 removeGeoFence(customId)；需要全部清理时调用 removeAllGeoFences() 或 destroyGeoFence()。

12. 可以同时启动连续定位、保活定位、猎鹰轨迹和地理围栏吗？

技术上部分能力可以共存，但普通连续定位、保活定位和猎鹰轨迹都可能持续使用定位硬件。同时运行会增加耗电、发热和系统后台限制风险，也可能产生业务上重复的位置数据。建议一个业务场景只保留必要的持续定位链路。地理围栏由 SDK 动态调整定位频率，不需要额外调用 keepLive()。

13. 为什么 Android 设备锁屏或运行一段时间后仍被停止？

前台服务只能提高存活概率，不能对抗用户“强行停止”、系统资源回收或所有厂商的省电策略。对于专用设备，建议同时配置应用自启动、后台运行、电池不优化和任务锁定；最稳定的方式是由设备厂商加入系统白名单。

14. 回调错误后应该如何排查？

• 普通定位：记录 code、mes、权限状态和系统定位开关。
• 猎鹰轨迹：记录 callbackType、isSuccess、errorCode、errorMsg、serviceID、tid、trid。
• 地理围栏：记录 eventType、isSuccess、customId、fenceId、errorCode、errorMessage。
• 同时确认 App 版本、系统版本、机型、网络状态以及前后台状态，方便判断权限、参数、鉴权还是系统限制问题。

注意事项

1. 隐私合规：插件会向高德 SDK 同步“已展示并同意隐私政策”的状态。宿主应用必须在用户真实同意隐私政策之后再调用定位、轨迹或围栏接口，目前插件是默认同意。
2. 只支持 App 原生端：当前 package.json 声明支持 Android 5.0（API 21）及以上、iOS 12 及以上；不支持 Web、小程序和 HarmonyOS。
3. 必须使用自定义基座：插件包含原生依赖和平台配置，标准基座不能用于最终验证。
4. Key 必须匹配应用身份：Android 包名/SHA1、iOS Bundle ID 或高德服务权限不匹配都会导致鉴权失败。
5. 前台启动后台任务：Android 的保活定位、猎鹰采集和后台围栏应在页面可见、由用户操作触发时启动。
6. 权限需要分级处理：前台位置、精确位置、后台位置和通知权限不能视为同一个权限；用户拒绝后应给出原因并提供设置入口。
7. 采集和上传周期必须整倍数：猎鹰采集周期范围为 1～60 秒，上传周期范围为 5～3000 秒，并且上传周期必须是采集周期的整数倍，例如 setInterval(2, 20)。过短的周期还会明显增加耗电、流量和发热。
8. 正确停止任务：普通连续定位、保活定位、猎鹰轨迹和地理围栏使用不同资源，应调用对应停止接口。猎鹰建议按 stopGather() → stopTrack() → destroyTrackClient() 的顺序清理。
9. 不要重复启动：业务按钮应做防重复点击，避免多次注册回调或重复创建同一个任务。所有异步操作都以回调中的成功状态为准。
10. 围栏标识唯一：customId 用于暂停、恢复、删除和持久化匹配，同一业务范围内必须稳定且唯一。
11. 围栏坐标统一：圆形中心点、多边形顶点和周边 POI 中心点都必须使用 GCJ-02。
12. 时间参数单位：猎鹰查询接口的 startTime、endTime 使用毫秒时间戳；查询区间及结束时间必须满足高德接口限制。
13. 本地缓存不是永久存储：猎鹰弱网缓存用于恢复上传，不应替代业务数据库。卸载 App、清理数据或磁盘异常都可能导致缓存丢失。
14. 系统强制停止无法保活：用户强制停止 App、关闭定位、撤销权限或厂商清理进程后，插件无法保证继续定位、上传或触发围栏。
15. 使用真机验证：后台定位、系统权限、前台服务、围栏跨界和轨迹上传必须在目标真机上测试，并覆盖锁屏、弱网、断网恢复和系统重启场景。

插件文档

• uts插件试用文档