百度地图 Android 定位SDK 开发指南4.2
1. 导入库文件
在相关下载最新的库文件。将liblocSDK4.so文件拷贝到libs/armeabi目录下。将locSDK4.1.jar文件拷贝到工程的libs目录下,并在工程属性->Java Build Path->Libraries中选择“Add JARs”,选定locSDK4.1.jar,确定后返回。这样您就可以在程序中使用百度地理围栏SDK了。
2. 设置AndroidManifest.xml
2.1 在application标签中声明service组件,每个app拥有自己单独的定位service
- <service
- android:name="com.baidu.location.f" android:enabled="true" android:process=":remote">
- </service>
2.2 声明使用权限
- <!-- 这个权限用于进行网络定位-->
- <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission>
- <!-- 这个权限用于访问GPS定位-->
- <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
- <!-- 用于访问wifi网络信息,wifi信息会用于进行网络定位-->
- <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
- <!-- 获取运营商信息,用于支持提供运营商信息相关的接口-->
- <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
- <!-- 这个权限用于获取wifi的获取权限,wifi信息会用来进行网络定位-->
- <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
- <!-- 用于读取手机当前的状态-->
- <uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
- <!-- 写入扩展存储,向扩展卡写入数据,用于写入离线定位数据-->
- <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permission>
- <!-- 访问网络,网络定位需要上网-->
- <uses-permission android:name="android.permission.INTERNET" />
- <!—SD卡读取权限,用户写入离线定位数据-->
- <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS"></uses-permission>
- <!--允许应用读取低级别的系统日志文件 -->
- <uses-permission android:name="android.permission.READ_LOGS"></uses-permission>
2.3 import相关类
- import com.baidu.location.BDLocation;
- import com.baidu.location.BDLocationListener;
- import com.baidu.location.LocationClient;
- import com.baidu.location.LocationClientOption;
- import com.baidu.location.BDNotifyListener;//假如用到位置提醒功能,需要import该类
- //如果使用地理围栏功能,需要import如下类
- import com.baidu.location.BDGeofence;
- import com.baidu.location.BDLocationStatusCodes;
- import com.baidu.location.GeofenceClient;
- import com.baidu.location.GeofenceClient.OnAddBDGeofencesResultListener;
- import com.baidu.location.GeofenceClient.OnGeofenceTriggerListener;
- import com.baidu.location.GeofenceClient.OnRemoveBDGeofencesResultListener;
3. 设置AcessKey
使用SDK4.2需要在Mainfest.xml设置Accesskey,设置有误会引起定位和地理围栏服务不能正常使用,必须进行Accesskey的正确设置。
设置AccessKey,在application标签中加入
- <meta-data
- android:name="com.baidu.lbsapi.API_KEY"
- android:value="key" />//key:开发者申请的key
4. 功能类的使用
4.1 使用基本定位功能
基本定位功能指的根据用户实际需求,返回用户当前位置的基础定位服务。包含GPS和网络定位(Wi-Fi和基站定位)功能。基本定位功能同时还支持结合定位结果的反地理编码功能,离线定位,位置提醒功能和地理围栏功能。
4.1.1 初始化LocationClient类
此处需要注意:LocationClient类必须在主线程中声明。需要Context类型的参数。
Context需要时全进程有效的context,推荐用getApplicationConext获取全进程有效的context
- public LocationClient mLocationClient = null;
- public BDLocationListener myListener = new MyLocationListener();
- public void onCreate() {
- mLocationClient = new LocationClient(getApplicationContext()); //声明LocationClient类
- mLocationClient.registerLocationListener( myListener ); //注册监听函数
- }
LocationClient类是定位SDK的核心类,具体方法如下:
-
构造类:
-
设置参数:
参数:配置定位SDK,详见LocationClientOption类。 说明:2.x版本以后的定位提供API接口,用以在API运行过程中,支持热切换配置参数。
-
注册监听函数:
参数:详见BDLocationListener类。 说明:当没有注册监听函数时,无法发起网络请求。
-
注册位置提醒监听事件:
-
开启/关闭:
start:启动定位SDK。 stop:关闭定位SDK。调用stop之后,设置的参数LocationClientOption仍然保留。
-
发起定位:
发起定位,异步获取当前位置。因为是异步的,所以立即返回,不会引起阻塞。定位结果在ReceiveListener的方法OnReceive方法的参数中返回。
需要注意:当定位SDK从定位依据判定,位置和上一次没发生变化,而且上一次定位结果可用时,则不会发起网络请求,而是返回上一次的定位结果。 返回值:
- 0:正常发起了定位。
- 1:服务没有启动。
- 2:没有监听函数。
- 6:请求间隔过短。 前后两次请求定位时间间隔不能小于1000ms。
-
请求离线定位:
离线定位功能:用户请求过得基站定位结果会缓存在本地文件。离线定位结果为缓存结果,精度低于在线的定位结果。
离线定位结果没有地址信息。
发起离线定位,异步获取当前位置。因为是异步的,所以立即返回,不会引起阻塞。定位结果在ReceiveListener的方法OnReceive方法的参数中返回。
返回值:
- 0:正常发起了定位。
- 1:服务没有启动。
- 2:没有监听函数。
-
取消监听函数:
取消监听函数。
-
位置提醒相关函数:
4.1.2 实现BDLocationListener接口
BDLocationListener接口有2个方法需要实现: 1.接收异步返回的定位结果,参数是BDLocation类型参数。
- public class MyLocationListener implements BDLocationListener {
- @Override
- public void onReceiveLocation(BDLocation location) {
- if (location == null)
- return ;
- StringBuffer sb = new StringBuffer(256);
- sb.append("time : ");
- sb.append(location.getTime());
- sb.append("\nerror code : ");
- sb.append(location.getLocType());
- sb.append("\nlatitude : ");
- sb.append(location.getLatitude());
- sb.append("\nlontitude : ");
- sb.append(location.getLongitude());
- sb.append("\nradius : ");
- sb.append(location.getRadius());
- if (location.getLocType() == BDLocation.TypeGpsLocation){
- sb.append("\nspeed : ");
- sb.append(location.getSpeed());
- sb.append("\nsatellite : ");
- sb.append(location.getSatelliteNumber());
- } else if (location.getLocType() == BDLocation.TypeNetWorkLocation){
- sb.append("\naddr : ");
- sb.append(location.getAddrStr());
- }
- logMsg(sb.toString());
- }
- }
BDLocation类,封装了定位SDK的定位结果,在BDLocationListener的onReceive方法中获取。通过该类用户可以获取error code,位置的坐标,精度半径等信息。具体方法如下:
获取error code:
返回值:
- 61 : GPS定位结果
- 62 : 扫描整合定位依据失败。此时定位结果无效。
- 63 : 网络异常,没有成功向服务器发起请求。此时定位结果无效。
- 65 : 定位缓存的结果。
- 66 : 离线定位结果。通过requestOfflineLocaiton调用时对应的返回结果
- 67 : 离线定位失败。通过requestOfflineLocaiton调用时对应的返回结果
- 68 : 网络连接失败时,查找本地离线定位时对应的返回结果
- 161: 表示网络定位结果
- 162~167: 服务端定位失败
- 502:key参数错误
- 505:key不存在或者非法
- 601:key服务被开发者自己禁用
- 602:key mcode不匹配
- 501~700:key验证失败
如果不能定位,请记住这个返回值,并到我们的hi群或者贴吧中交流。若返回值是162~167,请发送邮件至mapapi@baidu.com反馈。
获取经纬度坐标:
获取定位的坐标。坐标的类型在setLocationClientOption方法中设定。
获取定位精度:
获取文字描述的地址(反地理编码):
只有使用网络定位的情况下,才能获取当前位置的反地理编码描述。
自定位SDK2.6版本之后,支持获取省/市/区分级地理信息:
- public String getProvince ( ) //获取省份信息
- public String getCity ( ) //获取城市信息
- public String getDistrict ( ) //获取区县信息
获取手机方向信息:
4.1.3 设置定位参数
设置定位参数包括:定位模式(高精度定位模式,低功耗定位模式和仅用设备定位模式),返回坐标类型,是否打开GPS等等。
高精度定位模式:这种定位模式下,会同时使用网络定位和GPS定位,优先返回最高精度的定位结果;
低功耗定位模式:这种定位模式下,不会使用GPS,只会使用网络定位(Wi-Fi和基站定位);
仅用设备定位模式:这种定位模式下,不需要连接网络,只使用GPS进行定位,这种模式下不支持室内环境的定位。
eg:
- LocationClientOption option = new LocationClientOption();
- Option.setLocationMode(LocationMode.Hight_Accuracy);//设置定位模式
- option.setCoorType("bd09ll");//返回的定位结果是百度经纬度,默认值gcj02
- option.setScanSpan(5000);//设置发起定位请求的间隔时间为5000ms
- option.setIsNeedAddress(true);//返回的定位结果包含地址信息
- option.setNeedDeviceDirect(true);//返回的定位结果包含手机机头的方向
- mLocClient.setLocOption(option);
LocationClientOption类,该类用来设置定位SDK的定位方式,具体方法如下:
-
设置定位模式
-
设置打开GPS
设置是否打开gps,使用gps前提是用户硬件打开gps。默认是不打开gps的。
-
设置是否需要设备方向信息
-
设置是否需要地址信息
设置是否要返回地址信息,默认为无地址信息。
String 值为 all时,表示返回地址信息,其他值都表示不返回地址信息。
-
设置坐标类型:
设置返回值的坐标类型。
我们支持返回若干种坐标系,包括国测局坐标系、百度坐标系,需要更多坐标系请联系我们,需要深度合作。目前这些参数的代码为。因此需要在请求时指定类型,如果不指定,默认返回百度坐标系。注意当仅输入IP时,不会返回坐标。目前这些参数的代码为
- 返回国测局经纬度坐标系 coor=gcj02
- 返回国测局经纬度坐标系 coor=gcj02
- 返回百度经纬度坐标系 coor=bd09ll
百度手机地图对外接口中的坐标系默认是bd09ll,如果配合百度地图产品的话,需要注意坐标系对应问题。 有关坐标系的更多问题,请看常见问题
-
设置产品线名称:
设置产品线名称。强烈建议您使用自定义的产品线名称,方便我们以后为您提供更高效准确的定位服务。
-
设置定位时间间隔:
说明:
- 当所设的整数值大于等于1000(ms)时,定位SDK内部使用定时定位模式。调用requestLocation( )后,每隔设定的时间,定位SDK就会进行一次定位。如果定位SDK根据定位依据发现位置没有发生变化,就不会发起网络请求,返回上一次定位的结果;如果发现位置改变,就进行网络请求进行定位,得到新的定位结果。定时定位时,调用一次requestLocation,会定时监听到定位结果。
- 当不设此项,或者所设的整数值小于1000(ms)时,采用一次定位模式。每调用一次requestLocation( ),定位SDK会发起一次定位。请求定位与监听结果一一对应。
- 设定了定时定位后,可以热切换成一次定位,需要重新设置时间间隔小于1000(ms)即可。locationClient对象stop后,将不再进行定位。如果设定了定时定位模式后,多次调用requestLocation(),则是每隔一段时间进行一次定位,同时额外的定位请求也会进行定位,但频率不会超过1秒一次。
-
设置位置提醒接口:
4.1.4 发起定位请求
发起定位请求。请求过程是异步的,定位结果在上面的监听函数onReceiveLocation中获取。
- if (mLocClient != null && mLocClient.isStarted())
- mLocClient.requestLocation();
- else
- Log.d("LocSDK4", "locClient is null or not started");
4.1.5 发起离线定位请求
发起离线定位请求。请求过程是异步的,定位结果在上面的监听函数onReceiveLocation中获取。 getLocTypte = BDLocation.TypteOfflineLocation || BDLocation.TypeOfflineLocationFail 表示是离线定位请求返回的定位结果
4.1.6 位置提醒使用
位置提醒最多提醒3次,3次过后将不再提醒。 假如需要再次提醒,或者要修改提醒点坐标,都可通过函数SetNotifyLocation()来实现。
- //位置提醒相关代码
- mNotifyer = new NotifyLister();
- mNotifyer.SetNotifyLocation(42.03249652949337,113.3129895882556,3000,"gps");//4个参数代表要位置提醒的点的坐标,具体含义依次为:纬度,经度,距离范围,坐标系类型(gcj02,gps,bd09,bd09ll)
- mLocationClient.registerNotify(mNotifyer);
- //注册位置提醒监听事件后,可以通过SetNotifyLocation 来修改位置提醒设置,修改后立刻生效。
- //BDNotifyListner实现
- public class NotifyLister extends BDNotifyListener{
- public void onNotify(BDLocation mlocation, float distance){
- mVibrator01.vibrate(1000);//振动提醒已到设定位置附近
- }
- }
- //取消位置提醒
- mLocationClient.removeNotifyEvent(mNotifyer);
4.2使用地理围栏服务Beta
地理围栏服务提供的是基于位置的提醒服务,相对于SDK原来提供的位置提醒功能,地理围栏服务通过SDK本身的内部逻辑,大幅度降低位置提醒服务的功耗情况。通过使用地理围栏服务,第三方APP可以在低能耗的模式下轻松实现位置提醒服务。
4.2.1 初始化GeofecenClient类
此处需要注意:GeofenceClient类必须在主线程中声明。需要Context类型的参数。
- Context需要时全进程有效的context,推荐用getApplicationConext获取全进程有效的context。
- public GeofenceClient mGeofenceClient = null;
- public void onCreate() {
- mGeofenceClient = new GeofenceClient(getApplicationContext();
- }
4.2.2 实现添加和删除围栏的回调接口
添加围栏回调:OnAddBDGeofencesResultListener
实现如下:
- public class AddGeofenceListener implements OnAddBDGeofencesResultListener {
- @Override
- public void onAddBDGeofencesResult(int statusCode, String geofenceRequestId) {
- if (statusCode == BDLocationStatusCodes.SUCCESS) {
- //围栏创建成功
- }}}
删除围栏回调:OnRemoveBDGeofencesResultListener
实现如下:
- public class RemoveFenceListener implements OnRemoveBDGeofencesResultListener {
- @Override
- public void onRemoveBDGeofencesByRequestIdsResult(int statusCode, String[] geofenceRequestIds) {
- if (statusCode == BDLocationStatusCodes.SUCCESS) {
- //围栏删除成功
- }}}
4.2.3 实现并注册OnGeofenceTriggerListener回调接口
- public class GeofenceEnterLister implements OnGeofenceTriggerListener {
- @Override
- public void onGeofenceTrigger(String geofenceRequestId) {
- //进入围栏,围栏Id = geofenceRequestId
- }
- @Override
- public void onGeofenceExit(String geofenceRequestId) {
- //退出围栏,围栏Id = geofenceRequestId
- }
- //注册并开启围栏扫描服务
- mGeofenceClient .registerGeofenceTriggerListener(new GeofenceEnterLister());
- mGeofenceClient.start();
- }
4.2.4 设置围栏参数
围栏参数包括:id:围栏Id、x,y:围栏坐标点经纬度、name:半径类型(RADIUS_TYPE_SMALL、RADIUS_TYPE_MIDDELE、RADIUS_TYPE_LARGE)、expir:围栏的有效时间,单位毫秒(最长可以设置1个月)、coordType:坐标类型(COORD_TYPE_BD09、COORD_TYPE_BD09LL、COORD_TYPE_GCJ)、 具体如下:
- BDGeofence fence = new BDGeofence.Builder().setGeofenceId(id).
- setCircularRegion(x, y, type)
- . setExpirationDruation(expir)
- . setCoordType(coordType)
- .build();
4.2.5 发起围栏添加和删除请求
- //添加一个围栏:
- mGeofenceClient.addBDGeofence(fence, new AddGeofenceListener());
- //删除,指定要删除围栏的名字列表
- List<string> fences = new ArrayList<string>();
- fences.add(fenceId);
- mGeofenceClient. removeBDGeofences(fences, new RemoveFenceListener());
- </string></string>
5. 需要注意的问题
- 定位SDK必须注册GPS和网络的使用权限。
- 使用定位SDK请保证网络连接通畅(GPS定位方式不需要连网)。
- 我们强烈建议您设置自己的prodName,并保管好,这样方便我们为您提供更好的定位服务。
- 若需要返回的定位结果里包含地址信息,请保证网络连接。
- 定位SDK可以返回bd09、bd09ll、gcj02三种类型坐标,若需要将定位点的位置通过百度Android地图 SDK进行地图展示,请返回bd09ll,将无偏差的叠加在百度地图上。
- 有的移动设备锁屏后为了省电会自动关闭网络连接,此时网络定位模式的定位失效。此外,锁屏后移动设备若进入cpu休眠,定时定位功能也失效。若您需要实现在cpu休眠状态仍需定时定位,可以用alarmManager 实现1个cpu可叫醒的timer,定时请求定位。