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.













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

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

    (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;
      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;
      scriptDom.addEventListener('load', function() {
          var udesk = UdeskSDK.ticketSDK.init({
              // [Required] Must provide subdomain.
              subdomain:'your subdomain',
              // [Required] Must provide client appId.
              // [Required] Must provide signature.
              signature: 'your signature',
              // [Required] Must provide type.
              type:'content type',
              // [Required] Must provide content.
          // Your code goes here...
      }, false);

Custom Configuration

Initialize Global Parameters

Parameter NameTypeValueRequiredDescription
subdomainStringDomainYesCompany's full domain
appidStringSystem-generatedYesUnique identifier for the ticket plugin in the SDK
signatureStringEncrypted stringYesSignature required for SDK authentication, see details
typeStringtoken/email/weixinYesType value range
contentStringType valueYesValue corresponding to the type, used for signature calculation
positionObject{ position: absolute, right: 0; bottom: 0 }NoDocking 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 }
heightString100%NoConfigure custom SDK height
widthString100%NoConfigure custom SDK width
themeString"default"NoConfigure 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.
langStringZH-CN/EN-USNoConfigure SDK internationalization language settings, the default language is Chinese.
defaultFormDataObject{ textField_id: 'Ticket Subject', selectField_id: 'Text Field' }NoSet 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.
defaultUserDataObject{ cellphone: '123123131231', email: 'yao@udesdsdfsf.com'}NoSet 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.
snapshotBooleanfalseNoWhether to enable ticket screenshot function
snapshotOptionObject{ useCORS: true, allowTaint: false }NoScreenshot 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

    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 NameTypeValueRequiredDescription
appidStringSystem-generatedYesUnique identifier for the ticket plugin in the SDK
token (Type)Stringcustomer_tokenNoCustomer identifier
cellphone (Type)StringcellphoneNoCustomer's main phone number
email (Type)StringemailNoCustomer's main email
weixin (Type)Stringcontact_weixins.openidNoWeChat's appid + "#" + openid

Signature Algorithm

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


  • 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({
    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.


  • 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 NameTypeValueDescription
useCORSBooleanfalseWhether to enable CORS for rendering images
allowTaintBooleanfalseWhether 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.
scaleNumber2Scaling level when rendering tags
ignoreElementsFunctionHTMLElement => BooleanTags 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.
beforeSnapFunction() => Callback function before screenshot starts. Return false to abort.
afterSnapFunction() => Callback after screenshot ends, before the image editing modal pops up. Indicates the end of the screenshot and the start of editing the image.


  • 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 NameParametersDescription
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})
hideStringHide 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.
showStringShow the hidden corresponding type of component. The optional values for the parameter are: new/list/detail. Show all hidden components.
destroyStringDestroy 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 NameTypeValueRequiredDescription
typenew/list/detailYesGenerate ticket page for the corresponding type
ticketIdNumbernumberNoRequired when type is detail
containerElement/String[Element body]NoDefault container body node. Can set id value and DOM object. (Will override the container value in init)
heightString"100%"NoConfigure the height of the instantiated form (will override the height in init)
widthString"100%"NoConfigure the width of the instantiated form (will override the width in init)
positionStringNoConfigure the positioning style of the instantiated form (will override the positioning style in init)
classNamesString"test"NoConfigure 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 NameParametersDescription
setDefaultFormDataSet 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
            type: 'new',
            container: document.body,
        height: "100%",
        width: "100%",
        position: {
            position: "relative"
        // Ticket details
            type: 'detail',
            ticketId: 10,
            container: 'sdk'// Container id value,
        height: "100%",
        width: "100%",
        position: {
            position: "relative"