Harmony鹰眼SDK可以根据开发者自定义的定位周期和上传周期，自动地采集设备的位置信息，回传到鹰眼服务端，形成连续的轨迹。开发者可以为每个轨迹点添加附加信息，也可以对定位选项、采集周期与上传周期、缓存容量等进行自定义设置。SDK支持后台运行，断网时自动缓存，网络恢复后自动重连上传。
SDK与服务端采用TCP长连接与HTTPS通信，所有数据经过压缩和加密，保障数据安全，省电省流量。 轨迹追踪是鹰眼SDK中最基础、最核心的功能。通过类TraceClient中相应的接口，控制轨迹服务与轨迹采集的开启和停止，操作结果直接通过方法响应返回给开发者。下面首先对涉及到的基本概念进行介绍，之后会对各功能进行阐述。

SDK以采集周期为间隔，周期性地采集当前设备的位置信息；以上传周期为间隔，周期性地将若干轨迹点上传至鹰眼服务端。

当APP切换至后台，且期望尽量保持存活并持续定位追踪轨迹时，在APP声明定位权限时选择“同时需要前台和后台定位”，并且在最终用户授权时将APP定位权限设为“始终”，此时不论APP在前台还是后台，APP被杀死概率较低。
APP可定期检测用户定位授权状态，当检测到APP定位权限设不为“始终”时，可在适当的时机提示用户设置权限。以上操作均需严格遵守《百度地图开放平台产品和服务隐私政策》。

通过TraceClient类的 – constructor; 方法设置SDK运行所需要的基础信息。包括AK、轨迹服务的ID以及应用上下文。调用SDK的任何接口之前，必须先调用此隐私合规方法，在同意隐私合规情况下在调用TraceClient的constructor进行SDK的初始化，否则SDK的各功能无法正常运行。
以下代码片段表示，设置SDK运行时需要的基础信息：

import { LogMode, TraceClient } from "@bdmap/yingyan";

TraceClient.setAgreePrivacy(true); // 同意隐私合规协议

let traceClient = new TraceClient({
    ak: APP_AK,
    serviceId: APP_SERVICE_ID,
    context: appContext
    entityName: 'xxxxx',
    gatherInterval: 5, // 默认设置采集间隔（秒）
    packInterval: 30, // 默认 设置打包间隔（秒）
});

轨迹服务的控制分为开启轨迹采集（startGather）和停止轨迹采集（stopGather）两个接口。

通过setServiceStateListeners；方法开启服务监听，可以监听服务的各种状态。

// 轨迹服务状态变化回调
this.serviceStateCallback = (serviceOld: string, serviceNew: string) => {
    console.log('轨迹服务回调:', serviceOld, serviceNew);
};
 // 设置服务状态监听
traceClient.setServiceStateListeners(this.serviceStateCallback, this.gatherServiceStateCallback);
 // 开启服务
await traceClient.startTrace();

通过startGather; 方法开启轨迹采集，采集结果通过setLocationGatherCallback; 方法回调给开发者；上传结果通过setUploadResponseCallback方法回调给开发者。
开启轨迹采集时需要指定TraceConfigOptions类型的配置信息，目前TraceConfigOptions 接口中有entityName这个属性。该entityName在SDK的运行过程中有举足轻重的作用：

以下代码片段表示，开启轨迹采集：

[BinaryExpression]

通过TraceClient 类的 -stopGather方法停止采集轨迹，服务状态可以在上述开启服务的监听中收到回调。
以下代码片段表示，停止轨迹采集：

 // 停止采集服务
await traceClient.stopGather();

停止轨迹服务时，SDK会和服务端断开连接。在此之前，如果当前登录的entity有断网缓存的数据，则将其上传至服务端。以上操作均要求网络畅通，否则只是停止轨迹服务，缓存数据会由SDK持久化保存，待下次开启轨迹服务后，网络畅通的情况下，由SDK自动继续上传。
以下代码片段表示，停止轨迹服务：

await traceClient.stopService(); // 关闭服务

每个轨迹点都可能有一些和具体业务相关的数据，Harmony鹰眼SDK支持开发者将这些数据作为轨迹点的自定义数据，“附加”到这个轨迹点上。
SDK在每个采集周期会回调getTrackAttrData方法，将其返回值作为当前采集周期采集的轨迹点的自定义字段的值。SDK会解析此方法返回的字典，将key认为是自定义字段的名称，将value认为是自定义字段的值。需要注意的是，字典中的key必须是已经存在的 track属性字段。开发者可以通过鹰眼轨迹管理台，设置某个service的 track属性字段。下面我们通过一个例子，来进一步说明如何上传轨迹点的自定义字段值：
比如当前在开发一款跑步类的APP，可能需要记录每个轨迹点所对应的心率信息，那么可以通过以下几个步骤实现这一点:

在开启轨迹服务之后，停止轨迹服务之前，Harmony鹰眼SDK在运行期间内会随时TraceListener回调方法，向开发者推送消息，其中type 属性代表推送消息的类型，message 属性代表推送消息的内容。

目前轨迹监听服务主要支持网络服务、围栏报警服务等6个类型的事件监听和通知机制。

[BinaryExpression]

Harmony鹰眼SDK支持开发者对SDK的某些行为偏好进行自定义设置。主要分为定位选项设置、采集周期与上传周期设置、缓存容量设置3个方面。

鹰眼鹰眼轨迹SDK默认的采集周期为5秒，上传周期为30秒，即SDK会每隔5秒采集一次当前设备的位置信息，每隔30秒将该周期内的若干个位置信息打包、压缩、加密后传输至鹰眼服务端。
SDK支持开发者通过方法自定义采集周期和上传周期。设置结果会通过TraceClient类的getConfig方法回调给开发者。通过TraceClient类的setInterval方法设置采集和打包周期时，要求采集周期和上传周期的值域均为[2, 300]，且上传周期必须是采集周期的整数倍。
需要注意的是，该值一经设置，永久有效。即使是重新开启轨迹服务，也会按照上一次设置过的采集周期和上传周期进行采集和上传，SDK默认的采集周期和上传周期不再有效。如果想更改周期，再次调用此方法即可。该方法在开启轨迹服务之前和之后都可以调用。
采集周期一定是准确的，而上传周期只在网络畅通的时候才有意义。网络畅通的情况下，按照5秒采集30秒上传的默认值，查询历史轨迹时会发现，各轨迹点的loctime间隔为采集周期，而每6个连续的轨迹点的create_time是相同的，代表这6个点是同时上传至服务端的。而当断网时，SDK会自动缓存轨迹，等网络恢复后再批量上传至服务端。这种情况下，当查询历史轨迹时会发现，各轨迹点的loctime间隔仍然为采集周期，但create_time则没有什么规律了。但SDK会保证同一个entity终端的轨迹点，loctime较晚的点不会在loctime较早的点之前上传，以确保正确触发服务端地理围栏报警。
以下代码片段表示，将SDK默认的5秒采集一次位置信息、30秒上传一次位置信息，改为自定义的2秒采集一次位置信息、10秒上传一次位置信息。直到下次调用此方法，重新自定义采集周期和上传周期，SDK将一直使用本次自定义的值，即使停止轨迹服务后，重新开启轨迹服务也不受影响。

traceClient.setInterval(gatherInterval, packInterval)

鹰眼鹰眼轨迹SDK支持开发者自定义SDK缓存所占磁盘空间的最大值。开发者可以TraceClient类的setCacheMaxSize方法进行设置。关于此方法的行为有以下几点说明：
阈值一经设置，永久有效。如果想取消限制，只有再次设置一个非常大的值才行。 以下代码片段表示，设置客户端缓存占用磁盘空间的最大值为60MB，缓存轨迹数据占用超过60MB时将清空最早的缓存轨迹，直到占用空间满足要求。

traceClient.setCacheMaxSize(size)

鹰眼轨迹SDK除了可以自动采集并上传轨迹信息外，还支持开发者通过调用接口主动上传轨迹点。比如在两个采集周期之间，上传某个轨迹点作为补充；或者上传非当前登陆的entity的其他终端的轨迹点等使用场景。自定义轨迹点有如下几点说明：
自行上传的轨迹点除了可以上传位置坐标以及速度、方向、海拔高度、定位精度等系统预定义的track属性字段外，同样支持开发者自定义的track属性字段的上传，类似通过TraceClient类的setCustomAttribute(customMap: Map<string, string | number>)方法设置每个轨迹点的附加数据。
自行上传的轨迹点和鹰眼SDK主动采集上传的轨迹点存在以下异同：
示例一：上传某个entity的单个轨迹点
通过TraceClient类的createTrackUploadService().uploadSinglePoint({})方法，上传单个的自定义轨迹点；
以下代码片段表示，100000这个service下，已经通过轨迹管理台创建了3个叫做”someIntColumn”、 “someDoubleColumn”、 “someStringColumn” 的自定义track属性。名称为 “entityA” 的终端，在10秒钟之前，出现在了东经111.123456度，北纬44.654321度的位置，当时它的 “someIntColumn”属性的值为50，someDoubleColumn属性的值为44.55，someStringColumn属性的值为“aaa”，且方向为北偏东11度，海拔高度58米，定位精度为3米，速度为68米/秒。

traceClient.createTrackUploadService().uploadSinglePoint({
    entity_name: "car_001"; 
    latitude: 39.99; 
    longitude: 116.37; 
    loc_time: 1760583600; 
    coord_type_input: CoordType.BD09LL,
    //...
}).then(res=>{ })

示例二：批量上传多个entity的多个轨迹点
通过TraceClient类的createTrackUploadService().uploadMultiplePoints({})方法，批量上传若干个开发者自定义轨迹点，这些轨迹点可以属于不同的终端实体。
以下代码片段表示，一次性上传2个自定义轨迹点，分别属于entityA和entityB，每个轨迹点的设置与上面上传单个轨迹点时相同。

traceClient.createTrackUploadService().uploadMultiplePoints({
    point_list:[
        {
            entity_name: "car_001"; 
            latitude: 39.99; 
            longitude: 116.37; 
            loc_time: 1760583600; 
            coord_type_input: CoordType.BD09LL,
            //...
        },
        {
            entity_name: "car_001"; 
            latitude: 39.99; 
            longitude: 116.38; 
            loc_time: 1760583605; 
            coord_type_input: CoordType.BD09LL,
            //...
        }
    ]
}).then(res=>{ })