Udesk ServiceGo Ticket SDK工单插件

您好，欢迎接入Udesk ServiceGo Ticket SDK工单插件, 以下提供基本用法、注意事项、自定义配置等。

一、基本用法

登陆ServiceGo系统管理员账号，在 管理中心 -> 工单插件 ， 配置基本属性后复制代码到网页。

在代码中有几个占位符必须填写，timestamp和signature，具体规则请参考下面的详细说明。

userIdentity属性也建议一同填写，此属性表示当前登录用户的唯一身份标识，用以获取工单列表以及新建工单时用来关联创建人。如果在首页面渲染时不能获取，也可以在稍后通过setUserIdentity方法进行指定，但需要在向服务器发送实际请求之前完成。

二、注意事项

1、浏览器兼容型

SDK目前支持IE9+(含)的IE浏览器与基于它内核(360/qq/...)、其他主流浏览器(chrome/firefox/...)。

由于IE9浏览器不完全支持 https://developer.mozilla.org/en-US/docs/Glossary/CORS/[W3C CORS标准]， 在IE9上使用SDK时会有一定的限制，即跨域请求的两端必须采取相同的协议。 由于Udesk已经实现了全站HTTPS，并不再对HTTP协议提供支持， 所以您的网站也需要支持HTTPS协议。 如果有可能，建议您升级到IE10或更高版本，以获得最佳的用户体验。

2、优化体验

SDK引入了tiymce富文本编辑器，所以需要引入tiymce.js静态资源文件，默认SDK会自动加载，如果您希望有一个更好的体验， 可以按照以下方式提前引入tiymce.js静态资源文件。

<script src="https://sgo-assets.udesk.cn/sgo-ticket-sdk/1.0.1/js/tiymce.min.js"></script>

三、自定义配置

初始化全局参数

参数名称	类型	值	是否必需	说明
clientAppId	String	系统生成	是	SDK中工单插件的唯一标识，可以在ServiceGo系统中获取
signature	String	签名加密的字符串	是	SDK认证必须的签名，xref:ticket-sdk-custom-signature[查看详情]
timestamp	String	签名加密使用的时间戳字符串	是	生成签名时所需要的时间戳参数，xref:ticket-sdk-custom-signature[查看详情]
userIdentity	String	SDK使用者的标识	是	当前登录用户的唯一标识（邮箱、电话等，请根据您的业务系统进行指定）
position	Objcet	{ position: absolute, right: 0; bottom: 0 }	否	工单插件相对于页面的停靠位置，可以指定相对或绝对定位，在绝对定位时，还可以指定上下左右的位置信息：{ position: relative/absolute; left: 0, right: 0, top: 0, bottom: 0 }
height	String	100%	否	配置自定义SDK高度
width	String	100%	否	配置自定义SDK宽度
theme	String	"default"	否	配置自定义SDK主题。请注意，本插件中并不提供内置的多主题，您可以根据自己的需要设置多主题，然后通过此属性进行切换。
language	String	ZH-CN	否	配置SDK的国际化语言设置，默认语言是中文。目前只支持中文，如果要支持更多语言，请联系Udesk客服。
suppressDeprecationWarning	Boolean	true	否	工单插件提供了一种api检测机制，在日后的新版本中，我们可能会对某些很早期的api调用方式停止支持，同时在工单插件中会进行相应的提示，提示您升级更新的版本。如果您不希望看到这些提醒，可以把本属性设置为false来禁止提醒。

初始化签名认证算法

客户身份认证。SDK首先要做客户身份认证，认证请参考下面的参数以及signature加密算法。

参数名称	类型	值	是否必需	说明
clientAppId	String	系统生成	是	SDK中工单插件的唯一标示
clientAppKey	String	系统生成	是	ServiceGo系统租户秘钥
timestamp	String	时间戳	是	发起请求时的时间戳，从1970-01-01T00:00:00到现在的秒数。所生成签名在服务端会进行时效性验证，有效期是五分钟。

1、按后面参数及顺序拼接字符，以&进行分隔: clientAppId、clientAppKey、timestamp。

signature_content = clientAppId&clientAppKey&timestamp

clientAppId可以在ServiceGo系统中获取，获取方式【管理中心-工单组件-编辑工单组件信息中的Id】。 clientAppKey可以在ServiceGo系统中获取，获取方式【管理中心-系统设置-基本设置信息中的秘钥】。

2、 使用 SHA1 算法计算出签字符串的哈希值

signature_str = sha1(sign_str)

初始化实例代码

Udesk.ticket.sdk.init({
    clientAppId: "XXXXXXX-XXXXXXXXXXX-XXXXXXXX-XXXXXX",
    signature: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    userIdentity: "135XXXXXXXX",
    timestamp: "1510884424",
    position: {
        position: relative
    },
    height: "100%",
    width: "100%",
    theme: "default",
    language: "ZH-CN"
});

方法说明

方法名称	参数	说明
setNewTicketExtraData	{}	设置提交新建工单时的附加数据。通过此方式，您可以在提交新工单时，以编程的方式附加上一些额外的字段。此方法在提交一些UI不可见的字段值时非常有用。
setLocales	{}	此方法允许您修改当前语言下的某些国际化资源。资源都是以key: value对的方式提供。
setUserIdentity	{}	此方法可以指定当前登录用户的唯一身份标识userIdentity，但需要在向服务器发送实际请求之前完成。

四、NewTicket类使用说明

NewTicket类会实例化出来一个新建工单的表单

参数说明

参数名称	类型	值	是否必需	说明
container	Element	document.body	否	实例化表单的父元素
height	String	"100%"	否	配置实例化表单的高度（会覆盖init中的高度）
width	String	"100%"	否	配置实例化表单的宽度（会覆盖init中的宽度）
position	String	{}	否	配置实例化表单的定位样式（会覆盖init中的定位样式）
classNames	String	"test"	否	配置实例化表单的class属性

方法说明

方法名称	参数	说明
destroy	无	销毁渲染出来的NewTicket组件

使用实例

new Udesk.ticket.sdk.NewTicket({
    container: document.body
    height: "100%",
    width: "100%",
    position: {
        position: relative
    },
    classNames: "example"
});

五、TicketList类使用说明

TicketList类会实例化出来一个工单列表的表单，用户可以查看自己新建的工单 点击工单，进入工单详情页面，进行查看工单详细信息、评论工单、查看客服人员对工单的回复情况等。

参数说明

参数名称	类型	值	是否必需	说明
container	Element	[Element body]	否	实例化表单的父元素
height	String	"100%"	否	配置实例化表单的高度（会覆盖init中的高度）
width	String	"100%"	否	配置实例化表单的宽度（会覆盖init中的宽度）
position	String	{}	否	配置实例化表单的定位样式（会覆盖init中的定位样式）
classNames	String	"test"	否	配置实例化表单的class

方法说明

方法名称	参数	说明
destroy	无	销毁渲染出TicketList组件

使用实例

new Udesk.ticket.sdk.TicketList({
    container: document.body
    height: "100%",
    width: "100%",
    position: {
        position: relative
    },
    classNames: "example"
});