介绍

CEM JS-SDK是Udesk 面向网页开发者提供的网页开发工具包。

通过使用CEM JS-SDK,网页开发者可借助Udesk CEM系统的能力,为用户提供优质的网页体验。

此文档面向网页开发者介绍CEM JS-SDK如何使用及相关注意事项。

开始使用

集成 JS-SDK

请将以下的页面代码放置到需要集成的页面中的 <head> 和 </head> 标签之间,即可完成页面JSSDK代码的安装,请注意使用前需要先进行初始化(身份认证)

<!-- CEM JS-SDK Reference, More into at https://developer.udesk.cn/cem/jssdk -->
<script type='text/javascript'>
    (function(a,h,c,b,f,g){a["UdeskCEMJSSDKObject"]=f;a[f]=a[f]||function(){(a[f].d=a[f].d||[]).push(arguments)};g=h.createElement(c);g.async=1;g.src=b;c=h.getElementsByTagName(c)[0];c.parentNode.insertBefore(g,c)})(window,document,"script","https://cem.udesk.cn/sdk/jssdk/index.js","udcem");

    udcem('init', {
        projectId: 0,
        appId: 'xxxxxxxxxxxxxxxx',
        //签名参数在这里
    });
</script>
<!-- End CEM JS-SDK Reference -->

初始化(身份认证)

udcem('init', { projectId, appId, nonce, timestamp, customerToken, sign });

参数说明

参数名称 类型 说明 是否必须 备注
projectId Number 项目唯一ID
appId String APPID 获取位置【项目中心>项目列表-管理>发布设置>JS-SDK渠道>编辑】
nonce String 随机数 随机数,动态的比静态随机数安全系数更高
timestamp String 时间戳 当前时间戳(13位毫秒),5分钟有效期
customerToken String 客户唯一标示 客户唯一标示,推荐使用邮箱、手机号等
仅支持字母、数字及下划线,禁用特殊字符
sign String 加密签名 为确保安全,推荐在后端进行加密签名算法,以免数据泄漏或被篡改

加密签名算法

加密签名算法5分钟有效期,过期请重新计算签名,使用setData方法重新设置参数

1、按后面参数及顺序拼接字符,以key=value&形式: noncetimestampcustomerTokenappKey
appKey获取位置【项目中心>项目列表-管理>发布设置>JS-SDK渠道>编辑】,以下以js代码为例

sign = nonce=value&amp;timestamp=value&customerToken=value&appKey

2、使用 sha1 计算出签字符串

sign = sha1(sign)

3、将字符串转换为大写

sign = sign.toUpperCase()

4、示例

sign = "nonce=694db2645b3f69a8&timestamp=18500000000&customerToken=xxxx@udesk.cn&b476f9f8-5309-4d0a-a2d4-af08c4507a15";
sign = sha1(sign);
sign = sign.toUpperCase();

示例

udcem('init', {
    projectId: 0,
    appId: 'xxxxxxxxxxxxxxxx',
    nonce: '694db2645b3f69a8',
    timestamp: '18500000000',
    customerToken: 'xxxx@udesk.cn',
    sign: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
});

设置数据

init方法参数一致,用于切换projectId和appId、签名算法过期等

udcem('setData', { projectId, appId, nonce, timestamp, customerToken, sign });

同步数据

该方法会同步交易(交易明细)、交易类型、客户、员工等数据到服务器端,请谨慎调用,调用时请控制好调用频次

udcem('syncData', { data: { [trade], [tradeType], [user], [member], [projectId], [appId] } }, success, fail, complete);

参数说明

参数名称 类型 说明 是否必须 备注
data Object 传入数据
data.trade Object 交易/订单数据 详见下文
data.tradeType Object 交易类型 详见下文
data.member Object 客户数据 详见下文
data.user Object 员工数据 详见下文
data.projectId Number 项目唯一ID 如果没有传入,则会从init传入的参数中找
data.appId Number APPID 如果没有传入,则会从init传入的参数中找
success Function 同步数据成功回调 详见示例
fail Function 同步数据失败回调 详见示例
complete Function 同步数据结束回调(调用成功、失败都会执行) 详见示例

trade 交易/订单数据 - 参数说明

用于创建交易/订单

参数名称 类型 说明 是否必须 备注
tradeNo String 交易唯一编号 最大长度64个字符
organizationNo String 所属部门/门店编号 最大长度64个字符
amountReceivable String 应收金额(元)
amountReceived String 实收金额(元)
tradeTime String 交易日期,格式: yyyy-MM-dd HH:mm:ss
operateNormalUserNo String 操作员工编号
tradeDetailList Array 交易明细列表 参数见下表

tradeDetailList

参数名称 类型 说明 是否必须 备注
tradeDetailNo String 交易明细唯一编号
organizationNo String 子项所属的部门/门店编号
tradeNo String 子项的交易唯一编号
productNo String 产品唯一编号
tradeTypeNo String 交易类型唯一编号
unitPrice String 产品/商品单价(元)
number Number 产品/商品数量
amountReceivable String 应收小计(元)
amountReceived String 应收小计(元)

tradeType 交易类型 - 参数说明

用于创建交易/订单类型

参数名称 类型 说明 是否必须 备注
tradeTypeNo String 交易类型唯一编号 最大长度64个字符
organizationNo String 所属部门/门店编号 最大长度64个字符
name String 类型名称
description String 类型描述

member 客户数据 - 参数说明

用于创建客户

参数名称 类型 说明 是否必须 备注
memberNo String 客户唯一编号 最大长度64个字符
organizationNo String 所属部门/门店编号 最大长度64个字符
name String 姓名 最大长度128个字符
idCard String 身份证号
birthday String 出生年月日格式: yyyy-MM-dd
address String 家庭地址
mobile String 手机号
gender Number 性别(1-男,2-女)
joinTime String 创建时间,格式: yyyy-MM-dd HH:mm:ss
wxMemberList Array 微信信息列表 参数见下表

wxMemberList

参数名称 类型 说明 是否必须 备注
appId String 对应小程序/公众号appid
openId String 客户的微信openid 注意:appid + openid 是唯一的,如果已经存在则会报错;
headPortraitUrl String 头像链接
nickname String 昵称
mobile String 手机号
gender Number 性别(1-男,2-女)
city String 城市

user 员工数据 - 参数说明

用于创建员工

参数名称 类型 说明 是否必须 备注
userNo String 员工唯一编号 最大长度64个字符
name String 姓名 最大长度128个字符
idCard String 身份证号
birthday String 出生年月日格式: yyyy-MM-dd
address String 家庭地址
mobile String 手机号
email String 邮箱

示例

udcem("syncData", {
    "data": {
        "projectId": 1,
        "member": {
            "address": "北京市海淀区77号",
            "joinTime": "2019-06-29 17:43:23",
            "gender": 1,
            "birthday": "1989-03-07",
            "email": "admin@udesk.cn",
            "idCard": "110101198903071074",
            "memberNo": "C20170809157432",
            "mobile": "18777777777",
            "name": "张三",
            "organizationNo": "000001",
            "wxMemberList": [{
                "appId": "ie982jd8jfe82",
                "city": "湘西",
                "gender": 1,
                "headPortraitUrl": "https://wx.qlogo.cn/mmopen/vi_32/Q0j4TwGTfTJibXjrTzXaQbYu7geRQKPP5ibAB9iaJzKpwDchTLjEFZStBEt45ibqoRtDhsrRllsCAdzLUZa3sXr06g/132",
                "mobile": "18777777777",
                "nickname": "测试微信号",
                "openId": "ie982jd8jfe82d"
            }]
        },
        "trade": {
            "amountReceivable": "9.99",
            "amountReceived": "9.99",
            "memberNo": "C20170809157432",
            "operateNormalUserNo": "1",
            "organizationNo": "000001",
            "tradeDetailList": [{
                "amountReceivable": "9.99",
                "amountReceived": "9.99",
                "number": 3,
                "organizationNo": "000001",
                "productNo": "no.33333",
                "tradeDetailNo": "3",
                "tradeNo": "17",
                "tradeTypeNo": "1",
                "unitPrice": "3.33"
            }],
            "tradeNo": "17",
            "tradeTime": "2019-06-21 10:10:11"
        },
        "tradeType": {
            "description": "分期",
            "name": "6期",
            "organizationNo": "000001",
            "tradeTypeNo": "1"
        }
    },
    "success": function(){ console.log("成功调用"); },
    "fail": function(){ console.log("失败调用"); },
    "complete": function(){ console.log("结束调用"); }
});

显示调研问卷

非单页应用,初始化后随时调用
单页应用,在页面挂载后或触发事件时执行该方法

udcem('show', { [mode], [container], [projectId], [recordId], [style], [alignCenter] });

参数说明

参数名称 类型 说明 是否必须 备注
mode String 显示方式:inner(内嵌)、modal(模态框) 显示方式:inner(内嵌)、modal(模态框),默认模态框显示,内嵌显示需要传入container
container String或Element 显示容积 CSS选择器或Element,用于显示调研问卷内容
projectId Number 项目唯一ID 如果没有传入,则会从init传入的参数中找
appId Number APPID 如果没有传入,则会从init传入的参数中找
recordId String 问卷记录ID 用于显示调研结果
style Object 显示样式 可以自定义设置展示结果的样式,详见示例
alignCenter Object 水平居中显示 该参数会采用margin auto方式水平居中,如有冲突导致无效,可以通过style属性实现
dataParams Object 数据参数 用于显示项目中配置的动态数据 如:交易数据

示例

// 普通显示
udcem('show');

// 显示调研结果
udcem('show', { recordId: 0 });

// 显示自定义样式
udcem('show', {
    style: {
        width: '200px',
        height: '200px'
    }
});

// 同步交易数据成功后显示
udcem('syncData', {
    "data": {
        "tradeType": {
            "description": "分期",
            "name": "6期",
            "organizationNo": "000001",
            "tradeTypeNo": "1"
        }
    },
    "success": function(res){
        // 显示调研问卷
        udcem('show', { dataParams: res.data });
    }
});

隐藏调研问卷

参数说明

参数名称 类型 说明 是否必须 备注
container String或Element 显示容积 CSS选择器或Element,用于隐藏调研问卷内容
udcem('hide');

销毁调研问卷

非单页应用,可以不调用该方法
单页应用,在页面销毁时执行该方法

udcem('destroy');

接受调研问卷提交成功事件

udcem('onSubmitSuccess', fn({ recordId }));

参数说明

参数名称 类型 说明 备注
recordId String 问卷记录ID 用于显示调研的结果,建议存储该参数,方便进入回显使用

示例

udcem('onSubmitSuccess', function(obj){ 
    console.log(obj.recordId);
});

销毁事件

udcem('off', [fn]);

参数说明

参数名称 类型 说明 是否必须 备注
fn Function 接受的事件处理函数

示例

//销毁指定事件
udcem('off', fn);

//销毁所有事件
udcem('off');

常见问题

基本问题

有些浏览器会有兼容性问题?

推荐使用Chrome 56+浏览器,或使用Firefox 58+,其他浏览器可能有不适配的情况。

支持哪些系统或设备?

目前支持Windows、Mac OS X、Android、IOS等系统。