Web接口示例文档.doc

埋点API接口文档V1.1 【埋点API】接口文档版本(V1.0)2016年11月16目 录1. 版本信息12. 文档说明12.1 功能概述12.2 阅读对象12.3 业务术语12.5接口地址13. 安全规范23.1 签名机制23.2 签名方式23.3 加解密机制23.4 加解密方式24.埋点接口24.1.基本埋点信息提交24.1.1业务功能24.1.1接口地址24.1.2 输入参数列表24.1.3 返回参数列表34.2 拓展埋点信息提交44.1.1业务功能44.1.1接口地址54.1.2 输入参数列表54.1.3 返回参数列表51. 版本信息编号文档版本编写/修订章节修改内容修订人修订日期1V1.0创建文档全文2016/11/72. 文档说明2.1 功能概述为收集提供埋点，以便把客户端收集的埋点信息存入后台。2.2 阅读对象本文档面向具有开发能力，需要参与埋点的开发和管理人员。2.3 业务术语埋点：用来监控用户点击的每一步，记录这些信息。2.5接口地址接口基本地址： mobileApiBaseUrl：http:/*联调地址: mobileApiBaseUrl：http:/*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接口地址接口地址：mobileApiBaseUrlburiedPoint/*访问方式： post4.1.2 输入参数列表字段名中文名类型示例描述是否必填mobile手机号String(支持手机校验)是sign签名String32位md5加密是clientType客户端类型Integer1.app；2.h5；3.server签名认证区别处理使用,这里的客户端是指提交埋点数据的端。是sex性别Integer10 未知，1 男，2 女name姓名String（64）mobileModel手机型号String（64）resolutionWidth分辨率宽Integer（7位整数）此2参数要传必须一起传，resolutionHeight分辨率高Integer(7位整数)operatingSystem操作系统String(128)idCode识别码String(128)applicationVersion应用版本String(64)browser浏览器String(64)extranetIp外网IPString39支持ipv4和ipv6是downNetworkType下载网络类型String(64)browseNetworkType访问网络类型String(64)operateTime操作时间String2016-11-07 01:10:01日期和小时之间只有且只有一个空格，也可以不满足只要jdk解析获得准确的年月日时分秒即可是longitude经度Double9999以内正负数，10位以内小数要传一起传latitude纬度Double9999以内正负数，10位以内小数address地理位置String(255)tokenTokenString（128）shanyinremark备注StringrequestCheck传参检验Integer开发调试使用1.返回参数校验结果。联调时使用否supportedParams支持接收的参数Integer开发调试使用1.返回支持的参数列表。联调时使用否参数说明：参数requestCheck和supportedParams在联调时使用，里面设置开关，进入生成后关闭开关失效，有问题必要时开启开关，验证问题。4.1.3 返回参数列表字段名数据类型示例描述statusInteger0返回状态，0表示成功messageString成功返回消息说明checkResultMap检验结果，如果传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/*访问方式： post4.2.3 输入参数列表字段名中文名类型示例描述是否必填mobile手机号String(手机校验)是sign签名String32位md5加密是clientType客户端类型Integer1.app,2.h5,3.service签名认证区别处理使用,这里的客户端是指提交埋点数据的端。是pageId页面IDString（128）pageRemark页面中文名StringpageUrl页面URLString(1000)firstActivation首次激活String(64)eventId事件IDString(64)eventRemark事件中文名StringpreviousPage上一页面String(1000)currentPage当前页面String(1000)label标签String(64)parameter参数String(1000)stayId停留IDString(64)stayTimes停留时间Integer(20)19位以内正整数秒数operateTime操作时间String2016-11-07 01:10:01日期和小时之间只有且只有一个空格，也可以不满足只要jdk解析获得准确的年月日时分秒即可是viewportViewportString(255)cursorcursorString(64)actionactionString(64)remark备注StringrequestCheck传参检验Integer1.返回参数校验结果。否supportedParams支持接收的参数Integer1.返回支持的参数列表。否参数说明：参数requestCheck和supportedParams在联调时使用，里面设置开关，进入生成后关闭开关失效，有问题必要时开启开关，验证问题。4.2.4 返回参数列表字段名中文名类型示例statusInteger0返回状态，0表示成功messageString成功返回消息说明checkResultMap检验结果，如果传requestCheck=1，则返回，便于联调 参数说明： checkResult和埋点基本信息接口的结果值checkResult相同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接口地址接口地址：mobileApiBaseUrlburiedPoint/ *访问方式： post4.3.2 输入参数列表字段名中文名类型示例描述是否必填mobile手机号String(支持手机校验)是sign签名String32位md5加密是clientType客户端类型Integer1.app；2.h5；3.server签名认证区别处理使用,这里的客户端是指提交埋点数据的端。是basicPointListJson基本埋点信息数组对象是对象属性sex性别Integer10 未知，1 男，2 女name姓名String（64）mobileModel手机型号String（64）resolutionWidth分辨率宽Integer（7位整数）此2参数要传必须一起传，resolutionHeight分辨率高Integer(7位整数)operatingSystem操作系统String(128)idCode识别码String(128)applicationVersion应用版本String(64)browser浏览器String(64)extranetIp外网IPString39支持ipv4和ipv6是downNetworkType下载网络类型String(64)browseNetworkType访问网络类型String(64)operateTime操作时间String2016-11-07 01:10:01日期和小时之间只有且只有一个空格，也可以不满足只要jdk解析获得准确的年月日时分秒即可是longitude经度Double9999以内正负数，10位以内小数要传一起传latitude纬度Double9999以内正负数，10位以内小数address地理位置String(255)tokenTokenString（128）shanyinremark备注String4.3.3 返回参数列表字段名数据类型示例描述statusInteger0返回状态，0表示成功messageString成功返回消息说明4.3.4 相关数据库表basic_point4.4 拓展埋点信息批量提交4.4.1业务功能拓展埋点信息提交调用4.4.2接口地址接口地址：mobileApiBaseUrl/buriedPoint/*访问方式： post4.4.3 输入参数列表字段名中文名类型示例描述是否必填mobile手机号String(手机校验)是sign签名String32位md5加密是clientType客户端类型Integer1.app,2.h5,3.service签名认证区别处理使用,这里的客户端是指提交埋点数据的端。是expandPointListJson拓展数组数组对象属性pageId页面IDString（128）pageRemark页面中文名StringpageUrl页面URL