数位云Android SDK接入指南

1 概述

数位场景识别Android SDK是一个提供精准室内位置的数据服务应用程序接口。该接口可提供无需额外硬件部署的室内位置识别功能，使移动设备应用快速具备获取用户室内精准位置的能力。https://cloud.papakaka.com/flash/#/dashboard可获取sdk

2 获取AppId与AppKey

场景识别Android SDK需要数位授权的AppId、AppKey，每个Key仅且唯一对于1个应用验证有效，即对该Key配置环节中使用的包名匹配的应用有效；

AppId和AppKey的获取方式：

1.注册数位云账号；

2.创建一个“我的应用”，即可获取；

3.联系数位商务同事激活此应用，即可正常使用。

3 开发指南

此文档适配Android SDK V4.1.0+版本。

3.1 导入库文件

库文件从数位云“下载”菜单中的“数位场景识别_Android_SDK”链接处获取；

请根据所用IDE选择导入方式：

Eclipse ADT：

将SDK中的 jar 文件拷贝到工程的libs文件夹中。

Android Studio：

在Android studio 项目的需要添加SDK的模块，新建libs文件夹；

将SDK中的jar包拷贝到刚才建立的libs文件夹中；

修改需要添加模块的build.gradle文件，添加放置SDK开发包jar到应用的lib目录，在需要集成SDK的module 中bulid.gradle文件中添加相关的依赖（具体jar包以实际提供的jar文件为准）。

dependencies {
    implementation files('libs/ShuweiELBS_Android_SDK_vx.x.x.jar')
}

3.2 忽略混淆（重要）

-keep class com.szshuwei.x.** { *; }
## 或者
-libraryjars libs/ShuweiELBS_Android_SDK _vx.x.x.jar

3.3 设置AndroidManifest.xml

在Application标签中声明SERVICE组件,每个APP拥有自己独立的定位service，此service可以单独运行在另一个进程中：

<service android:name="com.szshuwei.x.collect.service.SWLocationService"/>
or
<service android:name="com.szshuwei.x.collect.service.SWLocationService" android:process=":YourProcessName" />

声明使用权限：

<!-- 网络访问的权限 -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- 获取网络状态权限 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!-- 获取wifi列表、蓝牙列表，基站列表等定位信息的权限 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<!-- 获取手机IMEI号相关信息的权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<!-- 允许程序获取wifi状态和变化的权限 -->
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 获取蓝牙状态的权限 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

权限说明：

权限	用途
android.permission.INTERNET	允许程序网络访问的权限
android.permission.ACCESS_NETWORK_STATE	允许程序获取网络状态权限
android.permission.ACCESS_COARSE_LOCATION	允许程序获取wifi列表、蓝牙列表，基站等定位信息的权限
android.permission.ACCESS_FINE_LOCATION	允许程序获取wifi列表、蓝牙列表，基站等定位信息的权限
android.permission.READ_PHONE_STATE	允许程序获取手机IMEI号相关信息的权限
android.permission.CHANGE_WIFI_STATE	允许程序获取wifi变化的权限
android.permission.ACCESS_WIFI_STATE	允许程序获取wifi状态的权限
android.permission.BLUETOOTH	允许程序获取蓝牙变化的权限
android.permission.BLUETOOTH_ADMIN	允许程序获取蓝牙变化的权限

设置AppId，AppKey：

在Mainfest.xml正确设置AppId和AppKey，如果设置错误将会导致场景识别SDK服务无法正常使用。需在Application标签中加入以下代码，填入开发者自己的AppId和AppKey：

<meta-data
  android:name="com.shuwei.location.APP_ID"
  android:value="your app id"/>
<meta-data
  android:name="com.shuwei.location.APP_KEY"
  android:value="your app key"/>

3.4 初始化SDK

在应用程序的 Application 类的onCreate方法中调用SWLocationClient.initialization(this)

public class MainApplication extends Application{
  @Override
  public void onCreate() {
​    super.onCreate();
​      SWLocationClient.initialization(this);
   }
}
// 如果需要开启开发者日志功能，可以调用：SWLocationClient.initialization(this, true);

为了保证用户能够顺利的进行数据调试，增加了数据调试模式，通过注册插值器来模拟一段有定位结果的信号，使用方法如下：

SWLocationClient.initialization(this);

//...
//注册插值器，模拟输入信号，使用正常输入信号
if(DEBUG) {
​    SWLocationClient.getInstance().registerWifiInterpolater(new WifiInterpolater.Stub() {
​      @Override
​      public List<WifiItem2> interpolate() throws RemoteException {
​        return DebugUtils.mockResults();
​      }
​    });
}

//...
//取消插值器
SWLocationClient.getInstance().unregisterWifiInterpolater();

3.5 动态申请权限

对于Android 6.0以上版本，设备的部分权限使用是需要动态进行申请的，场景识别Android SDK涉及的权限有“获取手机基本信息”、“获取WiFi、基站、蓝牙等定位权限”：

获取手机基本信息的权限：

android.permission.READ_PHONE_STATE

获取WiFi、基站、蓝牙等定位需要用到的权限：

android.permission.ACCESS_COARSE_LOCATION
android.permission.ACCESS_FINE_LOCATION
android.permission.CHANGE_WIFI_STATE
android.permission.ACCESS_WIFI_STATE
android.permission.BLUETOOTH // 部分手机蓝牙权限要动态获取

重要提示：

为了不影响APP的用户体验，SDK不会主动申请权限（申请权限会弹对话框），SDK只会检查APP有没有相关的权限，如果有就正常回发数据，如果没有就保持静默或者不启动Service服务。

为了保证SDK的正常运行，如果您的APP 使用的SDK版本高于6.0（API >= 23） 请动态申请相关的权限，通常是在APP的启动页面去申请检查。

3.6 启动Service服务

在需要使用SDK中的任何功能之前，都需要先启动Service服务，启动Service服务必须放在SDK初始化之后。 建议在onCreate()生命周期中启动Service服务，代码如下：

SWLocationClient.getInstance().start();

如果需要监听Service服务启动是否成功了，可以注册监听回调接口，代码如下：

SWLocationClient.getInstance()
    .setOnClientStartListener(new SWLocationClient.OnClientStartListener() {
                    @Override
                    public void onStartSuccess() {
                        // 服务启动成功了
                    }

                    @Override
                    public void onStartFail() {
                        // 服务启动失败了
                    }
                });

3.7 停止Service服务

在不再需要使用SDK中的任何功能之后，可以停止Service服务。 建议在onDestory()生命周期中停止Service服务，代码如下：

SWLocationClient.getInstance().stop();

如果需要使用周期触发功能，请不要停止Servic