轨迹追踪 - 百度地图 API

简介

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

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

注意：
开发者在百度地图鹰眼自行上传数据与百度地图开放平台无关，开发者应对上传数据的合法性负责，并确保不侵犯他人合法权益。若上传数据包含用户隐私信息，包括但不限于用户名、手机号、身份ID等，请开发者确保已获取用户的授权同意并由开发者自行加密以保障用户隐私安全，百度地图开放平台不对开发者自行上传的用户数据进行校验和加密。

最基础的轨迹追踪

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

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

概念：

定位周期：多久定位一次，在定位周期大于15s时，SDK会将定位周期设置为5的倍数（如设置采集周期为18s，SDK会调整为15s；设置为33s，SDK会调整为30s）

回传周期：鹰眼为节省电量和流量，并不是定位一次就回传一次数据，而是隔段时间将一批定位数据打包压缩回传。（回传周期最大不要超过定位周期的10倍，例如，定位周期为5s，则回传周期最好不要大于50s）
注意：回传周期不能小于定位周期，否则回传不生效；回传周期建议设置为定位周期的整数倍。

使用方法：

可以在开启服务前或在服务运行过程中动态设置定位和回传周期，设置完成后一旦进入下一采集周期即生效。开发者可自行判断终端的运动速度和状态，动态调整定位周期。使用示例：

//位置采集周期
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也有相应处理策略:

1. 开启轨迹服务，调用startTrace()时

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

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

2. 轨迹追踪过程中，调用startGather()

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

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

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

3. 停止轨迹追踪，调用stopGather()时

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

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

关于后台保活的说明

随着互联网对用户隐私的日益关注和保护，Android系统对于长时间后台定位的监管也更加严格。开发者在严格遵守《百度地图开放平台产品和服务隐私政策》的前提下，可通过申请加入华为等手机厂商后台应用白名单、创建前台通知、声明前台服务和后台定位权限等合理方式，提升APP和鹰眼service的存活率，提升轨迹的完整性。详细请参考服务的存活章节。