CEM JS-SDK技術文書 - Udesk | 開発者センター

紹介

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メソッドを使用してパラメータを再設定してください。

以下のパラメータを指定された順序で key=value& 形式で連結します: nonce、timestamp、customerToken、appKey
appKeyは【フィードバックセンター > 調査管理 > 対象プロジェクトを選択 > 管理 > 公開設定 > JS-SDK】で取得できます。以下はJavaScriptコードの例です。

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

sha1を使用して署名文字列を計算します。

sign = sha1(sign)

文字列を大文字に変換します。

sign = sign.toUpperCase()

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

例

udcem('init', {
    projectId: 0,
    appId: 'xxxxxxxxxxxxxxxx',
    nonce: '694db2645b3f69a8',
    timestamp: '1850000000000',
    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	都市	いいえ
#### ユーザー従業員データ - パラメータ説明

従業員の作成に使用します

パラメータ名	タイプ	説明	必須かどうか	備考
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": "テスト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": "分割払い",
            "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などのシステムをサポートしています。

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

紹介

使い始める

JS-SDKの統合

初期化（認証）

パラメータ説明

例

データ設定

データ同期

パラメータ説明

member 顧客データ - パラメータ説明

サンプルコード

調査アンケートを表示

パラメータ説明

例

調査アンケートを非表示にする

パラメータ説明

調査アンケートを破棄する

調査アンケートの送信成功イベントを受け取る

パラメータ説明

例

イベントを破棄する

パラメータ説明

例

よくある質問

基本問題

一部のブラウザで互換性の問題がありますか？

どのシステムやデバイスをサポートしていますか？

文档反馈