# 位置服务使用指南

## 一、使用前须知

多端应用中地图与位置服务相关 JSAPI 能力，如 `Map 组件`、`wx.openLocation` 等 location 相关接口能力，是基于[腾讯位置服务](https://lbs.qq.com/)服务实现，开发者需前往腾讯位置服务控制台注册开发者账号，并创建对应以获取 LBS SDK 所需的 Key。为方便开发者更好地理解整体逻辑，需认真阅读本章节的内容：

- 首先，前往[腾讯位置服务](https://lbs.qq.com/)控制台注册开发者账号，并创建应用以获取 LBS SDK 所需的 Key
- 然后，在开发者工具中配置启用「LBS SDK」，并填入对应 Key
- 最后，在 JS 代码侧使用调用 location 相关 JSAPI
- 此服务是腾讯位置服务的服务，个人开发者、企业开发者、商业授权开发者初始额度不同，如果需更高的额度则需付费提额，详情可查看[配额限制说明](https://lbs.qq.com/dev/console/quotaImprove)
- 以及，如需商业化授权可查看详情[腾讯位置服务商业化服务](https://lbs.qq.com/dev/console/authorization)

### 1、关于 SDK 版本要求

- iOS SDK：需使用版本号 ≥ 1.0.14
- Android SDK：需使用版本号 ≥ 1.0.7
- HarmonyOS SDK：需使用版本号 ≥ 0.5.9

**补充**：Android core sdk 选择 1.2.0 及以上，Android 对应的 lbs sdk 也要选 1.2.0 及以上，否则构建会失败的。

### 2、关于合规指南

根据监管部门要求，使用 SDK 时必须在《隐私政策》中告知终端用户 SDK 使用用途，并且在终端用户未同意《隐私政策》前不得初始化任何 SDK。请确保你开发或运营的应用有符合监管要求的《隐私政策》文本。同时请你务必明确告知终端用户你的应用使用了腾讯位置服务。

- [Android LBS SDK 合规指南](https://lbs.qq.com/mobile/androidLocationSDK/androidLBSInfo)
- [iOS LBS SDK 合规指南](https://lbs.qq.com/complianceGuides/guides/sdkGuides/positionSdkComplianceGuide)

### 3、位置服务 API 海外接口购买指南

- 如需在海外使用位置服务能力，则需前往腾讯云官网购买流量包，购买地址：[https://buy.cloud.tencent.com/overseas_pv_package](https://buy.cloud.tencent.com/overseas_pv_package)
- 按实际情况选择接口

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F20250826131331841.png)

- 填写 key

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F20250826131441259.png)

### 4、JSAPI 列表

LBS SDK，包括地图、定位、罗盘、加速计和设备方向等能力；其中地图和定位能力需配置腾讯位置服务 Key，相关的 JSAPI 列表如下（下面接口 Android 和 iOS 端）：

| 名称 | 功能说明 | 鸿蒙端支持情况 |
| -- | -- |-- |
| [wx.stopLocationUpdate](/miniprogram/dev/api/location/wx.stopLocationUpdate.md)  | 关闭监听实时位置变化，前后台都停止消息接收 |支持|
| [wx.startLocationUpdateBackground](/miniprogram/dev/api/location/wx.startLocationUpdateBackground.md)  | 开启小程序进入前后台时均接收位置消息，需引导用户开启[授权](/miniprogram/dev/framework/open-ability/authorize.md) |支持|
| [wx.startLocationUpdate](/miniprogram/dev/api/location/wx.startLocationUpdate.md)  | 开启小程序进入前台时接收位置消息 |支持|
| [wx.openLocation](/miniprogram/dev/api/location/wx.openLocation.md)  | 使用微信内置地图查看位置 |支持|
| [wx.onLocationChangeError](/miniprogram/dev/api/location/wx.onLocationChangeError.md)  | 监听持续定位接口返回失败时触发 |支持|
| [wx.onLocationChange](/miniprogram/dev/api/location/wx.onLocationChange.md)  | 监听实时地理位置变化事件，需结合 wx.startLocationUpdateBackground、wx.startLocationUpdate 使用 |支持|
| [wx.offLocationChangeError](/miniprogram/dev/api/location/wx.offLocationChangeError.md)  | 移除持续定位接口返回失败时触发 |支持|
| [wx.offLocationChange](/miniprogram/dev/api/location/wx.offLocationChange.md)  | 移除实时地理位置变化事件的监听函数 |支持|
| [wx.getLocation](/miniprogram/dev/api/location/wx.getLocation.md)  | 获取当前的地理位置、速度 |支持|
| [wx.chooseLocation](/miniprogram/dev/api/location/wx.chooseLocation.md)  | 打开地图选择位置 |尚未支持|

**注意事项**

- 使用该能力，构建 IPA 时不可选择「临时签名」，必须选择「证书签名」

**补充说明**

- wx.chooseLocation 涉及在腾讯位置服务的相关接口为：逆地址解析（/ws/geocoder/v1/?location=）、关键词提示（/ws/place/v1/suggestion）、周边推荐（/ws/place/v1/explore）

## 二、操作指南

本章节的操作指南仅包含开发者工具上的操作，更多关于[腾讯位置服务](https://lbs.qq.com/)控制台操作可前往其官网进行查看相关指引

### 1、申请 LBS SDK Key

腾讯位置服务控制台注册开发者账号，并创建对应以获取 LBS SDK 所需的 Key

- 创建应用，填写应用名称以及应用类型
![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190023659.png)
- 添加 Key
![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190024436.png)
- 需同时勾选「WebServiceAPI」和「SDK」，但是「域名白名单」里面的内容不要填写
![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190026254.png)
- 点击「添加」即可创建成功，并可查看配额信息
![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190028535.png)
- 前往「我的应用」即可查看 LBS SDK 所需的 Key
![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190032202.png)
- 补充说明：认证为企业开发者可获得更高配额，详情可前往「腾讯位置服务控制台 - 配额管理」进行查看
![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190031202.png)

### 2、启用 LBS SDK 并配置 Key

- 前往微信开发者工具，打开 `project.miniapp.json` 并进入扩展 SDK 配置，并启用 LBS SDK 以及填写 qmapAPIKey

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190034519.png)

- qmapAPIKey 即为步骤 1 中获取的腾讯位置服务 Key
- 其他说明：iOS 以及鸿蒙则无需选择 SDK 版本，只需配置 qmapAPIKey 即可
- iOS 端配置 qmapAPIKey 方法如下

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307190037292.png)

- 鸿蒙端配置 qmapAPIKey 方法如下（需切换到 json 模式，手动添加 qmapAPIKey）

![](https://res8.wxqcloud.qq.com.cn/wxdoc/7ae1a0c8-58b2-4cf7-bb37-27154ae03db2.png)

## 常见问题

### 1. iOS 中 wx.getLocation 没有回调？
请检查一下 project.miniapp.json 是否正确配置了 iOS 中地理位置相关的隐私信息访问许可描述，尤其是 `NSLocationWhenInUseUsageDescription`。
![Alt text](https://res.wx.qq.com/op_res/UGKPwKo146hS-g5J3xXVf_EfEzsu74ZOAo6jVrMXmUZ2Y89JuMfiGZByv50ibXtINv7_rocuz8mwXmikXhpBuw
)

### 2. wx.chooseLocation 打开的页面一直在 loading 中？
请检查问题 1 中的权限配置是否完成，再检查 qmapAPIKey 是否有「周边推荐（explore）」、「关键词输入提示」这两个接口的额度是否正常，如没有额度需要先申请额度，如额度已使用完请提升额度。