Udesk-Customer service solution leader

Hello, welcome to connect to the ticket SDK. Below are provided basic usage, precautions, parameter descriptions, method descriptions, event descriptions, related examples, etc.

Basic Usage

Step 1: Configure SDK

Log in to the Udesk customer service system administrator account, go to Admin Center -> Channel Management -> Ticket SDK, and configure the basic properties.

Step 2: Call SDK

Copy the code from basic information to the bottom of the webpage, modify the configuration parameters, call the corresponding method to use the SDK.

Example

Desktop

udesk

Mobile

udesk

Precautions

Device Support

The ticket SDK currently supports PC/Android (including tablets)/IOS (including tablets) and other devices.

Browser Support

Currently supported browsers include IE9+ (inclusive) and other mainstream browsers (Chrome/Firefox/...).

Due to incomplete support for CORS (W3C CORS standard) on IE9, there are limitations when using the SDK on IE9, i.e., both ends of cross-domain requests must adopt the same protocol.

If possible, it is recommended to upgrade to IE10 or higher for the best user experience.

Third-party Libraries

The ticket SDK depends on the third-party library jQuery. Please include jQuery in your website, or uncomment the jQuery reference in the ticket SDK plugin code.

Basic Example

Embedded Code Example

<body>
    <!-- Web page content, please copy the specific code at the administrator ticket SDK plugin -->

    <script>
    (function() {
      var token = "" + (token = new Date()).getFullYear() + token.getMonth() + token.getDate();

      /* if your website does not introduce jQuery, please cancel the following annotation code.*/

      // var scriptDom = document.createElement("script");
      // scriptDom.src = "https://assets-cli.udesk.cn/ticket_js_sdk/static/vendor/js/jquery.min.js?t="+token;
      // document.body.appendChild(scriptDom);

      var scriptDom = document.createElement("script");
      scriptDom.src = "https://assets-cli.udesk.cn/ticket_js_sdk/1.0.1/js/sdk.min.js?t="+token;
      document.body.appendChild(scriptDom);
      var styleDom = document.createElement("link");
      styleDom.rel = "stylesheet";
      styleDom.href = "https://assets-cli.udesk.cn/ticket_js_sdk/1.0.1/css/sdk.min.css?t="+token;
      document.body.appendChild(styleDom);
      scriptDom.addEventListener('load', function() {
          var udesk = UdeskSDK.ticketSDK.init({
              // [Required] Must provide subdomain.
              subdomain:'your subdomain',
              // [Required] Must provide client appId.
              appid:'f840xxxxxx5f868e',
              // [Required] Must provide signature.
              signature: 'your signature',
              // [Required] Must provide type.
              type:'content type',
              // [Required] Must provide content.
              content:'content',
              container:'sdk'
          });
          // Your code goes here...
          udesk.create({
            type:'new'
          })
      }, false);
  })();
    </script>
</body>

Custom Configuration

Initialize Global Parameters

Parameter Name	Type	Value	Required	Description
subdomain	String	Domain	Yes	Company's full domain
appid	String	System-generated	Yes	Unique identifier for the ticket plugin in the SDK
signature	String	Encrypted string	Yes	Signature required for SDK authentication, see details
type	String	token/email/weixin	Yes	Type value range
content	String	Type value	Yes	Value corresponding to the type, used for signature calculation
position	Object	{ position: absolute, right: 0; bottom: 0 }	No	Docking position of the ticket plugin relative to the container, can specify relative or absolute positioning, in absolute positioning, you can also specify top, bottom, left, and right position information: { position: relative/absolute; left: 0, right: 0, top: 0, bottom: 0 }
height	String	100%	No	Configure custom SDK height
width	String	100%	No	Configure custom SDK width
theme	String	"default"	No	Configure custom SDK theme. Please note that this plugin does not provide built-in multiple themes. You can set multiple themes according to your needs and switch them through this attribute.
lang	String	ZH-CN/EN-US	No	Configure SDK internationalization language settings, the default language is Chinese.
defaultFormData	Object	{ textField_id: 'Ticket Subject', selectField_id: 'Text Field' }	No	Set additional fields for ticket submission. These fields will be uploaded along with ticket fields. If they overlap with ticket fields, the values in this field will override the values entered in the ticket.
defaultUserData	Object	{ cellphone: '123123131231', email: 'yao@udesdsdfsf.com'}	No	Set additional customer fields for ticket submission. These fields will be uploaded along with customer fields. If they overlap with customer fields, the values in this field will override the values entered in the ticket.
snapshot	Boolean	false	No	Whether to enable ticket screenshot function
snapshotOption	Object	{ useCORS: true, allowTaint: false }	No	Screenshot function configuration parameters

defaultFormData can be used to set values for fields that do not exist in the ticket, and will be submitted along with the ticket fields. If there is a conflict with the ticket fields, the values in defaultFormData will be used.

defaultUserData When customer email and phone number fields are submitted and conflict with signature authentication parameters, the signature authentication parameters will prevail.

defaultUserData involves customer parameters: email (customer email field), cellphone (customer phone number field), name (customer name field), organization (customer company field), SelectField_id and TextField_id (customer custom field unique identifier, can be viewed in custom fields). All of the above field types are String.

defaultUserData Example

defaultUserData:{
    cellphone:  '123123131231',
        email:      'yao@udesdsdfsf.com',
        nick_name:  'Jack',
        organization: 'test company',
        TextField_325: 'Multiple lines of text',
        SelectField_189: '0',
        SelectField_185: '0',
        TextField_321: 'https://www.baidu.com',
        TextField_317: '123',
        TextField_313: '42342',
        TextField_309: '2017-01-01 00:00',
        TextField_305: '12:00:00',
        TextField_301: '2016/01/01',
        SelectField_177: '0',
        TextField_297: 'Customer field',
}

Initialize Signature Authentication Algorithm

Customer identity authentication. The SDK first needs to perform customer identity authentication. For authentication, please refer to the following parameters and the signature encryption algorithm. One of token, email, and weixin is required.

Type and Content Parameter Explanation

Parameter Name	Type	Value	Required	Description
appid	String	System-generated	Yes	Unique identifier for the ticket plugin in the SDK
token (Type)	String	customer_token	No	Customer identifier
cellphone (Type)	String	cellphone	No	Customer's main phone number
email (Type)	String	email	No	Customer's main email
weixin (Type)	String	contact_weixins.openid	No	WeChat's appid + "#" + openid

Signature Algorithm

Username: appid&Type&Content
Algorithm: SHA256(Username + "&" + appkey)

Note:

Signature calculation should be completed on the server side.

If the customer does not exist, it will be automatically created.

Initialize Instance Code

var udesk = UdeskSDK.ticketSDK.init({
    appid: "XXXXXXX-XXXXXXXXXXX-XXXXXXXX-XXXXXX",
    signature: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    type:"xxx"
    content:"xxx",
    subdomain: "xxxx",
    position: {
        position: "relative"
    },
    height: "100%",
    width: "100%",
    theme: "default",
    lang: "ZH-CN"
});

Screenshot Function and Configuration Parameters

When configuring snapshot in global parameters to true, the screenshot function is enabled, and a "Screenshot" button will be displayed after the "Upload Attachment" button. Clicking the "Screenshot" button will capture the current page document.body and pop up an image editing modal. After confirmation, the screenshot will be uploaded and displayed in the attachment list. The screenshot function is implemented based on html2canvas.

Note:

Requires compatibility with canvas-enabled browsers. The "Screenshot" button will not be displayed if not compatible and does not support mobile devices.

The function captures document.body and does not support specifying capture objects.

The position of the image editing modal is full-screen floating position: fixed; z-index: 9999; min-width: 600px;, rendered at the bottom of the body, the size is 80% of the current screen, located in the center of the screen, with a minimum width of 600, not responsive to drag or adapt.

snapshotOption Screenshot Parameter Explanation

Parameter Name	Type	Value	Description
useCORS	Boolean	false	Whether to enable CORS for rendering images
allowTaint	Boolean	false	Whether to allow canvas pollution. When `useCORS` is `true`, `allowTaint` must be `false`. When `allowTaint` is `true`, it will pollute the canvas and make it unreadable.
scale	Number	2	Scaling level when rendering tags
ignoreElements	Function	HTMLElement => Boolean	Tags that need to be filtered during rendering. The callback function parameter is the current rendered DOM tag. When the function returns `true`, this tag will be skipped. When it returns `false` or does not return, the rendering of this tag will continue.
beforeSnap	Function	() =>	Callback function before screenshot starts. Return `false` to abort.
afterSnap	Function	() =>	Callback after screenshot ends, before the image editing modal pops up. Indicates the end of the screenshot and the start of editing the image.

Note:

Except for beforeSnap and afterSnap, other parameters are consistent with html2canvas configuration parameter configuration.

Other html2canvas configuration parameters are also supported.

Passing Screenshot Cross-Origin Configuration

For example, when there is cross-origin with the image server, passing useCORS: true and allowTaint: true is sufficient. When snapshotOption parameter is not passed, the default configuration within the ticket is as follows:

const snapshotOption = {
    useCORS: true,
    allowTaint: false
}

This configuration requires the image server to configure Access-Control-Allow-Origin, and if necessary, set the crossorigin='anonymous' attribute for the Img tag, see MDN CORS enabled image.

Method Explanation

Method Name	Parameters	Description
create	{type:"xxx"}	This method is used to generate ticket-related pages. The optional values for the parameter type are: new/list/detail, where detail requires ticketId to be passed. For example: `udesk.create({type:"detail",ticketId:1})`
hide	String	Hide the corresponding type of component that has been rendered. The optional values for the parameter are: new/list/detail. Leave it blank to hide all components.
show	String	Show the hidden corresponding type of component. The optional values for the parameter are: new/list/detail. Show all hidden components.
destroy	String	Destroy the corresponding type of component that has been rendered. The optional values for the parameter are: new/list/detail. Leave it blank to unregister all components.

Detailed Explanation of the create Method

Parameter Explanation

Parameter Name	Type	Value	Required	Description
type		new/list/detail	Yes	Generate ticket page for the corresponding type
ticketId	Number	number	No	Required when type is detail
container	Element/String	[Element body]	No	Default container body node. Can set id value and DOM object. (Will override the container value in init)
height	String	"100%"	No	Configure the height of the instantiated form (will override the height in init)
width	String	"100%"	No	Configure the width of the instantiated form (will override the width in init)
position	String		No	Configure the positioning style of the instantiated form (will override the positioning style in init)
classNames	String	"test"	No	Configure the class of the instantiated form (will override the height in init)

newTicket Method Explanation

After calling udesk.create({ type:'new' }) method, the udesk object will create the corresponding ticket object udesk.newTicket for ticket field recording and uploading.

udesk.newTicket object provides the following methods

Method Name	Parameters	Description
setDefaultFormData		Set additional fields for ticket submission. Through this method, you can programmatically attach some additional fields when submitting a new ticket. This method is very useful when submitting fields that are not visible in the UI. The parameters are the same as [defaultFormData].

The setDefaultFormData method accepts an object and uses this object to override the defaultFormData field in the init method configuration. Calling this method will invalidate the defaultFormData field in the init method configuration.

Usage Example

    // New ticket
    udesk.create({
            type: 'new',
            classNames:'subdomain-ticket-sdk',
            container: document.body,
        height: "100%",
        width: "100%",
        position: {
            position: "relative"
        },
        });
        // Ticket details
        udesk.create({
            type: 'detail',
            ticketId: 10,
            classNames:'subdomain-ticket-sdk',
            container: 'sdk'// Container id value,
        height: "100%",
        width: "100%",
        position: {
            position: "relative"
        },
        });

Basic Usage

Example

Desktop

Mobile

Precautions

Device Support

Browser Support

Third-party Libraries

Basic Example

Embedded Code Example

Custom Configuration

Initialize Global Parameters

defaultUserData Example

Initialize Signature Authentication Algorithm

Initialize Instance Code

Screenshot Function and Configuration Parameters

snapshotOption Screenshot Parameter Explanation

Passing Screenshot Cross-Origin Configuration

Method Explanation

Detailed Explanation of the create Method

newTicket Method Explanation

Usage Example

Products

Solutions

Resources