维智定位 Android 定位 SDK
概述
维智 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 的应用项目。
-
启动 Android Studio。如果您看到 Welcome to Android Studio 对话框，请选择 Start a new Android Studio project，否则，请点击 Android Studio 菜单栏中的 File，然后点击 New->New Project，按提示输入您的应用名称、公司域和项目位置。然后点击 Next。
-
选择您的应用所需的机型。如果您不能确定自己的需求，只需选择Phone and Tablet。然后点击 Next。
-
在“Add an activity to Mobile”对话框中选择 EmptyActivity。然后点击Next。
-
按提示输入 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-dataandroid: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 = 5000option.isFastLocation = falseoption.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
-
创建应用
进入控制台，创建一个新应用。如果您之前已经创建过应用，可直接跳过这个步骤。
审核通过后，即可获取密钥 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);
-
在构造 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 23buildToolsVersion '23.0.1'defaultConfig {applicationId "com.wayz.location.demo"minSdkVersion 14targetSdkVersion 23versionCode 1versionName "2.5.0"}buildTypes {release {minifyEnabled falseproguardFiles 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 平台全部开发文档，在线查看