チケットSDK - Udesk | 開発者センター

こんにちは、チケットSDKへのご導入を歓迎いたします。以下に、基本的な使用方法、注意事項、パラメータ説明、メソッド説明、イベント説明、関連するサンプルなどを提供いたします。

基本的な使用方法

ステップ1：SDKの設定

Udeskカスタマーサポートシステムの管理者アカウントでログインし、管理センター -> チャネル管理 -> チケットSDKで基本プロパティを設定します。

ステップ2：SDKの呼び出し

基本情報にあるコードをWebページの下部にコピーし、設定パラメータ情報を修正して、対応するメソッドを呼び出すことでSDKを使用できます。

効果サンプル

デスクトップ版

udesk

モバイル版

udesk

注意事項

デバイスサポート

チケットSDKは現在、PC/Android(タブレット含む)/iOS(タブレット含む)などのデバイスをサポートしています。

ブラウザサポート

現在、主要なブラウザ(Edge / Chrome / Firefox / IE 11...)をサポートしています。

可能であれば、最適なユーザー体験を得るために、主要なブラウザへのアップグレードをお勧めします。

基本サンプル

埋め込みコードサンプル

<body>
    <!-- ウェブページの内容 具体的なコードは管理者のチケットSDKプラグインでコピーしてください -->

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

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

      var styleDom = document.createElement("link");
      styleDom.rel = "stylesheet";
      styleDom.href = "https://assets-cli.udesk.cn/ticket_sdk/ticket_sdk.css?t="+token;
      document.body.appendChild(styleDom);

      scriptDom.addEventListener('load', function() {
          var udesk = UdeskSDK.ticketSDK.init({
              // [必須] サブドメインを提供する必要があります。
              subdomain:'your subdomain',
              // [必須] クライアントappIdを提供する必要があります。
              appid:'f840xxxxxx5f868e',
              // [必須] 署名を提供する必要があります。
              signature: 'your signature',
              // [必須] タイプを提供する必要があります。
              type:'content type',
              // [必須] コンテンツを提供する必要があります。
              content:'content',
              container:'sdk'
          });
          // ここにコードを記述します...
          udesk.create({
            type:'new'
          })
      }, false);
  })();
    </script>
</body>

カスタム設定

グローバルパラメータの初期化

パラメータ名	タイプ	値	必須	説明
subdomain	String	ドメイン名	必須	会社の完全ドメイン名
appid	String	システム生成	必須	SDK内のチケットプラグインの一意識別子
signature	String	署名で暗号化された文字列	必須	SDK認証に必要な署名、詳細を確認
type	String	token/web_token/email/cellphone/weixin/qywx	必須	タイプの取り得る値の範囲
content	String	タイプに対応する値	必須	対応するタイプの値、signatureの計算に使用
position	Object	{ 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のテーマを設定。本プラグインには組み込みのマルチテーマは提供されていないことにご注意ください。ご自身のニーズに応じてマルチテーマを設定し、このプロパティで切り替えることができます。
lang	String	ZH-CN/EN-US	任意	SDKの国際化言語設定を構成。デフォルト言語は中国語です。
defaultFormData	Object	{ textField_id: 'チケット件名', selectField_id: 'テキストフィールド' }	任意	チケット送信時の追加フィールドを設定。これらのフィールドはチケットフィールドと共にアップロードされます。チケットフィールドと重複する場合、このフィールドの値でチケットに入力されたフィールド値が上書きされます。
defaultUserData	Object	{ cellphone: '123123131231', email: 'yao@udesdsdfsf.com'}	任意	チケット送信時の追加顧客フィールドを設定。これらのフィールドは顧客フィールドと共にアップロードされます。顧客フィールドと重複する場合、このフィールドの値でチケットに入力されたフィールド値が上書きされます。
snapshot	Boolean	false	任意	チケットスクリーンショット機能を有効にするかどうか
snapshotOption	Object	{ useCORS: true, allowTaint: false }	任意	スクリーンショット機能の設定パラメータ

defaultFormData は、チケットに存在しない一部のフィールド値を設定し、送信時にチケットフィールドと共に送信するために使用できます。

defaultFormData は、チケットの一部のフィールドのアップロード時のデフォルト値を設定するために使用できます。これらの値はチケットインターフェースのフィールド値には表示されず、送信時にのみデータマージに使用されます。

defaultFormData で設定されたフィールドがチケットフィールドと重複する場合、チケットページでそのフィールドが入力されているかどうかに関わらず、送信時には defaultFormData のフィールド値が優先されます。

defaultUserData 顧客のメールアドレス、携帯電話番号フィールドの送信時に署名認証パラメータと競合する場合、署名認証が優先されます。

defaultUserData 関連する顧客パラメータは以下の通りです：email(顧客メールアドレスフィールド)、cellphone(顧客携帯電話番号フィールド)、name(顧客名フィールド)、organization(顧客会社フィールド)、SelectField_idおよびTextField_id(顧客カスタムフィールドの一意識別子、カスタムフィールドで確認可能)。上記のフィールドタイプはすべてStringです。

defaultUserDataの例

defaultUserData:{
    cellphone:  '123123131231',
        email:      'yao@udesdsdfsf.com',
        nick_name:  '一万瓶',
        organization: '一万瓶',
        TextField_325: '複数行テキスト',
        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: '顧客フィールド',
}

初期化署名認証アルゴリズム

顧客認証。SDKはまず顧客認証を行う必要があり、認証は以下のパラメータおよびsignature暗号化アルゴリズムを参照してください。token、cellphone、email、weixin、qywxのいずれか一つは必須です。

タイプおよび内容パラメータの説明

パラメータ名	タイプ	値	必須	説明
appid	String	システム生成	はい	SDK内チケットプラグインの一意の識別子
token（タイプ）	String	customer_token	いいえ	顧客外部一意識別子
web_token（タイプ）	String	web_token	いいえ	顧客web識別子
cellphone (タイプ)	String	cellphone	いいえ	顧客の主な携帯電話番号（必須）
email（タイプ）	String	email	いいえ	顧客の主なメールアドレス（必須）
weixin（タイプ）	String	contact_weixins.openid	いいえ	WeChatのappid + "#" +openid
qywx（タイプ）	String	contact_qywx.openid	いいえ	企業WeChatのappid + "#" +openid

署名アルゴリズム

ユーザー名: appid&タイプ&内容
アルゴリズム：SHA256(ユーザー名 + "&" + appkey)

注意:

署名の計算はサーバー側で完了させる必要があります

顧客が存在しない場合は自動的に作成されます

初期化インスタンスコード

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"
});

スクリーンショット機能と設定パラメータ

グローバルパラメータで snapshot を true に設定すると、スクリーンショット機能が有効になります
【ファイルをアップロード】ボタンの後に【スクリーンショット】ボタンが表示されます
【スクリーンショット】ボタンをクリックすると、現在のページの document.body をキャプチャし、画像編集モーダルがポップアップ表示されます
確認後、スクリーンショットがアップロードされ、添付ファイルリストに表示されます
スクリーンショット機能は html2canvas に基づいて実装されています

注意:

Canvas に対応したブラウザが必要です。非対応の場合は【スクリーンショット】ボタンは表示されません。モバイル端末はサポートされていません

この機能のキャプチャ対象は document.body であり、特定のオブジェクトを指定することはできません

画像編集モーダルは全画面フローティングで、 position: fixed; z-index: 9999; min-width: 600px; は body の下部にレンダリングされます。サイズは現在の画面の 80%、画面中央に配置され、最小幅は 600 です。ドラッグやレスポンシブ対応はありません

snapshotOption スクリーンショットパラメータ説明

パラメータ名	型	値	説明
useCORS	Boolean	false	画像レンダリング時に CORS を有効にするか
allowTaint	Boolean	false	キャンバスの汚染を許可するかどうか。 `useCORS` が `true` の場合、 `allowTaint` は `false` でなければなりません。 `allowTaint` が `true` の場合、キャンバスが汚染され読み取り不能になる可能性があります
scale	Number	2	タグをレンダリングする際のスケールレベル
ignoreElements	Function	HTMLElement => Boolean	レンダリング時にフィルタリングするタグ。コールバック関数のパラメータは現在レンダリング中の dom タグです。関数が `true` を返すと、このタグはスキップされます。 `false` を返すか、何も返さない場合は、このタグのレンダリングを続行します
beforeSnap	Function	() => {}	スクリーンショット開始前のコールバック関数。 `false` を返すと終了します
afterSnap	Function	() => {}	スクリーンショット終了後、画像編集モーダル表示前のコールバック。スクリーンショット終了、画像編集開始を示します

注意:

beforeSnap、afterSnap を除き、他のパラメータは html2canvas configuration のパラメータ設定と一致します

他の html2canvas 設定パラメータも同様に渡すことができます

スクリーンショットのクロスオリジン設定の受け渡し

例えば、画像サーバーがクロスオリジンの場合、 useCORS: true と allowTaint: true を渡すだけで済みます
snapshotOption パラメータを渡さない場合、チケット内部では以下の設定がデフォルト構成として使用されます：

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

この設定では、画像サーバーに Access-Control-Allow-Origin の設定が必要です。必要に応じて Img タグの crossorigin='anonymous' を設定する必要があります。詳細は MDN CORS 対応画像を参照してください

メソッド説明

メソッド名	パラメータ	説明
create	{type:"xxx"}	このメソッドはチケット関連ページを生成するために使用されます。パラメータtypeの選択可能な値は：new/list/detailです。detailはticketIdを渡す必要があります。例：udesk.create({type:"detail",ticketId:1})
hide	String	レンダリングされた対応するタイプのコンポーネントを非表示にします。パラメータの選択可能な値は：new/list/detailです。空の場合はすべてのコンポーネントを非表示にします。
show	String	非表示になっている対応するタイプのコンポーネントを表示します。パラメータの選択可能な値は：new/list/detailです。すべての非表示コンポーネントを表示します。
destroy	String	レンダリングされた対応するタイプのコンポーネントを破棄します。パラメータの選択可能な値は：new/list/detailです。空の場合はすべてのコンポーネントを登録解除します。

createメソッド詳細説明

パラメータ説明

パラメータ名	タイプ	値	必須	説明
type	String	new/list/detail	はい	対応するタイプのチケットページを生成します
mode	String	web/mobile	はい	対応するレンダリングモードのチケットページを生成します
ticketId	Number	数字	いいえ	typeの値がdetailの場合、ticketIdは必須です
container	Elment/String	[Element body]	いいえ	デフォルトコンテナbodyノード。id値とDomオブジェクトを設定できます。（init内のコンテナ値を上書きします）
height	String	"100%"	いいえ	インスタンス化されたフォームの高さを設定します（init内の高さを上書きします）
width	String	"100%"	いいえ	インスタンス化されたフォームの幅を設定します（init内の幅を上書きします）
position	String	{}	いいえ	インスタンス化されたフォームの位置スタイルを設定します（init内の位置スタイルを上書きします）
classNames	String	"test"	いいえ	インスタンス化されたフォームのclassを設定します（init内の高さを上書きします）

newTicket メソッド説明

udesk.create({ type:'new' }) メソッドを呼び出した後、udesk オブジェクト内に対応するチケットオブジェクト udesk.newTicket が作成され、チケットフィールドの記録とアップロードに使用されます。
udesk.newTicket オブジェクトは以下のメソッドを提供します。

メソッド名	パラメータ	説明
setDefaultFormData	{}	チケット送信時の追加フィールドを設定します。この方法により、新しいチケットを送信する際に、プログラムでいくつかの追加フィールドを添付することができます。このメソッドは、UIで見えないフィールド値を送信する際に非常に便利です。パラメータは[defaultFormData]と同じです。

setDefaultFormData メソッドはオブジェクトを受け取り、このオブジェクトを使用して init メソッド設定内の defaultFormData フィールドを上書きします。このメソッドを呼び出すと、init メソッド設定内の defaultFormData フィールドが無効になります。

使用例

    //新規チケット作成
    udesk.create({
        type: 'new',
        mode: 'web',
        classNames:'subdomain-ticket-sdk',
        container: 'sdk_new'//コンテナid値,
        height: "100%",
        width: "100%",
        position: {
            position: "relative"
        },
    });
    //チケット詳細
    udesk.create({
        type: 'detail',
        mode: 'web',
        ticketId: 10,
        classNames:'subdomain-ticket-sdk',
        container: 'sdk_detail'//コンテナid値,
        height: "100%",
        width: "100%",
        position: {
            position: "relative"
        },
    });

アップグレードガイド

// 注意：ドメインアドレスは、現在お使いのドメインアドレスを保存してください。ここでは例としてhttps://assets-cli.udesk.cnを使用します
// ステップ1: jsとcssの参照アドレスを変更

".../ticket_js_sdk/1.0.1/js/sdk.min.js"
// jsファイルを以下に変更
".../ticket_sdk/ticket_sdk.js"

".../ticket_js_sdk/1.0.1/js/sdk.min.css"
// cssファイルを以下に変更
".../ticket_sdk/ticket_sdk.css"

// ステップ2: Jqueryへの参照を削除

// ステップ3: レンダリングモードを追加
udesk.create({
    mode: 'web' // web: PC端末レンダリングモード, mobile: モバイル端末レンダリングモード
})

API機能呼び出しガイド

特殊な状況では、カスタマイズされたインターフェースを独自に実装する必要がある場合があります。その場合、SDKのAPIを呼び出して対応するデータを取得または送信する必要があります。

メソッド名	パラメータ	説明
getConfig		チケット設定を取得
getTicketFormConfig	(id: number)	チケットテンプレートの設定を取得
saveTicket	(data)	チケットを送信、dataパラメータ説明
uploadAttachment	(file)	添付ファイルをアップロード
getTicketList	({ page: number, // ページ番号 status_id?: string, // フィルタリングするチケットステータスID desc?: string, //完全なチケット番号またはあいまいなチケット件名 })	送信済みチケットのリスト情報を取得
getTicketDetail	(id: number // チケットID)	チケットの詳細情報を取得
remindTicket	(id: number // チケットID)	チケットの催促
getTicketReplies	(id: number, // チケットID { page: number // ページ番号 })	チケットの返信情報を取得
postTicketReplies	(id: number, // チケットID { reply: { attachment_ids: number[], // 添付ファイルID content: string, // 返信内容 content_type: 'text' }})	返信情報を送信

// 例：
const SDKRequest = udesk.request();
// チケット設定を取得
SDKRequest.getConfig().then((res) => {
    console.log(res)
})
// IDが29のチケットテンプレートを取得
SDKRequest.getTicketFormConfig(29).then((res) => {
    console.log(res)
})
// 添付ファイルアップロードインターフェース
const fileDom = document.getElementById('test_file');
fileDom.addEventListener('change', function(e) {
    const file = e.target.files[0];
    SDKRequest.uploadAttachment(file).then((res) => {
        console.log(res)
    })
});

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

基本的な使用方法

効果サンプル

デスクトップ版

モバイル版

注意事項

デバイスサポート

ブラウザサポート

基本サンプル

埋め込みコードサンプル

カスタム設定

グローバルパラメータの初期化

defaultUserDataの例

初期化署名認証アルゴリズム

初期化インスタンスコード

スクリーンショット機能と設定パラメータ

snapshotOption スクリーンショットパラメータ説明

スクリーンショットのクロスオリジン設定の受け渡し

メソッド説明

createメソッド詳細説明

newTicket メソッド説明

使用例

アップグレードガイド

API機能呼び出しガイド

文档反馈