轨迹追踪

简介

鹰眼Android SDK可根据开发者设置的定位和回传频率,自动采集并回传轨迹。

开发者通过在APP中调用startTrace()和stopTrace()方法,来控制何时开始轨迹采集、何时停止轨迹采集。

最基础的轨迹追踪

实现最简单的轨迹追踪功能,请参见Hello Trace部分示例,在此不作重复说明。

设置轨迹定位周期和回传周期

概念:

定位周期:多久定位一次,在定位周期大于15s时,SDK会将定位周期设置为5的倍数(如设置采集周期为18s,SDK会调整为15s;设置为33s,SDK会调整为30s)


回传周期:鹰眼为节省电量和流量,并不是定位一次就回传一次数据,而是隔段时间将一批定位数据打包压缩回传。(回传周期最大不要超过定位周期的10倍,例如,定位周期为10s,则回传周期最好不要大于60s)


使用方法:

鹰眼SDK支持开发者动态设置定位周期和回传周期(2s至5分钟),可以在开启服务前设置,也可以在服务运行过程中动态设置,下一采集周期生效。开发者可自行判断终端的运动速度和状态,动态调整定位周期。使用示例:

//位置采集周期
int gatherInterval = 2;
//打包周期
int packInterval = 12;
//设置位置采集和打包周期
client.setInterval(gatherInterval, packInterval);

轨迹点自定义属性数据上传

轨迹中的每个位置点可拥有一系列开发者自定义的描述字段,如汽车的电量、发动机转速等,用以记录行程中的实时状态信息。鹰眼不仅支持结构化的自定义字段,也支持图像这样的对象类型数据。


为实现自定义属性数据上传,开发者须重写OnCustomAttributeListener监听器中的onTrackAttributeCallback()接口,调用 LBSTraceClient.setOnCustomAttributeListener()方法设置自定义属性监听器,并按照设置的定位周期更新onTrackAttributeCallback()的返回值。SDK每采集一次轨迹,便会自动回调onTrackAttributeCallback()接口,获取属性值并写入当前轨迹点的属性字段中。


自定义属性监听器需通过LBSTraceClient.setOnCustomAttributeListener()进行设置,LBSTraceService只回调最新设置的自定义监听器。


onTrackAttributeCallback()的返回值是Map<String, String>类型,每个对象都是一个<key,value>对,其中key为entity的自定义字段名称,value为值。


示例:随轨迹上传电动车电量和行车图像

1. 上传电量:开发者需创建一个名为energy的track自定义字段用来记录车辆当前剩余电量


2. 上传行车影像:当开发者需要随轨迹上传图像数据,可利用鹰眼 SDK 图像存储功能进行图像的上传、存储和查询,详见图像存储。例如:司机路遇拥堵或事故时,需上报现场图片至服务端。

图像上传的同时,利用自定义属性上传功能,可将图片文件的唯一标识objectKey传入轨迹点的 object_name字段中,将图片文件与轨迹点绑定。在查询轨迹和实时位置时,通过 object_name 即可查询到轨迹点对应的图像文件。


为满足以上两个场景的需求,此时可重写onTrackAttributeCallback()如下 :

OnCustomAttributeListener mCustomAttributeListener = new OnCustomAttributeListener() {
    @Override
    public Map<String, String> onTrackAttributeCallback() {
        Map<String, String> trackAttrs = new HashMap<String, String>();
 
        //获取当前电量:getCurrentEnergy()为开发者自定义的获取当前电量的方法
        String energy = getCurrentEnergy();
       //随轨迹点上传电量信息
        trackAttrs.put("energy", energy);
 
        //获取图像的唯一标识ObjectKey:getObjectKey()为开发者自定义的获取行车图像的objectKey。
        String objectKey = getObjectKey();
       //随轨迹上传图像唯一标识ObjectKey
        trackAttrs.put("object_name", objectKey);
 
        return trackAttrs;
    }
};

复杂网络状态下,SDK的连接与轨迹回传策略

在网络状态持续良好的情况下,SDK将按照指定频率回传轨迹。如果在开启轨迹追踪时、追踪过程中、或结束轨迹追踪时遇到网络不稳定或断网的情况,SDK也有相应处理策略:


①开启轨迹服务,调用startTrace()时

调用startTrace()后,SDK会与服务端建立连接,并将已缓存的轨迹数据上传到服务端,但不会进行定位采集,即尚未开始轨迹追踪。

若建立连接过程中,网络不稳定或者断网,SDK均会监听网络变化,在网络状态改变且可用时,重新发起连接。因此,开发者可以在APP初始化完成后,开启轨迹服务,以便提前完成SDK与服务端的连接,尽量降低连接操作对正常业务流程的影响。


②轨迹追踪过程中,调用startGather()

开启轨迹服务后,需调用startGather(),SDK才会开始真正的定位采集。

在采集过程中,若出现网络中断、连上不可上网的Wi-Fi,或网络频繁切换时,SDK都将自动开启缓存模式,将采集的轨迹数据保存到数据库中,并自动监听网络,待联网时自动回传缓存数据。

鹰眼未限制缓存数据量,只要手机存储空间未满,就将持续缓存数据。一旦手机空间不足,将停止写入缓存数据。


③停止轨迹追踪,调用stopGather()时

要结束当前采集任务时,只需调用stopGather(),此时SDK便会停止采集,但仍将维持与服务端的长连接。

因此,若在采集追踪过程中,出现网络不可用的情况,导致缓存了轨迹信息,此时SDK也会监听网络变化,网络可用时便会重连,连接建立成功后将缓存数据上传到服务端。