Web接口示例文档

.

.

API】接口文档

版本(V1.0)

2016年11月

【埋点

.

目 录

1. 版本信息 ........................................................................................................................... 1

2. 文档说明 ........................................................................................................................... 1

2.1 功能概述 ............................................................................................................. 1

2.2 阅读对象 ............................................................................................................. 1

2.3 业务术语 ............................................................................................................. 1

2.5接口地址 .............................................................................................................. 1

3. 安全规范 ........................................................................................................................... 1

3.1 签名机制 ............................................................................................................. 1

3.2 签名方式 ............................................................................................................. 2

3.3 加解密机制 ........................................................................................................ 2

3.4 加解密方式 ........................................................................................................ 2

4.埋点接口 ............................................................................................................................. 2

4.1.基本埋点信息提交 ............................................................................................ 2

4.1.1业务功能 .................................................................................................. 2

.

.

4.1.1接口地址 .................................................................................................. 2

4.1.2 输入参数列表 ....................................................................................... 2

4.1.3 返回参数列表 ....................................................................................... 4

4.2 拓展埋点信息提交 .......................................................................................... 7

4.1.1业务功能 .................................................................................................. 7

4.1.1接口地址 .................................................................................................. 7

4.1.2 输入参数列表 ....................................................................................... 7

4.1.3 返回参数列表 ....................................................................................... 9

.

.

1. 版本信息

编号 文档版本

1 V1.0

编写/修订章节

创建文档

修改内容

全文

修订人

修订日期

2016/11/7

2. 文档说明

2.1 功能概述

为收集提供埋点，以便把客户端收集的埋点信息存入后台。

2.2 阅读对象

本文档面向具有开发能力，需要参与埋点的开发和管理人员。

2.3 业务术语

埋点：用来监控用户点击的每一步，记录这些信息。

2.5接口地址

接口基本地址： {mobileApiBaseUrl}：**

联调地址: {mobileApiBaseUrl}：**

3. 安全规范

3.1 签名机制

签名使用md5加密，签名通过则可以调用接口进行埋点数据提交。

.

.

3.2 签名方式

Sign:name+”盐值” ,MD5 加密 32为 不够长度 前面补0。

Server使用盐值：lba_point_apply

盐值可变，变动会通知

3.3 加解密机制

3.4 加解密方式

4.埋点接口

4.1.基本埋点信息提交

4.1.1业务功能

基本埋点信息提交时调用

4.1.1接口地址

接口地址：{mobileApiBaseUrl}buriedPoint/**

访问方式： post

4.1.2 输入参数列表

字段名

mobile

中文名

手机号

类型

String(支持手机校验)

sign 签名 String 32位md5是

示例

描述 是否必填

是

.

.

加密

clientType 客户端类型

Integer ；2.h5； 签名认证 区别处理使用,这里的客户端是指提交埋点数据的端。

sex 性别 Integer 1 0 未知，

1 男，2

女

name

mobileModel

resolutionWidth

resolutionHeight

operatingSystem

idCode

applicationVersion

browser

extranetIp

downNetworkType

姓名 String（64）

手机型号 String（64）

分辨率宽 Integer（7位整数）

分辨率高 Integer(7位整数)

操作系统 String(128)

识别码 String(128)

应用版本 String(64)

浏览器

外网IP

下载网络类型

browseNetworkType 访问网络类型

operateTime 操作时间 String 2016-11-07

01:10:01

日期和小时之间只有且只有一个空格，也可以不满足只要jdk是

String(64)

String(64)

String

String(64)

192.168.1.139

支持ipv4和ipv6

是

此2参数要传必须一起传，

是

.

.

解析获得准确的年月日时分秒即可

longitude 经度 Double 9999以内正负数，10位以内小数

latitude 纬度 Double 9999以内正负数，10位以内小数

address

token

remark

requestCheck

地理位置 String(255)

Token

备注

String（128）

String

开发调试使用

1.返回参数校验结果。联调时使用

supportedParams 支持接收的参数

Integer 开发调试使用

1.返回支持的参数列表。联调时使用

参数说明：

参数requestCheck和supportedParams在联调时使用，里面设置开关，进入生成后关闭开关失效，有问题必要时开启开关，验证问题。

否

否 传参检验 Integer

shanyin

要传一起传

4.1.3 返回参数列表

字段名

status

message

checkResult

数据类型

Integer

String

Map

示例

0

成功

描述

返回状态，0表示成功

返回消息说明

检验结果，如果传requestCheck=1，则返回，便于联调

.

.

参数说明：

这里主要说明checkResult,按照如下规则返回

{

"ownRequestProperties": [

{

"propertyName": "mobile",

"propertyChName": "手机号码",

"propertyValue": "13976",

"requestPropertyCheckState": "参数名大小写错误，传递为:moBile,系统要求：mobile;参数值：不满足手机格式要求"

},

{

"propertyName": "extranetIp",

"propertyChName": "外网Ip",

"propertyValue": "13976",

"requestPropertyCheckState": "参数值：不满足ip格式要求"

}

]

}

ownRequestProperties为请求端实际所传的参数列表，通过这个结果可以快速检查使用接口过程中可能出现的问题，免去过量的沟通成本。设定是只要requestPropertyCheckState为ok,就算所传参数通过。参数一旦通过，接口将正常保存信息。当通过这个接口仍然无法解决问题时，再进入人工沟通解决。

目前联调信息主要是ownRrequestProperties做辅助，有其他返回信息必要再另行通知。

4.1.4 相关数据库表

CREATE TABLE `basic_point` (

`id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '标识',

`mobile` varchar(18) DEFAULT NULL COMMENT '手机',

`client_type` int(3) DEFAULT NULL COMMENT '客户端类型',

.

.

`sex` int(3) DEFAULT NULL COMMENT '性别',

`name` varchar(64) DEFAULT NULL COMMENT '姓名',

`mobile_model` varchar(64) DEFAULT NULL COMMENT '手机型号',

`resolution_width` int(8) DEFAULT NULL COMMENT '分辨率宽',

`resolution_height` int(8) DEFAULT NULL COMMENT '分辨率高',

`operating_system` varchar(128) DEFAULT NULL COMMENT '操作系统',

`id_code` varchar(128) DEFAULT NULL COMMENT '识别码',

`application_version` varchar(64) DEFAULT NULL COMMENT '应用版本',

`browser` varchar(64) DEFAULT NULL COMMENT '浏览器',

`extranet_ip` varchar(255) DEFAULT NULL COMMENT '外网Ip',

`down_network_type` varchar(64) DEFAULT NULL COMMENT '下载网络类型',

`browse_network_type` varchar(64) DEFAULT NULL COMMENT '访问网络类型',

`operate_time` datetime DEFAULT NULL COMMENT '操作时间',

`longitude` decimal(10,6) DEFAULT NULL COMMENT '经度',

`latitude` decimal(10,6) DEFAULT NULL COMMENT '纬度',

.

.

`address` varchar(255) DEFAULT NULL COMMENT '地理位置',

`token` varchar(128) DEFAULT NULL COMMENT 'token',

`created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP

COMMENT '创建时间',

PRIMARY KEY (`id`)

) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8

COMMENT='基本埋点信息表';

4.2 拓展埋点信息提交

4.2.1业务功能

拓展埋点信息提交调用

4.2.2接口地址

接口地址：{mobileApiBaseUrl}/buriedPoint/**

访问方式： post

4.2.3 输入参数列表

字段名

mobile

sign

中文名

手机号

签名

类型

String(手机校验)

String 32位是

md5加

示例

描述 是否必填

是

.

.

密

clientType 客户端类型 Integer ,2.h5,e

签名认证区别处理使用,这里的客户端是指提交埋点数据pageId

pageRemark

pageUrl

firstActivation

eventId

eventRemark

previousPage

currentPage

label

parameter

stayId

stayTimes

operateTime

页面ID String（128）

页面中文名 String

页面URL

首次激活

事件ID

上一页面

当前页面

标签

参数

停留ID

停留时间

操作时间

String(1000)

String(64)

String(64)

String(1000)

String(1000)

String(64)

String(1000)

String(64)

Integer(20)

String

19位以内正整数

2016-11-07

01:10:01

秒数

日期和小时之间只有且只有一个空格，也可以不满足只要jdk解析获

是

的

端。

是

事件中文名 String

.

.

得准确的年月日时分秒即可

viewport

cursor

action

remark

requestCheck

Viewport

cursor

action

备注

传参检验

String(255)

String(64)

String(64)

String

Integer

1.返回参数校验supportedParams 支持接收的参数

Integer

结否

果。

1.返回支持的参数列表。

参数说明：

参数requestCheck和supportedParams在联调时使用，里面设置开关，进入生成后关闭开关失效，有问题必要时开启开关，验证问题。

否

4.2.4 返回参数列表

字段名

status

message

checkResult

中文名

Integer

String

Map

0

成功

类型

功

返回消息说明

检验结果，如果传requestCheck=1，则返回，便于联调

参数说明：

checkResult和埋点基本信息接口的结果值checkResult相同

示例

返回状态，0表示成

.

.

4.2.5相关数据库表

CREATE TABLE `expand_point` (

`id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '标识',

`mobile` varchar(18) NOT NULL COMMENT '手机',

`client_type` int(3) DEFAULT NULL COMMENT '客户端类型',

`page_id` varchar(128) DEFAULT NULL COMMENT '页面ID',

`page_url` varchar(1000) DEFAULT NULL COMMENT '页面URL',

`first_activation` varchar(64) DEFAULT NULL COMMENT '首次激活',

`event_id` varchar(64) DEFAULT NULL COMMENT '事件ID',

`previous_page` varchar(1000) DEFAULT NULL COMMENT '上一页面',

`current_page` varchar(1000) DEFAULT NULL COMMENT '当前页面',

`page_label` varchar(64) DEFAULT NULL COMMENT '标签',

`parameter` varchar(1000) DEFAULT NULL COMMENT '参数',

`stay_id` varchar(64) DEFAULT NULL COMMENT '停留ID',

`stay_times` bigint(20) DEFAULT NULL COMMENT '停留时间',

`viewport` varchar(255) DEFAULT NULL COMMENT 'viewport',

.

.

`page_cursor` varchar(64) DEFAULT NULL COMMENT 'cursor',

`action` varchar(64) DEFAULT NULL COMMENT 'action',

`created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP

COMMENT '创建时间',

PRIMARY KEY (`id`)

) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8

COMMENT='拓展埋点信息表';

4.3基本埋点信息批量提交

4.3.1业务功能

基本埋点信息提交时调用

4.3.1接口地址

接口地址：{mobileApiBaseUrl}buriedPoint/ **

访问方式： post

4.3.2 输入参数列表

字段名

mobile

中文名

手机号

类型

String(支持手机校验)

sign

clientType

签名

客户端类String

Integer

32位md5加密

；2.h5； 签名认证是

是

示例

描述 是否必填

是

.

.

型 区别处理使用,这里的客户端是指提交埋点数据的端。

basicPointListJson 基本埋点信息数组对象

是

对象属性

sex

性别

Integer

1

0 未知，

1 男，2

女

name

mobileModel

resolutionWidth

resolutionHeight

operatingSystem

idCode

applicationVersion

browser

extranetIp

downNetworkType

姓名 String（64）

192.168.1.139

2016-11-07

01:10:01

此2参数要传必须一起传，

支持ipv4和ipv6

日期和小时之间只有且只有一个空格，也可

手机型号 String（64）

分辨率宽 Integer（7位整数）

分辨率高 Integer(7位整数)

操作系统 String(128)

识别码 String(128)

应用版本 String(64)

浏览器

外网IP

下载网络类型

String(64)

String

String(64)

String(64)

是

是

browseNetworkType 访问网络类型

operateTime 操作时间 String

.

.

以不满足只要jdk解析获得准确的年月日时分秒即可

longitude 经度 Double 9999以内正负数，10位以内小数

latitude 纬度 Double 9999以内正负数，10位以内小数

address

token

remark

地理位置 String(255)

Token

备注

String（128）

String

shanyin

要传一起传

4.3.3 返回参数列表

字段名

status

message

数据类型

Integer

String

示例

0

成功

描述

返回状态，0表示成功

返回消息说明

4.3.4 相关数据库表

basic_point

4.4 拓展埋点信息批量提交

4.4.1业务功能

拓展埋点信息提交调用

.

.

4.4.2接口地址

接口地址：{mobileApiBaseUrl}/buriedPoint/**

访问方式： post

4.4.3 输入参数列表

字段名

mobile

sign

中文名

手机号

签名

类型

String(手机校验)

String 32密

clientType 客户端类型

Integer ,2.h5,e

签名认证区别处理使用,这里的客户端是指提交埋点数据的端。

expandPointListJson

对象属性

pageId

pageRemark

pageUrl

firstActivation

eventId

eventRemark

previousPage

页面ID

页面中文名

页面URL String(1000)

首次激活 String(64)

事件ID

事件中文名

上一页面 String(1000

String(64)

String

String（128）

String

拓展数组 数组

是

位是

md5加

示例

描述 是否必填

是

.

.

)

currentPage

label

parameter

stayId

stayTimes

operateTime

当前页面 String(1000)

标签

参数

停留ID

String(64)

String(1000)

String(64)

20位正整数

2016-11-07

01:10:01

秒数

日期和小时之间只有且只有一个空格，也可以不满足只要jdk解析获得准确的年月日时分秒即可

viewport

cursor

action

remark

Viewport

cursor

action

备注

String(255)

String(64)

String(64)

String

是

停留时间 Integer(20)

操作时间 String

4.4.4 返回参数列表

字段名

status

message

中文名

Integer

String

0

成功

类型

功

返回消息说明

示例

返回状态，0表示成.

.

4.4.5相关数据库表

expand_point

4.5 APP埋点接口盐值获取

4.5.1业务功能

使用注意事项，只有返回埋点确实传status=2的时候，才可以请求此更新

4.5.2接口地址

接口地址：{mobileApiBaseUrl}/buriedPoint/**

访问方式： post

4.5.3 输入参数列表

字段名

mobile

中文名

手机号

类型

String(手机校验)

示例

描述 是否必填

是

4.5.4 返回参数列表

字段名

status

中文名

Integer 0

类型

功

示例

返回状态，0表示成.

.

message

result

svk

String

Map

盐值

成功

返回消息说明

返回消息

.