更新记录

1.0.0（2026-11-06） 下载此版本

• 提供同意隐私协议、SDK 初始化、快速单次定位、单次定位、前台连续定位、后台连续定位、停止定位。
• AppKey 在 initSdk 传入，再分别调用 Android setApiKey、iOS initKey、微信 setAk。
• Android、iOS 使用维智定位原生 SDK，微信小程序使用云端融合定位。
• 统一错误码 9010001–9010007。
• 支持打开 SDK 日志。Android 与微信小程序可把日志回调到 JS。

平台兼容性

uni-app(3.8.10)

维智定位 wz-location

uni-app UTS 插件，在 Android、iOS 上调用维智定位原生 SDK，在微信小程序上走云端融合定位。对外接口一致。

调用顺序：同意隐私协议 → SDK 初始化 → 定位或日志。定位结果通过 success 返回。连续定位会多次回调，用 stopLocation 停止。

平台兼容性

HBuilderX ^3.6.8，uni-app ^3.1.0。

安装

将 uni_modules/wz-location 拷入工程，或从插件市场导入。示例工程为同仓库的 wz_location_demo。

import {
  agreePrivacy,
  initSdk,
  getQuickLocation,
  getOnceLocation,
  startForegroundLocation,
  startBackgroundLocation,
  stopLocation,
  setLogEnabled,
  onSdkLog,
  offSdkLog
} from '@/uni_modules/wz-location'

配置

AppKey 只在 initSdk 传入。Android 调用 WzLocationClientOption.setApiKey，iOS 调用 initKey，微信小程序调用 setAk。三端 Key 可以不同，调用方式相同。

不要在 AndroidManifest 里再写 com.wayz.location.appkey。原生 SDK 会先读 Manifest，Manifest 里有值时会忽略 setApiKey。

Android

原生类为 com.wayz.location.*。标准基座没有该 SDK，请制作自定义调试基座后再运行到 Android。

插件已声明的权限：精确定位、粗略定位、读取手机状态、网络状态、Wi-Fi 状态、更改 Wi-Fi 状态、前台服务、后台定位。后台定位服务为 com.wayz.location.WzService。

iOS

宿主 manifest.json 的 iOS 配置中保留用途描述与后台模式：

• NSLocationWhenInUseUsageDescription：需要使用位置信息进行定位
• NSLocationAlwaysAndWhenInUseUsageDescription：需要使用位置信息进行后台定位
• UIBackgroundModes：location

interval 在接口层单位是毫秒，插件会换算成秒再传给 iOS SDK。

微信小程序

宿主 manifest.json → mp-weixin 需要：

• permission.scope.userLocation.desc：位置用途说明
• requiredPrivateInfos：getLocation、startLocationUpdate、startLocationUpdateBackground、onLocationChange
• requiredBackgroundModes：location（仅后台连续定位需要）
• 按微信要求开启隐私检查，并在小程序后台开通对应接口

连续定位间隔最小 2 秒。后台连续定位依赖 wx.startLocationUpdateBackground，未开通时失败信息为「微信未开通后台定位接口」。

快速使用

agreePrivacy({
  agree: true,
  success() {
    initSdk({
      appKey: '你的 AppKey',
      success() {
        getOnceLocation({
          success(res) {
            console.log(res.longitude, res.latitude, res.address)
          },
          fail(err) {
            console.log(err.errCode, err.errMsg)
          }
        })
      },
      fail(err) {
        console.log(err.errCode, err.errMsg)
      }
    })
  }
})

页面卸载时停止定位并取消日志回调：

stopLocation()
offSdkLog()

API

agreePrivacy(options)

告知 SDK 用户是否同意隐私协议。agree 为 false 时会取消已初始化状态，之后定位会失败。

成功文案：已同意隐私协议 / 未同意隐私协议。

initSdk(options)

未同意隐私协议时失败，错误码 9010005。未传 appKey 或传空字符串时失败，错误码 9010002，文案「未配置 Appkey」。Key 错误时初始化仍会成功，定位阶段返回 9010002。

写入方式：

• Android：WzLocationClientOption.setApiKey
• iOS：WzClientLocation.initKey
• 微信小程序：setAk，随后请求云端定位时沿用这把 Key

成功文案：SDK已初始化。

定位

interval 单位毫秒，默认 5000，小于等于 0 时按默认值。微信端实际间隔不会小于 2000 毫秒。

单次定位在成功或失败时都会调用 complete。连续定位只在每次成功时调用 success，不调用 complete；失败时调用 fail。

再次发起定位会停掉上一次。微信小程序上，单次定位尚未返回时再次点击单次定位会被忽略，不会进入 fail。

success 收到的位置对象：

日志

Android 会把原生日志转到 success。微信仅在日志开关打开且已注册回调时转发，level 为 0，tag 为 wz-location。iOS 的 setLogEnabled 会设置原生日志开关，onSdkLog 目前不向 JS 转发日志内容。

错误码

errSubject 为 wz-location。errMsg 在有 SDK 原文时使用原文，否则使用下表说明。

Android 10 及以上且 targetSdkVersion >= 29 时，后台定位才会申请 ACCESS_BACKGROUND_LOCATION，用户拒绝则返回 9010007。更低版本直接开始后台定位。iOS 未获得「始终允许」时，后台定位返回 9010007。

隐私与权限

集成方在对外隐私政策中需要说明：本插件用于定位，会在用户同意后读取位置信息；Android 还会读取手机状态、网络与 Wi-Fi 状态以辅助定位；微信小程序会使用设备标识请求云端定位。用户拒绝隐私协议或系统权限后，插件不会继续定位。

联系

集成与插件问题请发邮件至 haitao.zhang@wayz.ai。