维智定位 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 的应用项目。

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：

在application标签中声明service组件：

在AndroidManifest.xml中配置权限:

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。

然后，声明权限

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

最后，设置维智KEY

在application标签中加入：

实用工具

定位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,
        grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    EasyPermissions.onRequestPermissionsResult(requestCode, permissions, grantResults, this)
}

相关下载

维智合规使用说明

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

Android 定位SDK下载

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

示例代码

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

参考文档下载

接口开发文档

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