简介《腾讯地图定位》资源是一套完整的Android定位项目工程面向需要接入地图与位置服务的移动端开发者解决从SDK初始化、动态权限申请到定位结果展示的全流程问题。工程基于腾讯位置服务SDK编写包含清晰的Java源码、XML界面与AndroidManifest配置可帮助初学者掌握高精度、省电等定位模式的选择依据以及定位延迟、室内信号弱等常见问题的处理策略。压缩包共76个文件核心包含5个Java源码、16个class文件、16个XML布局与配置文件、6个jar依赖库、6个so架构库覆盖armeabi-v7a与x86另有19张png图标资源及可直接安装运行的apk安装包整体大小仅4.16MB目录结构整洁便于按资源类型检索学习。目前已有728人学习下载。对正在评估腾讯地图定位能力、或希望快速搭建可运行Demo的Android开发者而言这份资源提供了从源码阅读到安装验证的完整参照能显著缩短定位功能集成的前期摸索时间。1. 腾讯地图定位Android 定位这件事比你想的更依赖选型腾讯地图定位是我在多个 LBS 项目里反复对比后留下来的一套 Android 定位方案。它最大的价值不是“能拿到经纬度”——系统定位接口也能做到而是它在室内、高架桥下、Wi-Fi 信号杂乱这些糟糕环境里依然能通过基站、Wi-Fi、GPS 混合策略给出一个可用的结果冷启动速度也明显优于裸调系统接口。很多做轨迹上报、签到打卡、门店服务的开发者最初都在LocationManager和各厂商 SDK 之间反复横跳最后发现真正要解决的是“拿不到、拿得慢、拿得飘”这三个问题。这篇笔记就从接入准备讲起把初始化、单次与连续定位、参数选型、高频踩坑和进阶策略一次说透。2. 接入前的三件套Key 申请、运行时权限与清单配置2.1 定位 Key 的申请与校验链路腾讯地图定位 SDK 要求每个应用绑定一个独立 Key这个 Key 和应用包名、签名证书的 SHA1 是一一对应的。常见做法是在腾讯位置服务控制台创建应用填写 Android 包名和签名 SHA1生成 Key 后配置进工程。我第一次接入时偷懒直接复制了官方 Demo 里的 Key结果回调里永远是错误码。原因在于控制台校验的是应用签名官方 Demo 的 Key 只在官方签名下才能通过校验换到自己的包名和签名上必然失败。这个校验链路是独立于 Android 权限体系的就算你把所有权限都声明齐全Key 不对照样拿不到坐标。所以接入的第一步不是在 Android Studio 里写代码而是先去控制台把 Key 申请下来并且保存好签名信息。后续如果你切换了发布签名比如从 debug 签名换到 release 签名必须回控制台更新 SHA1否则线上版本会突然全部定位失败——这个坑我在 2.1.1 小节里还会展开讲。2.2 AndroidManifest 权限声明与版本适配定位权限是这套 SDK 能工作的前提。Android 6.0 之后权限分为安装时授权和运行时授权两类其中精确定位ACCESS_FINE_LOCATION和粗略定位ACCESS_COARSE_LOCATION属于危险权限必须在运行时动态申请。!-- AndroidManifest.xml -- uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / uses-permission android:nameandroid.permission.ACCESS_COARSE_LOCATION / uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / !-- Android 10 后台定位如不需要可去掉 -- uses-permission android:nameandroid.permission.ACCESS_BACKGROUND_LOCATION /清单文件里需要声明网络和 Wi-Fi 状态权限因为腾讯地图定位 SDK 的混合定位策略依赖网络请求基站信息和 Wi-Fi 指纹库。ACCESS_BACKGROUND_LOCATION是 Android 10API 29新增的权限如果你的应用需要在退到后台后继续上报位置比如轨迹记录类应用必须在清单里声明并且在运行时和前台权限分开申请。这里有一个容易忽略的点从 Android 11 开始系统对后台定位权限的申请策略变得更严格用户在授权弹窗里只能选择“仅在使用时允许”后台权限需要通过设置页引导开启。所以如果你做的是后台轨迹上报产品层面要提前设计引导流程不能只靠一个requestPermissions就指望拿到全部权限。2.3 工程依赖引入与运行时权限申请定位 SDK 的依赖坐标在腾讯位置服务官方文档里可以找到通常是一个com.tencent.map.geolocation开头的 Maven 坐标按官方文档替换成当前最新稳定版即可。// build.gradle (app) dependencies { // 版本号以腾讯位置服务控制台公布的当前稳定版为准 implementation com.tencent.map.geolocation:TencentLocationSdk-open:latest }引入依赖之后不要急着初始化先做一次运行时权限申请确认用户授权后再进入定位流程。下面这段代码处理了 Android 6.0 以上的运行时权限申请逻辑。// MainActivity.java private static final int REQ_LOCATION_PERMISSION 100; private void checkPermissionAndLocate() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.M) { // 精确定位和粗略定位一起申请注意后台定位权限需要单独处理 String[] permissions { Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION }; if (checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) ! PackageManager.PERMISSION_GRANTED) { requestPermissions(permissions, REQ_LOCATION_PERMISSION); return; } } startLocation(); } Override public void onRequestPermissionsResult(int requestCode, NonNull String[] permissions, NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode REQ_LOCATION_PERMISSION) { if (grantResults.length 0 grantResults[0] PackageManager.PERMISSION_GRANTED) { startLocation(); } else { // 拒绝后建议引导去设置页否则混合定位只能退化为基站级别 Toast.makeText(this, 定位权限被拒绝无法获取位置, Toast.LENGTH_SHORT).show(); } } }逻辑说明checkPermissionAndLocate里判断了系统版本Android 6.0 以下不需要运行时申请直接进入定位6.0 以上先检查再申请。onRequestPermissionsResult里拿到授权结果后才真正调用startLocation()。参数说明REQ_LOCATION_PERMISSION自定义请求码用来在回调里区分是哪一次权限请求的结果。注意ACCESS_FINE_LOCATION和ACCESS_COARSE_LOCATION必须放在同一个申请请求里因为这两个权限在系统里属于同一权限组一次弹窗就能全选。3. 从单次定位到连续定位核心 API 的使用与回调设计3.1 初始化定位会话与请求对象腾讯地图定位 SDK 的入口是TencentLocationManager它是单例整个应用生命周期里只需要获取一次。定位请求参数通过TencentLocationRequest对象配置每次调用定位都需要传一个配置好的实例。// LocationHelper.java public class LocationHelper { private TencentLocationManager locationManager; public LocationHelper(Context context) { locationManager TencentLocationManager.getInstance(context); // SDK 默认返回 GCJ-02 坐标系国内地图展示不需要额外转换 } public void startSingleLocation(TencentLocationListener listener) { // create() 会生成一份默认参数的请求对象 TencentLocationRequest request TencentLocationRequest.create(); // requestLevel 决定回调里附带多少逆地理编码信息详见第 4 章 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_NAME); // 单次定位不关心间隔设个默认值即可 request.setInterval(0); locationManager.requestLocationData(request, listener); } }逻辑说明TencentLocationManager.getInstance(context)拿到全局单例内部负责管理各种定位源。TencentLocationRequest.create()生成默认请求setRequestLevel配置返回的附加信息级别setInterval(0)表示不启用定时更新。参数说明REQUEST_LEVEL_NAME表示在经纬度之外额外返回街道、区县等名称信息。如果你的业务只需要坐标用REQUEST_LEVEL_GEO或对应最低级别可以减少一次逆地理编码请求定位速度更快、也省电。SDK 里具体常量名以源码注释为准含义分几个档位从纯经纬度到附带 POI 信息不等。3.2 单次定位回调、错误码与超时处理单次定位是签到、打卡、门店导航这类场景的核心需求。它的调用方式很直接但是回调不是同步返回的而是异步回调在TencentLocationListener.onLocationChanged里。// 单次定位请求示例 locationHelper.startSingleLocation(new TencentLocationListener() { Override public void onLocationChanged(TencentLocation location, int errorCode, String reason) { if (errorCode 0 location ! null) { double lat location.getLatitude(); double lng location.getLongitude(); float accuracy location.getAccuracy(); String provider location.getProvider(); // provider 通常返回 gps / network / cell用于判断定位来源 Log.d(Location, lat lat , lng lng , accuracy accuracy , provider provider); } else { // errorCode 非 0 表示定位失败reason 里有可读描述 Log.e(Location, locate failed: errorCode , reason); } } Override public void onStatusUpdate(String s, int i, String s1) { // GPS 状态变化回调一般用于展示卫星数量 } });逻辑说明onLocationChanged是核心回调errorCode 0才表示定位成功。成功时从TencentLocation对象里取经纬度、精度和定位来源失败时打印错误码和原因便于排查。onStatusUpdate是 GPS 模块状态变化通知业务上通常用不到。参数说明accuracy的单位是米数值越小代表定位精度越高。GPS 定位在城市开阔地带通常能到 5~20 米纯基站定位可能在 200~1000 米之间。如果你的业务对精度有要求回调里可以加一个阈值判断超过阈值就丢弃结果并重新发起定位。这里要特别提醒单次定位请求发出后如果长时间没有回调比如到了室内、GPS 被遮挡SDK 并不会自动超时需要业务侧自己加一个延时任务比如 10 秒内没拿到结果就提示用户“定位超时请移动到开阔区域”。否则用户会一直看到加载动画体验很差。我一般会在发起请求时同时启动一个CountDownTimer回调成功或失败时取消。3.3 连续定位更新频率、生命周期与停止时机连续定位常用于轨迹记录、实时配送、运动健康类应用。setInterval参数决定了相邻两次回调的最小时间间隔单位是毫秒。这里有个常见的理解误区设置 5000 并不意味着每 5 秒一定回调一次而是说两次回调的间隔不少于 5 秒具体回调时机还受定位源返回速度影响。// 连续定位每 5 秒一次回调 TencentLocationRequest request TencentLocationRequest.create(); request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_NAME); request.setInterval(5000); locationManager.requestLocationData(request, listener); // 页面销毁或不需要定位时必须及时停止 Override protected void onDestroy() { super.onDestroy(); locationManager.removeUpdates(listener); }逻辑说明requestLocationData在传入带setInterval的请求对象后SDK 会按设定的间隔周期性回调。removeUpdates用来停止连续定位必须在onDestroy、onStop等生命周期节点调用否则定位服务一直在后台运行电量消耗非常明显。参数说明interval的设置要结合业务场景。轨迹记录类应用骑行场景 3~5 秒比较合适步行场景 5~10 秒驾车场景还要考虑转弯点的采集密度一般建议 3 秒以内。间隔越大越省电但轨迹的平滑度会下降两条定位点之间直线距离可能超过几十米。此外连续定位开始后如果屏幕灭掉部分厂商系统会主动休眠导致回调中断这类问题通常需要结合前台服务或高德/腾讯的厂商辅助定位来规避。4. 参数选型定位级别、坐标系和场景模式如何匹配业务4.1 定位级别不是精度开关而是数据附带量开关很多初学者会把REQUEST_LEVEL_*理解成“精度档位”认为级别越高定位越准。实际上这个参数控制的是回调里附带的逆地理编码信息量——纯经纬度、街道名称、区县名称还是附近 POI 列表和定位精度完全无关。精度取决于当前环境的 GPS 信号强度和 Wi-Fi/基站指纹库的覆盖密度。// 不同业务场景的 requestLevel 选择 // 只需要坐标 时间: 用最低级别减少网络请求 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_GEO); // 需要显示街道名称的签到应用 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_NAME); // 需要区县、市级信息的统计类应用 request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_ADMIN_AREA);逻辑说明级别从低到高SDK 在拿到坐标后还会额外向逆地理编码服务发起一次请求把坐标翻译成可读地址。这对定位本身的耗时没有影响因为坐标是并行返回的地址信息随后跟上。但你要知道如果业务只需要坐标设成高级别等于白白多一次网络开销。参数说明选择级别的依据只有一个——你的业务在回调里需要展示什么。地图打点只需要经纬度签到打卡需要街道后台数据统计需要区县行政区划。不要为了“以防万一”设成 POI 级别那个数据量很大而且大部分字段根本用不到反而增加分析负担。4.2 GCJ-02 与 WGS-84坐标系选错的后果国内地图服务的坐标系基本都被加密偏移过腾讯地图定位 SDK 默认返回 GCJ-02火星坐标系这是国家测绘标准所有国内地图厂商的底图都基于这个坐标系。如果你的应用展示地图用的也是腾讯地图或高德地图直接使用默认坐标系即可地图打点位置是准确对齐的。// 业务需要原始 GPS 坐标如涉外应用时显式切换坐标系 // TencentLocationManager 提供坐标类型切换方法 locationManager.setCoordinateType(TencentLocationManager.COORDINATE_TYPE_WGS_84);逻辑说明setCoordinateType在初始化后调用一次即可切换后所有定位回调里的经纬度都会按指定坐标系输出。默认值是 GCJ-02不调用任何方法就保持默认。参数说明COORDINATE_TYPE_WGS_84对应国际标准的 WGS-84 坐标系它是 GPS 芯片输出的原始坐标。这里最常踩的坑是业务方从定位 SDK 拿到 GCJ-02 坐标却直接传给使用 WGS-84 底图的海外地图组件导致点位偏移几百米。反过来把 WGS-84 坐标直接画在国内底图上也会出现明显的道路偏移。坐标系转换涉及火星坐标加密算法网上有大量转换公式但一定要搞清楚”底图用哪个坐标系”再动手坐标系选错直接导致所有点位飘移。4.3 场景模式与请求间隔省电和时效性的平衡定位间隔和定位模式是定位耗电的最大变量。下表整理了常见业务场景的推荐配置直接抄作业基本不会翻车。业务场景requestLevelinterval (ms)坐标系说明单次签到打卡NAME0GCJ-02只需要一次回调0 表示不循环骑行轨迹记录GEO3000~5000GCJ-02间隔太短轨迹细腻但费电步行导航/跑步GEO5000GCJ-025 秒完全够用省电效果明显驾车轨迹上报GEO2000~3000GCJ-02高速场景间隔太大会丢弯道点后台统计/巡检ADMIN_AREA10000GCJ-02低频采样关注行政区域即可参数说明interval 0只适用于单次定位场景调用一次只返回一次结果。连续定位场景如果设置 0SDK 可能以最快速度连续回调这在大多数业务里不是你要的效果反而会在短时间内消耗大量电量。还有一个值得注意的点腾讯地图定位 SDK 的混合定位本身会同时启用 GPS 和网络定位但在 GPS 信号弱的环境下SDK 会自动退化为基站/Wi-Fi 定位。这个退化过程是黑匣子不对外暴露详细状态你能看到的就是location.getProvider()返回值变了。如果 provider 从 gps 变成 network说明当前环境信号差UI 上可以提示用户移动位置但不要在这个节点反复重启定位请求那样只会让耗电加倍。5. 腾讯地图定位避坑五个高频问题的排查记录5.1 Key 校验失败回调一直返回错误码现象定位回调始终返回非 0 错误码reason 里提示 key 错误或鉴权失败权限已经全部授予网络也正常。原因控制台配置的包名或 SHA1 与实际应用不一致。常见于过了几天后重新生成了签名文件或者在测试机和发布包之间切换了签名配置。另一个可能原因是 Key 在 Manifest 里配置不对某些版本的 SDK 会从meta-data标签里读 Key标签名写错也会触发同样的错误。解决先用keytool -list -v -keystore your.keystore导出当前签名的 SHA1与控制台配置逐字符对比重点检查字母大小写和冒号分隔格式。然后在 Manifest 中确认 Key 配置的meta-data名称和 SDK 要求的完全一致。如果你用的是自动打包方案不同渠道签名不同也要确保每个渠道包的 Key 都单独申请过。5.2 Android 10 后台定位失效现象应用退到后台 1~2 分钟后定位回调彻底停止回到前台又恢复。原因Android 10 引入了ACCESS_BACKGROUND_LOCATION后台定位权限且它的授权方式必须单独申请普通权限弹窗无法覆盖。部分厂商系统还会在国内 ROM 上额外加一层“禁止后台定位”的开关即使你申请了权限用户没有在设置里放开也是白搭。解决在 Android 10 以上的版本除了申请前台定位权限还要申请后台定位权限。申请时机建议在用户进入轨迹记录功能时通过引导文案让用户去设置页开启后台定位权限。同时要检测厂商系统设置里的“自启动”和“后台限制”这两项在国内 ROM 上是独立于标准权限体系的系统不会弹窗询问只能引导用户手动修改。5.3 模拟器里永远拿不到定位结果现象在 Android 模拟器里运行项目定位回调一直超时或者报错换成真机就正常。原因模拟器没有真实的 GPS 模块也没有真实的基站和 Wi-Fi 指纹数据腾讯地图定位 SDK 的混合定位策略在模拟器里基本是废的。这不是代码问题也不是 Key 问题。解决开发阶段用adb shell给模拟器注入一个模拟位置源或者在模拟器的扩展设置里手动指定经纬度。但注意SDK 内部可能对模拟位置源做了检测某些版本会拒绝返回模拟位置。最稳妥的做法是定位相关功能直接在真机上调试测试时到室外开阔区域验证 GPS 表现室内验证 Wi-Fi/基站定位表现。模拟器只适合调试 UI 逻辑不适合验证定位链路。5.4 混淆构建后定位回调不触发现象debug 包定位正常release 包开了 minifyEnabled装上之后Key 没有报错权限也正常但定位回调就是不触发。原因混淆规则把定位 SDK 里的类名或方法名重写了SDK 内部通过反射拿到回调类被混淆后反射失败回调链路就断了。SDK 官方一般会提供混淆配置但很多项目组接入时没有把官方 proguard 规则完整贴进去。解决在proguard-rules.pro里加入定位 SDK 的 keep 规则至少需要保留 SDK 的根包路径。以下是一份保底配置。# proguard-rules.pro # 保留定位 SDK 的所有类 -keep class com.tencent.map.geolocation.** { *; } -keepattributes Signature -keepattributes *Annotation* -dontwarn com.tencent.map.geolocation.**逻辑说明-keep class强制保留指定包路径下所有类不被混淆-keepattributes保留注解和签名信息-dontwarn抑制缺失类警告。具体包名以官方混淆文档为准如果你接的版本包名有变化按实际源码包路径替换但保底思路是一样的。参数说明这里面最核心的是第一条{ *; }表示保留所有成员包括内部类。如果你的项目还用了 R8 全量优化建议把com.tencent.map.geolocation.**同时加入consumer-rules里避免库模块被二次裁剪。5.5 定位跳点与精度漂移现象连续定位过程中坐标点偶尔跳到几百米外画出来的轨迹出现明显的“飞点”。原因定位源切换时带来的精度回退比如从 GPS 平滑过渡到 Wi-Fi 定位的瞬间基站定位给出的初始点误差可能很大。此外城市峡谷环境高楼密集区会引入多径效应GPS 信号反射后计算出的坐标本身就偏了。解决在回调里加精度阈值过滤accuracy大于某个值的丢弃等下一次有效回调。同时利用 SDK 返回的时间戳和上一有效点做速度校验如果两点之间的距离除以时间间隔超过了合理速度比如步行应用超过 6km/h判定为飞点并丢弃或做平滑处理。我一般在定位回调里串联一个 3 点滑动滤波取中间点作为绘制坐标轨迹稳定性会明显改善。6. 把定位体验做扎实缓存优先、省电策略与精度校验定位 SDK 本身只负责给你坐标但用户感知到的“定位体验好不好”取决于你在 SDK 之上怎么设计。这里分享三个我每个项目都用的固定套路。第一个是缓存优先。冷启动进入应用时定位往往需要 1~3 秒才能回调这段时间地图上如果什么都没有用户会觉得“卡”。我一般会把上次定位成功的坐标存入本地启动时先用缓存坐标渲染界面再异步发起新的定位请求回调成功且精度更好时再刷新地图。// 启动时先用缓存撑住 UI再异步刷新 LocationCache cache LocationCache.getInstance(this); TencentLocation last cache.getLastLocation(); if (last ! null) { updateMap(last); // 先用上一次的坐标渲染 } locationHelper.startSingleLocation(new TencentLocationListener() { Override public void onLocationChanged(TencentLocation location, int errorCode, String reason) { if (errorCode 0 location ! null location.getAccuracy() 80) { cache.save(location); // 只有高精度结果才覆盖缓存 updateMap(location); // 新坐标到位刷新地图 } } // onStatusUpdate 省略 });逻辑说明LocationCache是业务侧自建的存储类内部用 SharedPreferences 保存经纬度、精度和时间戳。这里的关键设计有两个一是缓存坐标必须带上时间戳超过 10 分钟就不能再用了否则用户可能看到了一个“昨天的位置”二是只有精度小于 80 米的结果才写入缓存避免把飞点存下来污染下次启动。第二个是省电策略。连续定位的interval按业务场景已经做了区分但还有一个容易被忽略的点——屏幕熄灭时主动降低定位频率或者干脆停止定位等应用回到前台再恢复。我接轨迹类项目时会注册一个ScreenBroadcastReceiver系统灭屏就调removeUpdates点亮屏幕再重新发起定位。这种实现方式既能保住轨迹的大体完整又能把夜间待机耗电降一个量级。第三个是精度校验的统一封装。不要在业务层到处写if (accuracy 80)这种散装逻辑而是把校验收敛到定位管理器里提供一个onResult的包裹回调把精度过滤、飞点判断、时间戳校验都在这一层做掉上层拿到的一定是干净坐标。这样以后要调整阈值改一处就够了。这套组合是我从早期项目里一路踩出来的。最早我在一个巡检模拟项目里直接用原始回调用户走完一整条街轨迹却是一条断裂的折线——飞点、缓存过期、后台停止全遇到了。从那以后我每次接入定位 SDK 都强制先写一个最小验证工程确认 Key、权限、回调链路通了再开始业务代码然后每接一个新业务场景先把定位级别、间隔、缓存策略这三件事定下来再写 UI。这个习惯救了我很多次希望帮到你。本文还有配套的精品资源点击获取
