一洽|Echat客服系统会员系统接入

1.消息加解密说明

什么是EncodingAESKey?
一洽采用AES对称加密算法对消息体对行加密,EncodingAESKey则是加密所用的秘钥。消息接收方用此秘钥对收到的密文消息体进行解密。

消息加解密过程和微信公众平台的消息加解密方式一致。
示例代码(包括C++、php、Java、Python和C#版本)示例代码
注:一洽的签名信息在GET请求中,微信的示例代码签名在XML结构中,Encrypt节点的加解密方式是一样的。

Java要求jdk 1.6及1.6以上
异常java.security.InvalidKeyException:illegal Key Size的解决方案:在官方网站下载JCE无限制权限策略文件(请到官网下载对应的版本, 例如JDK7的下载地址:http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html 下载后解压,可以看到local_policy.jar和US_export_policy.jar以及readme.txt,如果安装了JRE,将两个jar文件放到%JRE_HOME%\lib\security目录下覆盖原来的文件;如果安装了JDK,将两个jar文件放到%JDK_HOME%\jre\lib\security目录下覆盖原来文件

2.访客端集成会员信息

网页代码中集成会员系统时设置metaData参数将会员信息通过加密的方式通知一洽访客的会员身份。
示例:

<script type="text/javascript">
    var _echatServer = ['e.echatsoft.com'];
    window._echat=window._echat||function(){(_echat.q=_echat.q||[]).push(arguments)};_echat.l=+new Date;
    _echat('initParam', { companyId: 1});
    _echat('initParam', { metaData: 'OAQpxXDnQkjEaj2GhX0ShpXhteq4pw5kHnU9mIQgN+O1R1XiTa9DL8/HVGvIeyXEOr2Fgcfyb2ufwauFyLRdIXBBNc1rIO9Bklz/DQ2UiiY'});
    (function () {
        var echat = document.createElement('script');
        echat.type = 'text/javascript';
        echat.async = true;
        echat.id = 'echatmodulejs';
        echat.setAttribute('charset','UTF-8');
        echat.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'es.echatsoft.com/visitor/echat.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(echat, s);
    })();
</script>

如果是自定义对话窗口链接,在打开的对话窗口地址中追加metaData。
示例:

https://es.echatsoft.com/visitor/pc/chat.html?companyId=1&metaData=OAQpxXDnQkjEaj2GhX0ShpXhteq4pw5kHnU9mIQgN+O1R1XiTa9DL8/HVGvIeyXEOr2Fgcfyb2ufwauFyLRdIXBBNc1rIO9Bklz/DQ2UiiY

会员信息接入时可携带的信息列表如下:

属性 类型 限制 含义
vip int >0 当前客户信息是否为会员客户信息,如果为会员客户信息,那么所有渠道(PC、手机、app、微信D)的访客身份将保持统一一洽会识别为同一个访客。
1:会员 2:非会员 默认为1。如果传递的客户信息为非会员信息那么会员的访客ID则使用一洽识别的当前渠道ID
uid String 最长不超过50位 会员的唯一值 (vip=1时必须)支持数字、英文大小写、字符。 其中支持字符如下:!,#,$,(,),*,+,-,.,@,_,{,~,} 传入不支持字符当做匿名访客处理
grade String 0,1,2 .... 会员级别
category String 最长不超过50位 会员类别 例如:金牌会员
name String 最长不超过50位 会员姓名 例如:王宝强
nickName String 最长不超过50位 会员的昵称 例如:宝宝
gender int >=0 会员的性别,0-未知, 1-男, 2-女
age int >=0 <=100 会员的年龄
birthday String 格式yyyy-MM-dd 会员的生日 例如:2015-08-01
maritalStatus int >=0 婚姻状况 1:未婚 2:已婚 0:未知
phone String 最长不超过50位 会员的联系电话
qq String 最长不超过50位 会员的QQ
wechat String 最长不超过50位 会员的微信
email String 最长不超过50位 会员的邮件地址
nation String 最长不超过50位 会员的国家
province String 最长不超过50位 会员的身份
city String 最长不超过50位 会员的城市
address String 最长不超过255位 会员地址
photo String 最长不超过255位 会员头像地址
c1-c20 String 最长不超过255位 自定义参数
memo String 最长不超过255位 会员备注信息

密文会员信息生成过程:
1.将需要传递给一洽的用户信息组装成XML
如:

<xml>
    <uid><![CDATA[1314521]]></uid>
    <grade><![CDATA[1]]></grade>
    <category><![CDATA[金牌会员]]></category>
    <name><![CDATA[王宝强]]></name>
    <nickName><![CDATA[宝宝]]></nickName>
    <gender><![CDATA[1]]></gender>
    <age><![CDATA[36]]></age>
    <birthday><![CDATA[2015-08-01]]></birthday>
    <maritalStatus><![CDATA[2]]></maritalStatus>
    <phone><![CDATA[18990987546]]></phone>
    <qq><![CDATA[9876389]]></qq>
    <wechat><![CDATA[echatsoft]]></wechat>
    <email><![CDATA[9876389@qq.com]]></email>
    <nation><![CDATA[中国]]></nation>
    <province><![CDATA[广东]]></province>
    <city><![CDATA[深圳]]></city>
    <address><![CDATA[深南大道金融街]]></address>
    <photo><![CDATA[http: // www.baidu.com/mypic.png]]></photo>
    <c1-c20><![CDATA[自定义参数]]></c1-c20>
    <memo><![CDATA[娱乐明星]]></memo>
</xml>

2.通过AES将明文xml进行加密
下面所有的加密示例所使用的的appid和encodingAesKey如下:

appId:myAPPID
encodingAesKey:43weiyiqiaencodingAesKey1111111111111111111

加密结果如下:

0A4VLxGwQzknqYdZdW2x5C87vcil8NSNL1iHENzLnNtv0wPAORT1i19lT6pbCWeipnDfiweDhohdzEbyu0x1JWM2zv+e4fvMy/mLlJFxLEUN9OhHRsgSd44Fnr0wKQWgBYEpabTB0bzkbcO7Spx0yIZU1UePcyY/GPeKe+cgHt4UT8v6LOF1Ff6tg8aA/WlPN89CjprHIWftak7REm8WnfnnQ0/GVXJ0lBEfhV2D8Wra6mKPslcmyyt3z6KbLxaU2KJffLYepUv85nruq1pQ6h90Bx18w4+uH2hzYbKFFqIeREAtS7T348AuydYIcmF3LNu+J9O3RVdDiO4rFJ365SDHyd0Re7t+fiA7qWb8TsFmJQAKMZDW9RP5RmuMUmB3aUIJD+D4oA4nJwYzAeZiQPvHp7ulZ0M2uwO3HhAOIC1bsnNbkkD3Ba9d8OcNIsMGObzMEwPlm8zrr07Mnegn1HyN6Z1e5l8bH/FcEqoK6dX9UUJjDyv/XO+Qe8Xc5jvUk3XRgCARlE10rTj4cw8URG1TEwyxcPKt5zmTnbDtZsoGeQXuGGfjVpJ+LdYIQBM6ju+NFDAAHBX0hUZ9ENW7tMA7OAa0mLxtfDvr3j6JvbrLuFAwglFaCH5xnky7mNC6AajqbK8qCMEk/RconWmEFjTAGjenW59ZVftkooI6IfCB5lCv+/1sn4/ANcE0ik97E3RFIGAAnlldnVa7218nx12VYFz8XwdyAMQMZrsyD94qTHtwrSBjwPctfnsc7j0k2wVACmGJs3EBS5VJjrmOBIf7vutP+BGQFdbg9+AgRv2cPpax36TSbdjIxytJDZTXRUgsdk0nOJGq3dDLk+KmUEehY3GYWasYVMyYzLLGEnCnWFQzZjFzB3MBVcJPd35qsiKIFn1PsBdEU+L854U9HRc9S1yFsp9CtbrRv9zBNpX+uUOowheA4bS3ali8paRSPIvYsxYlM0WlFtVc+mOBUFfPLZLSsoEvH9PI++Rh/DeUIsZZkftxEnwmudgtxVK+p42w9lGEayKtuUF2ZrUNGislCR3rCrdN4fy3fglDfZ4=

注: 通过参数传递给一洽的metaData要进行urlEncode进行utf8编码后传参,避免特殊字符导致截断解密失败。

3.访客端自定义业务数据

在网页代码或者自定义对话链接的窗口地址中可设置参数myData来传递自定义的业务数据,数据格式明文密文根据业务要求开发者自行决定。一洽在收到myData信息后会将myData的数据原样传给客户端内集成的业务系统页面。

myData长度限制:500 超过长度后对话期间的数据传输不受影响,数据归档中使用myData会有影响,一洽在做历史记录持久化的时候会做截断处理。

示例:

<script type="text/javascript">
    var _echatServer = ['e.echatsoft.com'];
    window._echat=window._echat||function(){(_echat.q=_echat.q||[]).push(arguments)};_echat.l=+new Date;
    _echat('initParam', { companyId: 1});
    _echat('initParam', { metaData: 'OAQpxXDnQkjEaj2GhX0ShpXhteq4pw5kHnU9mIQgN+O1R1XiTa9DL8/HVGvIeyXEOr2Fgcfyb2ufwauFyLRdIXBBNc1rIO9Bklz/DQ2UiiY'});
    _echat('initParam', { myData: 'myData'});
    (function () {
        var echat = document.createElement('script');
        echat.type = 'text/javascript';
        echat.async = true;
        echat.id = 'echatmodulejs';
        echat.setAttribute('charset','UTF-8');
        echat.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'es.echatsoft.com/visitor/echat.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(echat, s);
    })();
</script>

对话窗口地址示例:

https://es.echatsoft.com/visitor/pc/chat.html?companyId=1&metaData=OAQpxXDnQkjEaj2GhX0ShpXhteq4pw5kHnU9mIQgN+O1R1XiTa9DL8/HVGvIeyXEOr2Fgcfyb2ufwauFyLRdIXBBNc1rIO9Bklz/DQ2UiiY&myData=network%3Dwifi%26game%3D%E6%96%97%E5%9C%B0%E4%B8%BB%26ver%3D9%2E2%26os%3Dios10

4. demo代码下载

说明:可下载对应语言的demo工程,直接在项目上修改即可快速实现会员接入以及业务系统对接。

4.1 JAVA demo下载

说明:可下载对应语言的demo工程,直接在项目上修改即可快速实现会员接入以及业务系统对接。
4.1 JAVA demo下载
下载地址:java demo

5.业务系统集成流程