维智定位 Android 定位 SDK

发布于：2025-05-16 ⋅ 阅读:(26) ⋅ 点赞:(0)

概述

维智 Android 定位 SDK是为 Android 移动端应用提供的一套简单易用的定位服务接口，为广大开发者提供融合定位服务。通过使用维智定位SDK，开发者可以轻松为应用程序实现极速、智能、精准、高效的定位功能。

重要：为了进一步加强对最终用户个人信息的安全保护措施，从定位SDK v3.0.0版本起， 请开发者务必确保调用SDK任何接口前先调用隐私合规接口updatePrivacyAgree， 否则可能会无法正常使用相关功能。具体可参考隐私合规接口说明。

什么是定位SDK

Android 定位 SDK 是一套简单的LBS服务定位接口，您可以使用这套定位API获取定位结果、逆地理编码（地址文字描述）。

入门指南

本指南是向 Android 应用添加地图、定位的快速入门指南。

第 1 步：下载并安装 Android Studio

按照 Android Studio 编译器安装指南下载并安装 Android Studio。（注：下载地址为Google官方网站）

第 2 步：获取维智 KEY

使用维智管理平台 需要您在官网控制台获取Key。

第 3 步：创建项目

按以下步骤新建一个 Empty Activity 的应用项目。

  1. 启动 Android Studio。如果您看到 Welcome to Android Studio 对话框，请选择 Start a new Android Studio project，否则，请点击 Android Studio 菜单栏中的 File，然后点击 New->New Project，按提示输入您的应用名称、公司域和项目位置。然后点击 Next。

  2. 选择您的应用所需的机型。如果您不能确定自己的需求，只需选择Phone and Tablet。然后点击 Next。

  3. 在“Add an activity to Mobile”对话框中选择 EmptyActivity。然后点击Next。

  4. 按提示输入 Activity 名称、布局名称和标题。使用默认值即可。然后点击 Finish。

第 4 步：下载并安装定位开发包

从官网下载按照需求下载开发包并解压。

解压后，会得到一个jar文件，请您将jar文件添加到工程中，操作步骤请参考开发指南的 Android Stuido  jar 文件安装步骤。

第 5 步：Hello WZLocation

请查看 Android Studio 项目中的下列文件。

1、配置 AndroidManifest.xml 文件

默认情况下，AndroidManifest.xml 位于所设置项目目录main文件下。主要用于配置维智定位 Key 和申请权限：

在AndroidManifest.xml的application标签中配置Key：

<meta-data
    android:name="com.wayz.location.appkey"
    android:value="${wz_key}" />

在application标签中声明service组件：

<service android:name="com.wayz.location.WzService"></service>

在AndroidManifest.xml中配置权限:

<!-- 用户读取保存的 ID 文件-->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<!--允许获取粗略位置，粗略定位必选-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!--允许获取精确位置，精准定位必选-->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- 写入扩展存储，向扩展卡写入数据，用于写入离线定位数据-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!--允许访问网络，必选权限-->
<uses-permission android:name="android.permission.INTERNET" />
<!--允许获取网络状态，用于网络定位（无gps情况下的定位），若需网络定位功能则必选-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--允许获取wifi网络信息，用于网络定位（无gps情况下的定位），若需网络定位功能则必选-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!--允许获取wifi状态改变，用于网络定位（无gps情况下的定位），若需网络定位功能则必选-->
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<!--后台获取位置信息，若需后台定位则必选-->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

2、实现定位

如下几行代码可以帮助您实现最基础的定位功能

private lateinit var client: WzLocationClient
private lateinit var option: WzLocationClientOption
​
private fun initLocationClient() {
    option = WzLocationClientOption()
    // 回调间隔
    option.interval = 5000
    option.isFastLocation = false
    option.setOnceLocate(false)
    client = WzLocationClient(this@BasicLocActivity, option)
    client?.startLocation(this@BasicLocActivity)
}
​
    override fun onLocationReceived(location: WzLocation) {
        // 定位结果返回
    }
​
    override fun onLocationError(exception: WzException) {
        tv.text = StringBuilder().append("数据异常：").append(exception.errorMessage).toString()
    }
​

开发指南

创建工程

获取KEY

如何申请 KEY

  1. 创建应用

    进入控制台，创建一个新应用。如果您之前已经创建过应用，可直接跳过这个步骤。

    审核通过后，即可获取密钥 accessKey。

Android Studio 配置工程
新建一个Android工程

新建一个 Empty Activity 的应用工程，创建一个 Android 工程。 可以参考入门指南

集成 SDK

将下载的定位 SDK jar 文件复制到工程（此处截图以官方示例Demo为例子）的 libs 目录下，如果有老版本定位 jar 文件存在，请删除。如图所示：

配置 build.gradle 文件

在 build.gradle 文件的 dependencies 中配置导入 jar 包

隐私合规

1.定位的合规接口说明如下：

/** 设置包含隐私政策，并展示用户授权弹窗 必须在 WzLocationClient 实例化之前调用
 *
 * @param context:    上下文
 * @param isContains: 隐私权政策是否包含维智开平隐私权政策 true 是包含
 * @param isShow:     隐私权政策是否弹窗展示告知用户 true 是展示
 */
 public static synchronized void updatePrivacyShow(Context context, boolean isContains, boolean isShow);
 /**
  * 设置是否同意用户授权政策 必须在 WzLocationClient 实例化之前调用
  *
  * @param context 上下文
  * @param isAgree 隐私权政策是否取得用户同意 true 是用户同意
  */
  public static synchronized void updatePrivacyAgree(Context context, boolean isAgree);

  1. 在构造 WzLocationClient 之前必须进行合规检查，设置接口之前保证隐私政策合规，检查接口如下：

 MapsInitializer.updatePrivacyShow(this, true, true)
 MapsInitializer.updatePrivacyAgree(this, true)

获取位置

获取定位数据

首先，声明Service组件

请在application标签中声明service组件,每个app拥有自己单独的定位service。

<!-- 必选-->
<service android:name="com.wayz.location.WzService"></service>

然后，声明权限

Android 6.0及以上系统可以参考Android 6.0权限说明章节。

<!--用于进行网络定位-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission>
<!--用于访问GPS定位-->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
<!--用于获取运营商信息，用于支持提供运营商信息相关的接口-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
<!--用于访问wifi网络信息，wifi信息会用于进行网络定位-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
<!--用于获取wifi的获取权限，wifi信息会用来进行网络定位-->
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
<!--用于访问网络，网络定位需要上网-->
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<!--用于申请调用A-GPS模块-->
<uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"></uses-permission>
<!--如果设置了target >= 28 如果需要启动后台定位则必须声明这个权限-->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<!--如果您的应用需要后台定位权限，且有可能运行在Android Q设备上,并且设置了target>28，必须增加这个权限声明-->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

最后，设置维智KEY

在application标签中加入：

<meta-data android:name="com.wayz.location.appkey" android:value="wz_key" />

实用工具

定位SDK错误码对照表
常量字段 值 返回值说明
AIR_MODE 1003 因为您开了飞行模式，我们无法获取位置信息。
APPKEY_ILLEGAL 401 Appkey 非法或不存在
APPKEY_PERMISSION_ERROR 403 Appkey 权限异常
CANT_CAL_BACK 404 服务器异常
CANT_CAL_POSITON 1010 定位服务返回定位失败。
CANT_GET_ANY_INFO 1002 我们无法获取任何定位信息，请尝试打开 WI-FI 开关和 GPS 位置服务。
ERROR_CELLINFO 2002 定位时的基站信息错误。
ERROR_INIT 3001 定位初始化时出现异常。
常量字段 值 返回值说明
ERROR_START_CLIENT 3002 定位客户端启动失败。
GOT_NULL_PARAM 1005 获取到的请求参数为空，可能获取过程中出现异常。
GOT_ONLY_ONE_WIFI 1004 由于仅扫描到单个 wifi，且没有基站信息。
HTTP_OVERTIME 1009 网络请求超时
ILLEGAL_DEVICE_ID 1011 option 参数非法
MOCK_LOCATION 1006 定位结果被模拟导致定位失败。
ETWORK_UNREACHABLE 2001 无网络,请求服务器过程中的异常，多为网络情况差，链路不通导致。
NO_APPKEY 1008 您尚未配置 AppKey。
NO_PERMISSON 1001 没有定位权限
NO_SIM 1007 由于手机没插 sim 卡且 WIFI 功能被关闭。
PARAMS_ERROR 400 参数异常
常量字段 值 返回值说明
PATH_ERROR 404 URL 路径异常
PATH_ERROR 501 路径异常
SERVER_ERROR 500 服务器异常
SERVER_ERROR 502 服务器异常
Android 6.0 以上权限说明

Android 6.0系统在原有的AndroidManifest.xml声明权限的基础上新增了运行时权限动态检测，定位等权限也包含在其中。

第 1 步，声明目标SDK版本

Android 6.0系统默认为targetSdkVersion小于23的应用默认授予了所申请的所有权限，所以如果您APP设置的targetSdkVersion低于23，在运行时也不会崩溃。

Android Studio：

在build.gradle中声明targetSdkVersion为23。

android {
    compileSdkVersion 23
    buildToolsVersion '23.0.1'
    defaultConfig {
        applicationId "com.wayz.location.demo"
        minSdkVersion 14
        targetSdkVersion 23
        versionCode 1
        versionName "2.5.0"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

第 2 步，检查并申请定位权限

在运行定位之前需要对定位权限进行检查和申请，示例代码如下，

companion object {
    val permissions = arrayOf(
            Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION
    )
}
​
private fun checkPermisson() : Boolean {
    if (!EasyPermissions.hasPermissions(this, *MyApp.permissions)) {
        EasyPermissions.requestPermissions(this, "需要申请如下权限", 1, *MyApp.permissions)
        return false
    } else {
        return true
    }
}
​

第 3 步，用户授权

在请求权限后，系统会弹出相应的Dialog提示用户授予权限，如下图所示：

第 4 步，接收回调

用户选择允许或拒绝后，会回调onRequestPermissionsResult方法, 该方法类似于onActivityResult方法。

override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<out String>,
        grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    EasyPermissions.onRequestPermissionsResult(requestCode, permissions, grantResults, this)
}

相关下载

维智合规使用说明

维智合规使用说明文档，下载

Android 定位SDK下载

提供基础的维智定位服务，下载解压后，即可引用。下载

示例代码

Android平台全部示例代码，下载

参考文档下载

接口开发文档

Android 平台全部开发文档，在线查看

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布