场景定位

场景定位针对签到、运动、出行等典型业务场景，预设了定位策略配置。

开发者无需手动构造复杂的请求参数，直接指定场景即可获得最优的定位体验。

自定位 SDK v7.2.8 起，需通过 TencentLocationManager.setDeviceID 上传设备唯一标识，用于定位问题排查。

---

场景类型

场景	常量	定位方式	说明
签到场景	SIGN_IN_SCENE	单次定位	优先返回精度较高的结果，首次定位可能延迟 1~3 秒
出行场景	TRANSPORT_SCENE	连续定位	优先使用卫星定位结果，卫星信号断开后超时 8 秒才返回网络结果
运动场景	SPORT_SCENE	连续定位（惯导）	适用于步行或骑行，首次定位可能延迟 3~5 秒

场景内部配置

签到场景（SIGN_IN_SCENE）

通过 requestSingleFreshLocation 发起单次定位，TencentLocationRequest 参数预设如下：

Request 字段	值
locMode	HIGH_ACCURACY_MODE
allowGPS	true
gpsFirst	true
gpsFirstTimeOut	3000 ms
requestLevel	REQUEST_LEVEL_ADMIN_AREA
allowCache	true（默认）
allowDirection	false（默认）

出行场景（TRANSPORT_SCENE）

通过 requestLocationUpdates 发起连续定位，TencentLocationRequest 参数预设如下：

Request 字段	值
locMode	ONLY_GPS_MODE
allowGPS	true
interval	1000 ms
gpsFirst	false（默认）
requestLevel	REQUEST_LEVEL_NAME（默认）
allowCache	true（默认）
allowDirection	false（默认）

运动场景（SPORT_SCENE）

运动场景不通过 TencentLocationRequest 配置，而是直接启动 DR（惯导）引擎：

参数	值
DR 类型	DR_TYPE_WALK
回调间隔	1000 ms
GPS 超时	5000 ms（超时前仅返回非网络定位结果）

运动场景依赖步骑行惯导能力，需通过 isDrSupport() 判断设备是否支持。不支持时返回错误码 -1，DR so 库加载失败时返回 -7。

开发步骤

1. 获取 TencentLocationManager 实例

mLocationManager = TencentLocationManager.getInstance(this);

2. 发起场景定位请求

// mScenario 为场景常量：SIGN_IN_SCENE / TRANSPORT_SCENE / SPORT_SCENE
mLocationManager.requestLocationWithScene(mScenario, this);

回调在主线程 Looper 上执行。this 为 TencentLocationListener 实现类。

3. 停止定位

• 签到场景：无需停止，单次定位自动结束。
• 出行场景 / 运动场景：必须主动停止。

mLocationManager.stopLocationWithScene(mScenario, this);

返回值说明

• 签到场景 / 出行场景：返回值含义参见 错误码对照表。
• 运动场景：返回值含义参见 步骑行惯导错误码。

返回值	含义
0	启动成功
-1	设备不支持 DR 引擎（仅运动场景）
-7	DR so 库加载失败（仅运动场景）

注意事项

• 场景定位与连续定位/单次定位是独立的接口，无需额外调用 requestLocationUpdates 或 requestSingleFreshLocation。
• 运动场景需要设备支持 DR 引擎，可通过 isDrSupport() 提前判断。
• 出行场景使用仅 GPS 模式，卫星定位成功后不再返回网络定位结果；卫星信号丢失后等待超时才返回网络结果。

相关链接

• 步骑行惯导
• 错误码对照表
• API 参考手册