概述
維智 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 平臺全部開發文檔，在線查看
)
)
