Udesk-Customer service solution leader

Introduction

CEM JS-SDK is a web development toolkit provided by Udesk for web developers.

By using the CEM JS-SDK, web developers can leverage the capabilities of the Udesk CEM system to provide users with a high-quality web experience.

This document introduces how to use the CEM JS-SDK and related precautions for web developers.

Getting Started

Integrating JS-SDK

Place the following code between the <head> and </head> tags of the page that needs integration to complete the installation of the page JSSDK code. Please note that initialization (authentication) is required before use.

<!-- 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',
        // Signature parameters here
    });
</script>
<!-- End CEM JS-SDK Reference -->

Initialization (Authentication)

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

Parameter Description

Parameter Name	Type	Description	Required	Remarks
projectId	Number	Unique project ID	Yes
appId	String	APPID	Yes	Obtain from [Feedback Center > Research Management > Find Target Project > Management > Release Settings > JS-SDK]
nonce	String	Random number	No	A dynamic random number is more secure than a static one
timestamp	String	Timestamp	No	Current timestamp (13 digits milliseconds), valid for 5 minutes
customerToken	String	Unique customer identifier	No	Unique customer identifier, recommended to use email, mobile number, etc. Only supports letters, numbers, and underscores; special characters are disabled
sign	String	Encrypted signature	No	To ensure security, it is recommended to perform encryption signature algorithm on the backend to prevent data leakage or tampering

Encryption Signature Algorithm

The encryption signature algorithm has a validity period of 5 minutes. Recalculate the signature when it expires, and use the setData method to reset the parameters.

Concatenate characters according to the parameters and order behind, in the form of key=value&: nonce, timestamp, customerToken, appKey
Get appKey from [Feedback Center > Research Management > Find Target Project > Management > Release Settings > JS-SDK], using JavaScript code as an example:

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

Calculate the SHA1 hash value of the concatenated string:

sign = sha1(sign)

Convert the string to uppercase:

sign = sign.toUpperCase()

Example

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

Example

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

Setting Data

Consistent with init method parameters, used to switch projectId and appId, and the expiration of the signature algorithm, etc.

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

Sync Data

This method will synchronize transaction (transaction details), transaction type, customer, employee, and other data to the server. Please use it with caution. Control the call frequency when calling.

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

Parameter Description

Parameter Name	Type	Description	Required	Remarks
data	Object	Incoming data	Yes
data.trade	Object	Transaction/order data	No	See below
data.tradeType	Object	Transaction type	No	See below
data.member	Object	Customer data	No	See below
data.user	Object	Employee data	No	See below
data.projectId	Number	Unique project ID	No	If not passed, it will be found from the parameters passed in init
data.appId	Number	APPID	No	If not passed, it will be found from the parameters passed in init
success	Function	Sync data success callback	No	See example
fail	Function	Sync data failure callback	No	See example
complete	Function	Sync data completion callback (will be executed whether successful or not)	No	See example

trade Transaction/Order Data - Parameter Description

Used to create transactions/orders.

Parameter Name	Type	Description	Required	Remarks
tradeNo	String	Unique transaction number	Yes	Maximum length of 64 characters
organizationNo	String	Department/store number	Yes	Maximum length of 64 characters
amountReceivable	String	Amount receivable (in yuan)	No
amountReceived	String	Amount received (in yuan)	No
tradeTime	String	Transaction date, format: `yyyy-MM-dd HH:mm:ss`	No
operateNormalUserNo	String	Employee number	Yes
tradeDetailList	Array	List of transaction details	No	Parameters see below

tradeDetailList

Parameter Name	Type	Description	Required
tradeDetailNo	String	Unique transaction detail number	Yes
organizationNo	String	Department/store number	Yes
tradeNo	String	Unique transaction number	No
productNo	String	Unique product number	No
tradeTypeNo	String	Unique transaction type number	No
unitPrice	String	Product/unit price (in yuan)	No
number	Number	Number of products/items	No
amountReceivable	String	Subtotal receivable (in yuan)	No
amountReceived	String	Subtotal received (in yuan)	No

tradeType Transaction Type - Parameter Description

Used to create transaction/order types.

Parameter Name	Type	Description	Required	Remarks
tradeTypeNo	String	Unique transaction type number	Yes	Maximum length of 64 characters
organizationNo	String	Department/store number	Yes	Maximum length of 64 characters
name	String	Type name	No
description	String	Type description	No

member Customer Data - Parameter Description

Used to create customers.

Parameter Name	Type	Description	Required	Remarks
memberNo	String	Unique customer number	Yes	Maximum length of 64 characters
organizationNo	String	Department/store number	Yes	Maximum length of 64 characters
name	String	Name	Yes	Maximum length of 128 characters
idCard	String	ID card number	No
birthday	String	Date of birth, format: `yyyy-MM-dd`	No
address	String	Home address	No
mobile	String	Mobile number	No
gender	Number	Gender (1-male, 2-female)	No
joinTime	String	Creation time, format: `yyyy-MM-dd HH:mm:ss`	No
wxMemberList	Array	WeChat information list	No	See below

wxMemberList

Parameter Name	Type	Description	Required	Remarks
appId	String	Corresponding mini program/public account appid	Yes
openId	String	Customer's WeChat openid	Yes	Note: appid + openid is unique. If it already exists, an error will occur;
headPortraitUrl	String	Avatar link	No
nickname	String	Nickname	No
mobile	String	Mobile number	No
gender	Number	Gender (1-male, 2-female)	No
city	String	City	No

user Employee Data - Parameter Description

Used to create employees.

Parameter Name	Type	Description	Required	Remarks
userNo	String	Unique employee number	Yes	Maximum length of 64 characters
name	String	Name	Yes	Maximum length of 128 characters
idCard	String	ID card number	No
birthday	String	Date of birth, format: `yyyy-MM-dd`	No
address	String	Home address	No
mobile	String	Mobile number	No
email	String	Email address	No

Example

udcem("syncData", {
    "data": {
        "projectId": 1,
        "member": {
            "address": "77 Haidian District, Beijing",
            "joinTime": "2019-06-29 17:43:23",
            "gender": 1,
            "birthday": "1989-03-07",
            "email": "admin@udesk.cn",
            "idCard": "110101198903071074",
            "memberNo": "C20170809157432",
            "mobile": "18777777777",
            "name": "Zhang San",
            "organizationNo": "000001",
            "wxMemberList": [{
                "appId": "ie982jd8jfe82",
                "city": "Xiangxi",
                "gender": 1,
                "headPortraitUrl": "https://wx.qlogo.cn/mmopen/vi_32/Q0j4TwGTfTJibXjrTzXaQbYu7geRQKPP5ibAB9iaJzKpwDchTLjEFZStBEt45ibqoRtDhsrRllsCAdzLUZa3sXr06g/132",
                "mobile": "18777777777",
                "nickname": "Test WeChat",
                "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": "Installment",
            "name": "6 installments",
            "organizationNo": "000001",
            "tradeTypeNo": "1"
        }
    },
    "success": function(){ console.log("Successfully called"); },
    "fail": function(){ console.log("Failed call"); },
    "complete": function(){ console.log("End call"); }
});

Display Survey Questionnaire

For non-single-page applications, call at any time after initialization.
For single-page applications, execute this method after the page is mounted or when an event is triggered.

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

Parameter Description

Parameter Name	Type	Description	Required	Remarks
mode	String	Display mode: inner(embedded) or modal(modal box)	No	Default is modal display. For embedded display, pass container
container	String or Element	Display container	No	CSS selector or Element, used to display survey questionnaire content
projectId	Number	Unique project ID	No	If not passed, it will be taken from the parameters passed by init
appId	Number	APPID	No	If not passed, it will be taken from the parameters passed by init
recordId	String	Survey record ID	No	Used to display survey results
style	Object	Display style	No	Customize the style of the displayed results, see example for details
alignCenter	Object	Display horizontally centered	No	This parameter will center horizontally using margin auto. If it conflicts and becomes invalid, you can implement it through the style attribute
dataParams	Object	Data parameters	No	Used to display dynamically configured data in the project, e.g., transaction data

Example

// Normal display
udcem('show');

// Display survey results
udcem('show', { recordId: 0 });

// Display custom style
udcem('show', {
    style: {
        width: '200px',
        height: '200px'
    }
});

// Display after successful synchronization of transaction data
udcem('syncData', {
    "data": {
        "tradeType": {
            "description": "Installment",
            "name": "6 installments",
            "organizationNo": "000001",
            "tradeTypeNo": "1"
        }
    },
    "success": function(res){
        // Display survey questionnaire
        udcem('show', { dataParams: res.data });
    }
});

Hide Survey Questionnaire

Parameter Description

Parameter Name	Type	Description	Required	Remarks
container	String or Element	Display container	No	CSS selector or Element, used to hide the survey questionnaire content

udcem('hide');

Destroy Survey Questionnaire

For non-single-page applications, you can skip this method.
For single-page applications, execute this method when the page is destroyed.

udcem('destroy');

Accept Survey Submission Success Event

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

Parameter Description

Parameter Name	Type	Description	Remarks
recordId	String	Survey record ID	It is recommended to store this parameter for easy retrieval when displaying

Example

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

Destroy Event

udcem('off', [fn]);

Parameter Description

Parameter Name	Type	Description	Required	Remarks
fn	Function	Event handling function	No

Example

// Destroy a specified event
udcem('off', fn);

// Destroy all events
udcem('off');

Frequently Asked Questions

Basic Questions

Are there compatibility issues with some browsers?

We recommend using Chrome 56+ or Firefox 58+. Other browsers may have compatibility issues.

Which systems or devices are supported?

Currently supports Windows, Mac OS X, Android, iOS, and other systems.

Introduction

Getting Started

Integrating JS-SDK

Initialization (Authentication)

Parameter Description

Encryption Signature Algorithm

Example

Setting Data

Sync Data

Parameter Description

trade Transaction/Order Data - Parameter Description

tradeType Transaction Type - Parameter Description

member Customer Data - Parameter Description

user Employee Data - Parameter Description

Example

Display Survey Questionnaire

Parameter Description

Example

Hide Survey Questionnaire

Parameter Description

Destroy Survey Questionnaire

Accept Survey Submission Success Event

Parameter Description

Example

Destroy Event

Parameter Description

Example

Frequently Asked Questions

Basic Questions

Are there compatibility issues with some browsers?

Which systems or devices are supported?

Products

Solutions

Resources