bTrace
initTrace setInterval startTrace startGather stopTrace stopGather queryHistoryTrack createCircleFence createPolygonFence queryCacheTrackRequest queryDistance queryFenceHistoryAlarmInfo deleteFence queryRTTrack addEntity queryMonitoredStatus
论坛示例
为帮助用户更好更快的使用插件，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。
概述
bTrace插件封装了百度鹰眼轨迹SDK，该sdk提供如下功能：
- 轨迹追踪：按照设定的频率主动采集实时轨迹
- 轨迹存储：云端实现海量轨迹数据存储
- 轨迹查询：查询被追踪者实时位置、历史轨迹和里程
- 轨迹纠偏：云端对轨迹进行实时去噪、绑路、抽稀处理，解决轨迹偏移问题
- 地理围栏：当被追踪者进出一定范围（圆形、多边形、线型、行政区）的虚拟地理区域时，监控者可以接收到自动报警通知
- 图像存储：支持随轨迹上传、存储和查询图像文件
注意事项：
使用任何鹰眼轨迹接口前，必须先在百度轨迹管理台中创建鹰眼服务，获得servie_id后方可正式使用鹰眼轨迹。 一个service（即鹰眼轨迹服务，其唯一标识为service_id）对应一个的轨迹管理系统，至多同时管理100万个entity（即终端设备）。若需管理超过100万的终端，可创建多个service分别管理。创建鹰眼服务获取servie_id
在Android系统中通常使用轨迹追踪的应用都需要长时间后台运行，若手机开启了省电模式、各手机厂商定制的优化模式（如小米手机的神隐模式）、第三方安全应用的省电模式（如360手机卫士），则进程可能会被杀死。 处理策略为，用户在手机端关闭省电模式，或将APP加入这些模式的白名单
基本概念： 在使用插件前，需要了解百度鹰眼的一些基本概念，想要了解更多请到百度鹰眼官方网站
使用说明： 使用该插件需要到百度控制台申请appKey
配置说明： 使用此插件之前需先配置 config.xml 文件，配置完毕，需通过云端编译生效，配置方法如下：
- 名称：bTrace
- 参数：api_key
- 配置示例：
<!-- Android 配置方法 -->
<meta-data name="com.baidu.lbsapi.API_KEY" value="0Du6ujuego7WfAdHFOZ8rEr8Of0AHa9i"/>
<!-- iOS 配置方法 -->
<feature name="bTrace">
<param name="api_key" value="ATu9pjnegF7HfAgHuOZbrErnOf0A8ak0"/>
<param name="MCODE" value="com.apicloud.app"/>
</feature>
申请后台定位功能权限
由于系统限制，定位功能必须在 app 为当前激活使用状态或后台运行状态时才能正常运行。所以若要集成后台定位功能，必须得配置 config 文件 以申请后台运行权限，然后应用打包或自定义 loader 方可正常使用。配置实例如下：
//配置一个后台定位功能：
<preference name="backgroundMode" value="location"/>
//配置多个后台运行功能，各值之间用竖线 | 隔开：
<preference name="backgroundMode" value="location | audio"/>
注意：
初始化前先用 api.hasPermission 和 api.requestPermission 接口判断申请后台定位权限。
#插件接口
initTrace
初始化轨迹
initTrace({params}, callback(ret))
params
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID
entityName:
- 类型：字符串
- 描述：终端实体的名称，采集的轨迹将算在该 entity 名下
keepAlive：
- 类型：布尔
- 描述：（可选项）是否保活 仅支持 ios 平台
- 默认：false
isNeedObjectStorage：
- 类型：布尔类型
- 描述：是否需要对象存储 仅支持 Android 平台
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true // 布尔类型；sdk是否初始化成功；
message:'', // 字符串类型；返回消息（该字段和eventType一起返回）
code:10020, // 数字类型；返回的code（该字段和eventType一起返回）
eventType:'serviceStart' // 字符串类型；服务开启；取值范围如下：
// serviceStart 服务开启
// serviceStop 服务关闭
// gatherStart 开始采集数据
// gatherStop 停止采集数据
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.initTrace({
serviceId: 1000,
entityName: 'daughter',
}, function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
setInterval
设置定位和回传周期
initTrace({params}, callback(ret))
params
gatherInterval:
- 类型：数字
- 描述：采集周期
- 范围：2~300（单位：秒）
packInterval:
- 类型：数字
- 描述：打包周期
- 范围：2~300（单位：秒）
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true // 布尔类型；是否设置成功；
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.setInterval({
gatherInterval: 2,
packInterval: 10,
}, function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
startTrace
开启轨迹服务
startTrace({params}, callback(ret))
params
accuracy：
- 类型：字符串
- 描述：（可选项）定位精度
- 默认值：'100m'
- 取值范围：
- 10m
- 100m
- 1km
- 3km
filter：
- 类型：数字
- 描述：（可选项）位置更新所需的最小距离（单位米）
- 默认值：1.0
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true // 布尔类型；是否开启成功；
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.startTrace(function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
startGather
开启采集数据
startGather(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true // 布尔类型；是否采集成功；
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.startGather(function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
stopTrace
停止轨迹服务
stopTrace(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true // 布尔类型；停止轨迹服务；
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.stopTrace(function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
stopGather
停止数据采集
stopGather(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true // 布尔类型；停止采集；
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.stopGather(function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
queryHistoryTrack
查询历史轨迹
queryHistoryTrack({params}, callback(ret))
params
tag:
- 类型：数字
- 描述：请求tag
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID
entityName:
- 类型：字符串
- 描述：终端实体的名称，采集的轨迹将算在该 entity 名下
startTime:
- 类型：数字
- 描述：开始时间戳（单位：秒）
endTime:
- 类型：数字
- 描述：结束时间戳（单位：秒）
pageSize：
- 类型：数字
- 描述：分页大小
pageIndex:
- 类型：数字
- 描述：分页索引
- 默认：0
processOption：
- 类型：JSON对象
- 描述：纠偏设置
{
needDenoise: true, //（可选项）布尔类型；是否开启去噪功能
needVacuate: true, //（可选项）布尔类型；是否开启抽稀操作
needMapMatch:true, //（可选项）布尔类型；是否需要绑路
radiusThreshold: 100 //（可选项）数字类型；设置精度过滤值
transportMode:'walking' //（可选项）字符串类型；交通方式 // 取值范围：walking, riding, driving
}
coordType：
- 类型：字符串
- 描述：坐标类型 注意:仅支持iOS
- 取值范围：
- bd09ll 为百度坐标系，在GCJ02坐标系基础上再次加密
- gcj02 是由中国国家测绘局制订的地理信息系统的坐标系统
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
result:[{
direction:'', // 数字类型；方向
height:'', // 数字类型；高度
locTime:'', // 数字类型；定位时间
radius:'', // 数字类型；定位精度
speed:'', // 数字类型；速度
latitude:'', // 数字类型；纬度
longitude:'' // 数字类型；经度
}]
**iOS返回以下参数**
size:'31',
distance:61.89,
message:成功,
points:[{
direction:264, // 数字类型；方向
loc_time:'', // 数字类型；定位时间
radius:'65', // 数字类型；定位精度
floor:'',
create_time:'',// 字符串类型；创建时间
speed:0, // 数字类型；速度
locate_mode'网络定位',
latitude:'', // 数字类型；纬度
longitude:'' // 数字类型；经度
}]
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.queryHistoryTrack({
tag:0,
serviceId:12345,
entityName:'myCar',
startTime:new Date().getTime() / 1000 - 10000,
endTime:new Date().getTime() / 1000,
pageSize:1000,
pageIndex:10
},function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS 、Android系统
可提供的1.0.0及更高版本
createCircleFence
创建圆形围栏（客户端只支持圆形围栏）
createCircleFence({params}, callback(ret))
params
tag:
- 类型：数字
- 描述：请求tag
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID
entityName:
- 类型：字符串
- 描述：终端实体的名称，采集的轨迹将算在该 entity 名下 仅支持 Android 平台
monitoredCenter：
- 类型：字符串
- 描述：监控对象
type:
- 类型：字符串
- 描述：围栏类型
- 取值范围：
- client 在客户端创建
- server 在服务器端创建
centerLatitude：
- 类型：数字
- 描述：中心点纬度
centerLongitude：
- 类型：数字
- 描述：中心点经度
radius：
- 类型：数字
- 描述：半径
- 单位：米
denoise：
- 类型：数字类型
- 描述：去噪精度
- 单位：米
fenceName：
- 类型：数字类型
- 描述：围栏名称
coordType：
- 类型：字符串
- 描述：坐标类型
- 取值范围：
- bd09ll 为百度坐标系，在GCJ02坐标系基础上再次加密
- gcj02 是由中国国家测绘局制订的地理信息系统的坐标系统
- wgs84 为一种大地坐标系，也是目前广泛使用的GPS全球卫星定位系统使用的坐标系
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:0, //数字类型；返回状态
message:'创建成功', //字符串类型；返回信息
fenceId: 2323, // 数字类型；围栏Id
fenceName:'', // 字符串类型；围栏名称 **仅支持 Android 平台**
fenceShape:'circle', // 字符串类型； 取值范围：circle 圆形 polygon 多边形 **仅支持 Android 平台**
fenceType:'local' //字符串类型；取值范围：local 本地 server 服务器 **仅支持 Android 平台**
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.createCircleFence({
tag:0,
serviceId:12345,
entityName:'myCar',
centerLatitude:23.4545,
centerLongitude:45.455
},function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
createPolygonFence
创建多边形围栏（客户端只支持圆形围栏）
createPolygonFence({params}, callback(ret))
params
tag:
- 类型：数字
- 描述：请求tag
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID
fenceName：
- 类型：数字类型
- 描述：围栏名称
entityName:
- 类型：字符串
- 描述：终端实体的名称，采集的轨迹将算在该 entity 名下
monitoredCenter：
- 类型：字符串
- 描述：监控对象
vertexes：
- 类型：JSON数组
- 描述：多边形顶点数组
[{
latitude:23.45,
longitude:34.12
}]
denoise：
- 类型：数字类型
- 描述：去噪精度
- 单位：米
coordType：
- 类型：字符串
- 描述：坐标类型
- 取值范围：
- bd09ll 为百度坐标系，在GCJ02坐标系基础上再次加密
- gcj02 是由中国国家测绘局制订的地理信息系统的坐标系统
- wgs84 为一种大地坐标系，也是目前广泛使用的GPS全球卫星定位系统使用的坐标系
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:0, //数字类型；返回状态
message:'创建成功', //字符串类型；返回信息
fenceId: 2323, // 数字类型；
fenceName:'', // 字符串类型
fenceShape:'circle', // 字符串类型； 取值范围：circle 圆形 polygon 多边形
fenceType:'local' //字符串类型；取值范围：local 本地 server 服务器
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.createPolygonFence({
tag:0,
serviceId:12345,
entityName:'myCar',
centerLatitude:23.4545,
centerLongitude:45.455
},function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
queryCacheTrackRequest
查询缓存轨迹
queryCacheTrackRequest({params}, callback(ret))
params
entityName:
- 类型：字符串
- 描述：实体名称 仅支持 Android 平台
entityNames:
- 类型：字符串
- 描述：entity名称组成的数组 仅支持 iOS 平台
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID
tag:
- 类型：数字
- 描述：请求tag
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
**以下返回值仅支持 Android 平台**
startTime: 2323, // 数字类型；开始时间戳
endTime:23456, // 数字类型；结束时间戳
entityName:'myCar', // 字符串类型；实体名称
total:10 //字符串类型；缓存数量
**以下返回值仅支持 iOS 平台**
message: '', //字符串类型；信息
result:[{ //数组类型；获取的结果
end_time:'', //字符串类型；结束时间戳
entity_name:'', //字符串类型；实体名
start_time:'' //字符串类型；开始时间戳
total:3 //数字类型；总数
}],
status: 0, //数字类型；状态
tag: 1 //数字类型；标识
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.queryCacheTrackRequest({
tag:0,
serviceId:12345,
entityName:'myCar',
},function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
clearCacheTrackRequest
清除缓存轨迹
clearCacheTrackRequest({params,callback})
params
entityNames:
- 类型：JSON数组
- 描述：实体数组 仅支持 Android 平台
[
'myCar' // 字符串；实体名称数组
]
entities:
- 类型：JSON数组
- 描述：entity信息组成的数组 仅支持 ios 平台
{
name:'', //字符串类型；实体名
startTime: , //数字类型；开始时间
endTime: //数字类型；结束时间
}
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID
tag:
- 类型：数字
- 描述：请求tag
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：仅支持 ios 平台
{
message: '', //字符串类型；信息
status: 0, //数字类型；状态
tag: 1 //数字类型；标识
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.clearCacheTrackRequest({
tag:0,
serviceId:12345,
entityName:'myCar',
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
queryDistance
查询轨迹里程
queryDistance({params})
params
entityName:
- 类型：字符串
- 描述：实体名称
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID
tag:
- 类型：数字
- 描述：请求tag
startTime:
- 类型：数字
- 描述：开始时间戳
endTime:
- 类型：数字
- 描述：结束时间戳
transportMode：
- 类型：字符串
- 描述：交通方式
- 取值范围：
- driving 驾车
- riding 骑行
- walking 步行
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
distance：10000 // 数字类型；轨迹里程数 (仅支持 Android 平台)
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.queryDistance({
tag:0,
serviceId:12345,
entityName:'myCar',
startTime:new Date().getTime() / 1000 - 10000,
endTime:new Date().getTime(),
transportMode:'driving'
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
queryFenceHistoryAlarmInfo
查询报警信息
queryFenceHistoryAlarmInfo({params})
params
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID， 在 iOS 平台上会忽略本参数
tag:
- 类型：数字
- 描述：请求tag
startTime:
- 类型：数字
- 描述：开始时间戳
endTime:
- 类型：数字
- 描述：结束时间戳
monitoredPerson：
- 类型：字符串
- 描述：被监控的对象
coordType：
- 类型：字符串
- 描述：坐标类型 仅支持安卓平台
- 取值范围：
- bd09ll 为百度坐标系，在GCJ02坐标系基础上再次加密
- gcj02 是由中国国家测绘局制订的地理信息系统的坐标系统
- wgs84 为一种大地坐标系，也是目前广泛使用的GPS全球卫星定位系统使用的坐标系
fenceIds:
- 类型：JSON数组
- 描述：实体数组
[
123456 // 数字类型；fenceIds
]
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:0
message:''
result:[{
fenceId:10000, // 数字类型；轨迹里程数
fenceName:'', // 字符串类型；围栏名称
monitoredPerson:'', // 字符串类型；被监控的对象
monitoredAction:'enter' // 字符串类型；监控行为 取值范围：// enter 进入围栏
// exit 离开围栏
}]
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.queryFenceHistoryAlarmInfo({
tag:0,
serviceId:12345,
entityName:'myCar',
startTime:new Date().getTime() / 1000 - 10000,
endTime:new Date()/getTime(),
monitoredPerson:'myCar',
coordType:'bd09ll',
fenceIds:[1223,4554,23443]
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
deleteFence
删除围栏
deleteFence({params})
params
serviceId:
- 类型：数字
- 描述：开发者创建的鹰眼服务ID，在 iOS 平台上会忽略本参数
tag:
- 类型：数字
- 描述：请求tag
type：
- 类型：字符串
- 描述：围栏类型 仅支持 Android 平台
- 取值范围：
- local 本地
- server 服务器
monitoredPerson：
- 类型：字符串
- 描述：被监控的对象
fenceIds:
- 类型：JSON数组
- 描述：实体数组
[
123456 // 数字类型；fenceIds
]
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true
}
示例代码
var baiduTrace = api.require('bTrace');
baiduTrace.deleteFence({
tag:0,
serviceId:12345,
entityName:'myCar',
type:'server',
fenceIds:[1223,4554,23443]
},function(ret){
api.alert({msg: JSON.stringify(ret)});
})
可用性
iOS系统、Android系统
可提供的1.0.0及更高版本
queryRTTrack
检索符合过滤条件的Entity终端实体 仅支持iOS 平台
queryRTTrack({params}, callback(ret))
params
serviceId:
- 类型：数字类型
- 描述：开发者创建的鹰眼服务的ID
entityNames:
- 类型：字符串
- 描述：entity标识,可以是多个，不同标识之间用逗号隔开
columnKey:
- 类型：字符串
- 描述：（可选项）检索条件（格式为 : "key1=value1,key2=value2,....."）
activeTime：
- 类型：数字类型
- 描述：（可选项）UNIX时间戳，查询在此时间之后有定位信息上传的entity（loc_time>=activeTime）如查询2016-8-21 00:00:00之后仍活跃的entity，此字段设置为1471708800
pageSize：
- 类型：数字类型
- 描述：分页大小
pageIndex:
- 类型：数字类型
- 描述：（可选项）分页索引
returnType：
- 类型：数字类型
- 描述：（可选项）返回结果的类型
- 默认值：0
- 取值范围：
- 0 : 返回全部结果
- 1 : 只返回entityName的列表
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, // 布尔类型; 操作是否成功
result: '' // 字符串类型; 查询成功后的结果
}
err:
- 类型：JSON 对象
- 内部字段：
{
msg : '' // 字符串类型；错误消息
}
示例代码
var bTrace = api.require('bTrace');
bTrace.queryRTTrack({
entityNames: 'daughter',
serviceId: 1234,
columnKey: '',
activeTime: 0,
pageSize: 1000,
pageIndex: 10
}, function(ret, err) {
if (ret) {
api.alert({msg:JSON.stringify(ret)});
}
})
可用性
iOS系统
可提供的1.0.0及更高版本
addEntity
添加Entity 仅支持iOS 平台
addEntity({params}, callback(ret))
params
serviceId:
- 类型：数字类型
- 描述：开发者创建的鹰眼服务ID
entityName:
- 类型：字符串
- 描述：entity名称，作为其唯一标识
entityDES:
- 类型：字符串
- 描述：entity的可读性描述
columnKey：
- 类型：字符串
- 描述：属性名称（格式 : "key1=value1,key2=value2......."）
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, // 布尔类型; 操作是否成功
}
示例代码
var bTrace = api.require('bTrace');
bTrace.addEntity({
serviceId:1001,
entityName:'dad',
columnKey: ''
}, function(ret) {
if (ret) {
api.alert({msg:JSON.stringify(ret)});
}
})
可用性
iOS系统
可提供的1.0.0及更高版本
queryMonitoredStatus
查询实时状态，查询被监控对象和客户端地理围栏的位置关系
queryMonitoredStatus({params}, callback(ret))
params
tag:
- 类型：数字类型
- 描述：请求tag
serviceId:
- 类型：数字类型
- 描述：开发者创建的鹰眼服务ID
fenceId：
- 类型：数字类型
- 描述：要查询的围栏ID
monitoredPersons:
- 类型：字符串类型
- 描述：监控对象列表（多个entityName，以英文逗号"," 分割），ios平台仅读取第一个
type:
- 类型：字符串类型
- 描述：围栏类型
- 默认：server
- 取值范围：
- local 客户端本地围栏
- server 服务器围栏
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, // 布尔类型; 操作是否成功
result: '' // 字符串类型; 查询结果
}
示例代码
var bTrace = api.require('bTrace');
bTrace.queryMonitoredStatus({
fenceId:1001,
monitoredPersons: 'daughter,son'
}, function(ret) {
if (ret) {
api.alert({msg:JSON.stringify(ret)});
}
})
可用性
iOS系统
可提供的1.0.0及更高版本