欢迎使用AIPS3.0用户接口文档
除了您现在看到的这个在线版本,您还可以前往以下网址下载:
什么是 AIPS3.0
AIPS3.0 介绍
1. AIPS3.0接口特点
- 让用户快速搭建平台管理终端设备;
- 让用户快速便捷地投放多媒体广告;
AIPS3.0用户接口文档将帮助用户通过HTTPS协议实现如下功能:
- 获取指定GPS位置附近的终端设备
- 获取终端设备运行时长和运行里程
- 向指定终端设备投放公益和商业广告
- 获取所有终端设备播放记录
2. AIPS3.0接口访问方法
AIPS3.0接口使用HTTPS的POST方法获取数据,请求地址的一般格式为:
https://[WEBSITE]/p/taxi.TaxiPublisher/[API]
其中[WEBSITE]为服务器地址,[API]为需要请求的API接口名称,已开放的API接口目录如下:
编号 |
接口名 |
功能简介 |
1 |
BindTaxiLicence |
绑定设备车牌号(或其他唯一标识) |
2 |
QueryTaxiRunningTime |
查询设备运行时长 |
3 |
QueryTaxiMileage |
查询设备已移动公里数 |
4 |
QueryTaxiLocation |
查询设备当前位置 |
5 |
QueryNearbyTaxi |
查询指定经纬度附近的设备 |
6 |
UpsertPeriodPrice |
设置各时段广告播放单价 |
7 |
Advertising |
投放商业广告 |
8 |
CustomizedShow |
投放非商业信息 |
9 |
UpdateAdStatus |
变更投放信息状态 |
10 |
SetAddressToSaveAdLog |
设置播放日志回传地址 |
WEBSITE地址需要通过如下方式获取:
发送邮件至sdk@xixunled.com
POST请求头需包含用户身份验证字符串,用户身份验证字符串在https://deerclick.com.cn网站注册登录成功后即可取得。
POST请求参数和返回参数均为JSON数据格式。
4. 接口访问举例
暂无
AIPS3.0接口详细说明
注意:
- HTTPS类型接口均为POST请求,请求地址格式为:
https://[WEBSITE]/p/taxi.TaxiPublisher/[API]
- 所有POST请求的报文头中必须包含一个名为"Authorization"的头部字段,其对应的值为用户从AIPS3.0平台下载的授权身份凭证字符串。如何获取凭证请[参考这里]。
- 所有POST的请求参数使用JSON格式字符串放在BODY中。
- 所有POST的返回数据使用JSON格式字符串放在BODY中。
1. BindTaxiLicence
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/BindTaxiLicence;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"xixun_id":"设备序列号", //string类型
"licence":"车辆牌照" //string类型
}
- 应答数据格式:
{
"result":0/1 //int类型。0表示失败,1表示成功
}
- 接口功能说明:
该接口可以将指定设备与一个唯一的用户标识(如车牌号)关联。后面所有对设备的操作均使用licence作为操作对象的标识。
2. QueryTaxiRunningTime
3. QueryTaxiMileage
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/QueryTaxiMileage;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"taxi_id":"licence", //string类型
"begin_at":0 //int64类型
}
- 应答数据格式:
{
"mileage":0 //double类型
}
- 接口功能说明:
该接口通过传入设备唯一标识(接口1中绑定的licence)和起始查询时间,begin_at为int64类型的时间戳,单位毫秒。返回设备从指定时间开始的运行里程,单位米。
4. QueryTaxiLocation
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/QueryTaxiLocation;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"list_taxi_id" :["licence1", "licence2", ...] //string类型数组
}
- 应答数据格式:
{
"list_location":[{"taxi_id":"", "longitude":"", "latitude":"", "distance":""}]
}
- 接口功能说明:
该接口可以指定多个设备的唯一标识(如车牌号)作为查询条件,返回每个设备当前所处的GPS坐标。返回数据中的list_location是一个JSON字符串数组,taxi_id是设备唯一标识,longitude和latitude是经纬度(WGS84坐标系),类型均为string。distance无意义可忽略。
5. QueryNearbyTaxi
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/QueryNearbyTaxi;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"longitude":0.0, //double类型,经度
"latitude":0.0, //double类型,维度
"radius": 0, //int32类型,指定半径范围
"limit":10 //int32类型,限定查询结果的数量
}
- 应答数据格式:
{
"list_location":[{"taxi_id":"licence", "longitude":"0.0", "latitude":"0.0", "distance":"2000"}]
}
- 接口功能说明:
该接口可以传入longitude和latitude作为圆心的GPS坐标和radius指示的半径(单位米)作为查询条件,返回GPS坐标在这个范围内的设备。如果查询结果数量大于limit,则按distance从小到大排列返回limit个设备信息。
返回数据中的list_location是一个JSON字符串数组,taxi_id是设备唯一标识,longitude和latitude是当前设备经纬度,distance为设备到圆心的距离,单位米。
如无特别说明,接口中涉及的GPS坐标均为WGS84坐标系。
6. UpsertPeriodPrice
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/UpsertPeriodPrice;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"price_list":[{"period":"00:00-11:59", "price":1.0}, {"period":"12:00-23:59", "price":2.0}]
}
- 应答数据格式:
{
"result":0/1 //int类型。0表示失败,1表示成功
}
- 接口功能说明:
该接口可以设置各个时段的广告投放价格,price_list是时段定价的数组,period指定开始和结束时间,price为定价。
结合接口7中用户的广告投放预算平衡用户广告每日播放次数和总投放量。如果不是用接口7,则可以忽略该接口。
7. Advertising
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/Advertising;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"ad_id" :"123", //string类型,广告ID;
"meta" :"iamge", //string类型,image为图片,video为视频,text为文本;
"resource" :"http://download_url.com", //string类型,如果meta为text,resource为文字内容,\n换行,\r分页;meta不为text则resource为文件下载url;
"template" :"", //string类型,meta为text时,template为文字显示背景,暂时忽略不用;
"longitude" :0.0, //double类型,广告允许显示区域的经度;
"latitude" :0.0, //double类型,广告允许显示区域的纬度;
"radius" :0, //int32类型,广告允许显示区域的半径;
"total_budget" :100.0,//double类型,广告投放总预算;
"daily_budget" :10.0,//double类型,广告投放每日预算;
"view_type" :1,//int32类型,meta为text时,1,2,3分别表示单页,滚动和两页显示;
"list_period" :["01:00-03:00","18:00-19:00"]//string类型数组,指定允许播放的时段。
}
- 应答数据格式:
{
"result":0/1 //int类型。0表示失败,1表示成功
}
- 接口功能说明:
该接口可以将商业广告投放到用户所属的设备上。广告类型可以是文字、图片和视频中任一种。
该接口未指定具体播放的设备,只要和服务器正常通信的设备都有可能收到该播放任务,设备根据限定的longitude,latitude和radius判断是否应播放该广告。
服务器根据设备回传的播放记录、广告投放预算来通知设备继续播放或停止播放。
接口调用成功后投放状态为发布(状态码1),调用接口9可以变更已投放广告的状态。
8. CustomizedShow
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/CustomizedShow;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"ad_id" :"123",//string类型,广告ID;
"meta" :"image",//string类型,image图片,video视频,text文本;
"resource" :"http://download_url.com", //string类型; //string类型,如果meta为text,resource为文字内容,\n换行,\r分页;meta不为text则resource为文件下载url;
"template" :"", //string类型,暂时忽略不用;;
"view_type" :1, //int32类型,meta为text时,1,2,3分别表示单页,滚动和两页显示;
"funny" :true, //boolean类型,true则为插播信息,只显示一次。否则为公益广告,永久播放;
"list_licence" :["licence1","licence2",...]//字符串数组,指定播放该内容的设备标识;
}
- 应答数据格式:
{
"result":0/1 //int类型。0表示失败,1表示成功
}
- 接口功能说明:
该接口可以将普通广告或插播信息投放到list_licence指定的设备上。广告类型可以是文字、图片和视频中任一种。
当Advertising和当CustomizedShow同时存在于同一设备中,funny=true的CustomizedShow优先级最高,其次是Advertising,当没有其他内容可播放时才播放funny=false的CustomizedShow;
接口调用成功后投放状态为发布(状态码1),调用接口9可以变更已投放广告的状态。
9. UpdateAdStatus
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/UpdateAdStatus;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"ad_id":"123", //string类型,广告ID;
"ad_status":1 //int32类型,变更后的状态:1发布,2暂停,3终止
}
- 应答数据格式:
{
"result":0/1 //int类型。0表示失败,1表示成功
}
- 接口功能说明:
该接口变更指定广告的投放状态,Advertising和当CustomizedShow两种类型的广告均适用。
10. SetAddressToSaveAdLog
- 接口地址:https://[WEBSITE]/p/taxi.TaxiPublisher/SetAddressToSaveAdLog;
- 请求头格式:"Authorization":"用户从AIPS3平台下载的授权身份凭证字符串";
- 请求参数格式:
{
"address":"http://userserver.com/upload_record //string类型
}
- 应答数据格式:
{
"result":0/1 //int类型。0表示失败,1表示成功
}
- 接口功能说明:
该接口可以给AIPS3平台设定一个http POST方法,从AIPS3平台获取用户设备的播放记录。
回传日志数据为JSON格式:
{
"records":
[{
"fadid":"123", //string类型
"fplaycaridnum":"licence", //string类型
"ffee":2, //float64类型
"fplaydatetime":1542178020, //int64类型,单位秒
"fequipid":"device_SN" //string类型,设备序列号
}]
}
用户端收到数据成功后需要在应答的body中包含SUCCESS字符串,否则AIPS3会尝试再次发送数据直到成功为止。
上海熙讯电子科技有限公司 研发部
2018-11-29