文档中心 维纳斯 开发指南 服务端接入指南

服务端接入指南

最近更新时间:2019-08-14 18:49:03

Wns 服务端部署架构

详细内容请参考新手入门 > 整体架构的说明。

WNS 和开发商服务器的通信方式

WNS 接入服务器和开发商服务器之间建立 TCP 长连接,目前只支持单发单收的模式,就是一个连接上,WNS 发送数据到开发商服务器后,必须等开发商服务器返回响应包后,再发下一个请求。多个并发的请求就建立多个连接来并发收发数据。

WNS 和开发商服务器的通信协议

开发商接入 WNS,开发商服务器需要对接 WNS 接入服务器的协议,目前主要有两种协议对接方式。
HTTP 协议:开发商服务器不用任何改造就可以接入 WNS,WNS 接入服务器和开发商服务器之间的通信是标准的 HTTP 协议。
二进制协议:开发商服务器需要改造对接 WNS 接入服务器的协议,具体协议格式在下面详细介绍。

HTTP 协议对接

开发商的 web 服务器不需要做任何改造,wns 透传开发商自己的 http 数据包。为了开发商便于获取终端的信息,wns 在 http 头上,会添加部分信息。具体内容如下
X-Wns-Qua:Wns Sdk 的版本信息,开发商可以记录 sdk 版本信息,定位问题时可以便于确认具体的版本号。
X-Forwarded-For:移动终端的 IP 地址,开发商可以根据终端 IP 做精确营销等服务。
X-Wns-DeviceInfo:移动终端的设备信息,开发商可以根据设备信息做图片适配、差异化服务等。
X-Wns-Wid:移动终端的唯一标识,可以根据 wid 做详细的问题定位,开发商也可以使用 wid 做 push 消息调用。
QVIA:移动终端的 IP,内容和 X-Forwarded-For 相同。

二进制协议说明

维纳斯二进制协议主要包括协议开始标记、协议头,数据串、协议结束标记,一共四个部分,如下图所示

WNS 接入服务器 转发到 开发商服务器协议: STX + pdu + UpStream + ETX
开发商服务器 返回到 WNS 接入服务器协议: STX +pdu + DownStream + ETX
说明:
STX:协议开始标记位(1 字节)。
Pdu:WNS 协议头(23 字节)。
UpStream: protobuf 结构,客户端 APP 发送的 buf 在其中(变长字段)。
DownStream:protobuf 结构,开发商返回的 buf 在其中(变长字段)。
ETX:协议结束标记位(1 字节)。

STX 和 ETX(单字节标记位)

STX = 0x04
ETX = 0x05

Pdu 协议格式(二进制网络字节序)

struct pdu_protocol_header
{ 
uint8_t version;           //wns保留,开发商无需识别
uint32_t cmd;             // wns保留,开发商无需识别
uint16_t checksum;         // wns保留,开发商无需识别
uint32_t seq;             // wns保留,开发商无需识别
uint32_t key;             //填写0
uint8_t response_flag;    //填写0
uint16_t response_info;    //填写0
char reserved[1];          //预留字段
uint32_t len;                //整个数据长度,包括STX、协议头、ETX等 
 } ;

UpStream 协议(protobuf 结构)

message WnsAppUpstream
 {
     required uint32 seq     = 1;                //序列号回包时对应
     required uint32 appid     = 2;              //业务的appid
     required uint64 wid     = 3;                //wns id代表一个wns的链接可以发push用
     required string qua     = 4;                //qua信息
     required string service_cmd = 5;        //sdk接口传入的命令字
     required string device_info     = 6;  //设备信息 imei/os/机型/分辨率
     optional WnsAppClientIpInfo ip_info    = 7;    //客户端IP信息
     required bytes busi_buff     = 8;          //sdk接口传入的业务buf
     optional string uid  = 9;                  //开发商sdk调用bind的用户id
     optional UserAgent user_agent = 10; //标识终端版本号、渠道号
 };
message WnsAppClientIpInfo
 {
     enum IpType{
         IPV4    = 1;
         IPV6    = 2;
     }//1表示IPv4 2表示IPv6
     optional IpType ip_type        = 1;
     optional int32 client_port    = 2;    //客户端端口
     optional string client_ip    = 3;      //如:IPV4:10.6.1.1 ipv6: fe80::2e0:81ff:feda:202d
 };
message UserAgent
 {
     required int32 platform        = 1;      //平台区分 0:ios 1:android
     optional string version        = 2;      //版本号
     optional string channel        = 3;       //渠道名
 };

服务器收包逻辑简介

这里简单说明下开发商服务器如何对接 Wns 二进制协议,开发商服务器可以按下面思路来接收数据包

  1. 接收数据头:数据头长度是 STX+PDU 的长度,一共是 24 个字节,多次收取数据直到大于等于 24 个字节。
  2. 分析协议头:根据 pdu 的协议,获取出 len 字段的长度,获取整个数据包的长度。
  3. 接收完整数据:根据 pdu 头解析出的整个数据包长度,多次收取数据,直到收完整个数据包的长度。
  4. 完整性检查:检查 STX、ETX 来简单判断数据合法性。
  5. ProtoBuf 解析:根据协议获取到 WnsAppUpstream 对应的 buffer,用 ProtoBuf 对这段 buffer 做解码。
  6. 获取业务数据:根据解析出来的 WnsAppUpstream 结构,获取到业务自己的 buffer 数据(busi_buff字段)。
  7. 其他信息获取:根据 WnsAppUpstream,还可以获取到终端的一些信息,比如终端 IP(WnsAppClientIpInfo)、终端设备信息(device_info)、设备标识(wid)等。

DownStream 协议(protobf 结构)

message WnsAppDownstream
{
     required uint32 seq  = 1;                //和UpStream中seq保持一致
     required uint64 wid = 2;                //和UpStream中wid保持一致
     required sint32 biz_code = 3;            //业务返回码 由业务设置。用于wns统计监控使用 0为处理正常,非0为异常
     required string service_cmd = 4;    //和UpStream中service_cmd保持一致
     required bytes busi_buff = 5;            //开发商返回给APP的数据buf 
     optional string err_msg = 6;            //错误信息,biz_code非0的时候填写错误信息提示客户端
     optional string uid = 7;                // 和UpStream中uid保持一致
 };

服务器回包逻辑简介

服务器回包逻辑,只需要按二进制协议规范,将数据打包返回给 Wns 接入服务器即可。返回包中,几个关键数据必须正确。主要包括下面几个

  1. 序列号:WnsAppDownstream 中 seq 字段,必须保证和 WnsAppUpstream 中 seq 字段相同的值。
  2. 设备标识:WnsAppDownstream 中 wid 字段,必须保证和 WnsAppUpstream 中 wid 字段相同的值。
  3. 命令字:WnsAppDownstream 中 service_cmd 字段,必须保证和 WnsAppUpstream 中 service_cmd 字段相同的值。
  4. 用户 ID:WnsAppDownstream 中 uid 字段,必须保证和 WnsAppUpstream 中 uid 字段相同的值。