web网站接入详细开发文档

简要说明

针对每一个Web渠道，晓多提供了独立可访问的聊天窗口地址，访客在浏览器打开这个地址即可与客服沟通以晓多官网的聊天窗口举例，可直接打开下面地址访问聊天会话窗口：

https://cvd.xiaoduoai.com/?src=15&channel_id=12&key=1e3916388152882324dab168cddd44ee0153f89d8080ab5f73962122cb16caa6

但更多的场景是，开发者想要在自己的网站里面，引用晓多的SDK，来嵌入一个聊天窗口

开发者在接入SDK后，我们会在开发者的网站里面添加一个在线咨询的入口按钮，访客在点击这个按钮时，我们会在开发者的网站里面打开咨询聊天窗口。 (tip: 入口按钮和聊天窗口的样式和位置都可以在晓多管理台-设置-网站对话框自定义里面设置)

下面将详细介绍SDK的嵌入方式和暴露的一些接口

SDK接入说明

SDK有两种接入方式，分别为单渠道接入和多渠道接入。多渠道接入提供了在开发者网站里面同时接入多个web渠道的能力

单渠道接入

在页面中引用SDK代码

    <!-- 举例 -->
    <script type="text/javascript" src="http://cvd.xiaoduoai.com/sdk/sdk.min.js?src=9&key=977b18aaaac8b2e51108da138576743265e1f05b674780a09fd5f3af3475bafa&channel_id=16" defer async></script>

注意：

需要修改sdk引用参数，改为用户自己的Web渠道的相关参数，参见客服管理台-设置-渠道列表-{找到或创建web网站接入渠道}
也支持第三方接入方式的参数，参见http://cvd.xiaoduoai.com/docs/c4.html中关于WEB C端接入的说明

多渠道接入

    <!-- 举例 -->
    <script>
        // 同时接入两个web渠道
        window.__CVD_C_ENTRY_SETTING = [
            'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776',
            'http://cvd.xiaoduoai.com/c?src=439&key=4ca6c1295d9f33ddb226e0247bb862fa3284c19a9218c090adfc1fedf35aae81&channel_id=2777'
         ]
    </script>
    <script type="text/javascript" src="http://cvd.xiaoduoai.com/sdk/sdk.min.js" defer async></script>

注意：

上面的示例是同时接入两个web渠道，window.__CVD_C_ENTRY_SETTING数组的每项值是开发者希望接入的web渠道所对应的聊天会话窗口的URL地址，用户可以在客服管理台-设置-渠道列表里面查看

关于入口按钮

在页面中引入sdk 脚本文件之后，sdk会在页面中添加一个或多个入口按钮(每个渠道一个对应的入口按钮)，点击入口按钮可以打开对应web渠道的聊天会话窗口。

入口按钮的样式和位置可以在晓多管理台-设置-网站对话框自定义里面设置。

开发者若要使用自己的入口按钮，可以把入口按钮隐藏掉，然后通过sdk提供的接口来实现打开或关闭聊天窗的功能

隐藏入口按钮的配置如下

    <script>
        // 在引入sdk之前，定义window.CVD_SDK_CONFIG
        window.CVD_SDK_CONFIG = { hideEntryBtn: true }
    </script>

SDK功能

每个聊天窗口都是一个独立的iframe页面，开发者可以通过sdk的接口来实现iframe窗口页面内部的dom操作或样式定义

sdk暴露了一个全局变量 CVD_SDK，通过这个全局变量，我们可以调用sdk提供的一些接口，实现一些自定义的逻辑

SDK配置

在sdk脚本引入之前，可以在全局定义sdk的配置对象


 // 配置说明

 {
    debugMode: false, // 关闭调试模式， 在调试模式下会有很多控制台日志输出，默认值为true
    hideEntryBtn: true, // 隐藏入口按钮的显示 ( 在用户自定义入口按钮时可以使用这个配置项 )
 }


 // 单渠道配置
 // 举例：

 window.CVD_SDK_CONFIG = { debugMode: false } 这种形式

 // 多渠道配置, 对象的key是开发者接入的渠道的地址， value是配置对象
 // 举例：

 window.CVD_SDK_MULTI_CHANNEL_CONFIG = {
    'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776': { debugMode: false }
  }

SDK准备好时的回调

如果开发者在引入sdk时，希望sdk脚本加载不要影响页面加载时间，可以添加defer async属性，让sdk的js延迟加载。

开发者可以在添加一个全局函数onCvdSdkReady，当sdk加载好以后，会调用此函数

window.onCvdSdkReady = function() {
  // 此时window.CVD_SDK就可用了
  // 举例： 打开聊天窗口
  window.CVD_SDK.openWindow()
}

关闭调试模式，关闭控制台日志输出

引入sdk后，控制台会输出一些调试日志，一般情况下开发者不关心这些日志，可以通过下面的方式关掉日志输出

window.onCvdSdkReady = function() {
  window.CVD_SDK.setDebugMode(false)
}

打开聊天窗口

    // 单渠道接入时
    // 打开聊天窗口
    if (window.CVD_SDK) window.CVD_SDK.openWindow()

    // 多渠道接入时
    // 参数为要打开的渠道对应的聊天会话窗口URL地址
    if (window.CVD_SDK) window.CVD_SDK.openWindow('http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

关闭聊天窗口

    // 单渠道接入时
    // 关闭聊天窗口
    if (window.CVD_SDK) window.CVD_SDK.closeWindow()

    // 多渠道接入时
    // 参数为要关闭的渠道对应的聊天会话窗口URL地址
    if (window.CVD_SDK) window.CVD_SDK.closeWindow('http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

在聊天窗口环境下执行脚本

    // 单渠道接入时
    // 在聊天窗口的iframe内执行代码
    if (window.CVD_SDK) window.CVD_SDK.evalScript('alert("alert from iframe window")')

    // 多渠道接入时
    // 第二个参数为聊天会话窗口URL地址
    if (window.CVD_SDK) window.CVD_SDK.evalScript('alert("alert from iframe window")', 'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

在聊天窗口环境下添加css样式

    // 单渠道接入时
    // 在聊天窗口的iframe内添加css
    if (window.CVD_SDK) window.CVD_SDK.addCssText('#msg_flow{    background-color: red;}')

    // 多渠道接入时
    // 第二个参数为聊天会话窗口URL地址
    if (window.CVD_SDK) window.CVD_SDK.addCssText('#msg_flow{    background-color: red;}', 'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

更新签名

    var sign = { sign: 'xxxx', ts: 'xxxx'}

    // 单渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.updateSign(sign)

    // 多渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.updateSign(sign, 'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

添加参数

注意：添加参数只会在访客会话建立之前(即会话还未生成时)有效

    // 举例， 设置访客昵称和电话
    var querys = { nick: '张三', phone_3rd: 12215593244 }

    // 单渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.addExtraQuerys(querys)

    // 多渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.addExtraQuerys(querys, 'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

获取访客消息未读数

sdk默认引入的入口按钮会显示消息未读数并自动更新。如果开发者要使用自己的入口按钮的话，可以调用这个接口来获取未读数，另外还可以监听unreadCountChange事件来感知未读数变化

    // 单渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.getUnreadCount()

    // 多渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.getUnreadCount('http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

`

发送文本消息

    // 单渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.sendTextMsg(str)

    // 多渠道接入时
    if (window.CVD_SDK) window.CVD_SDK.sendTextMsg(str, 'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

`

新标签页打开聊天窗口

    // 单渠道接入时
    var theWindow = window.CVD_SDK.openWindowInNewTab(windowName, windowFeatures)

    // 多渠道接入时
    var theWindow = window.CVD_SDK.openWindowInNewTab(windowName, windowFeatures, 'http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

`

记录一次最近咨询页

除了调用sdk提供的openWindowInNewTab方法外，用户也可以自己控制打开聊天窗口，然后调用此方法来记录访客的最近咨询页

    // 单渠道接入时
    window.CVD_SDK.addChatTrack()

    // 多渠道接入时
    window.CVD_SDK.addChatTrack('http://cvd.xiaoduoai.com/c?src=439&key=8eeb57f1fa5cdf824707023d383daf906229cfb2b7c3fbf11538c85890a733ad&channel_id=2776')

`

绑定事件

当前sdk提供的事件有：

sendMessage 用户发送消息时触发
message 收到消息时触发
unreadCountChange 未读数更新
windowClosed 窗口关闭
windowOpened 窗口打开
windowExpandStateChange 窗口最大化或还原

多渠道时，支持第三个参数为会话窗口URL地址，针对渠道绑定或解绑事件

    if (window.CVD_SDK) {
      window.CVD_SDK.on('sendMessage', function(msg) {
        console.log(msg)
      })

      // 可以使用once方法，回调函数最多触发一次
      window.CVD_SDK.once('sendMessage', function(msg) {
        console.log(msg)
      })
    }

解绑事件

    window.CVD_SDK.off('sendMessage', someFun)

Web接入详细文档