アプリ開発

このガイドでは、GitLab における Zendesk アプリの開発について説明します。

Zendesk アプリを理解する

Zendesk でアプリの作成と編集を始める前に、Zendesk アプリと Zendesk Apps frameworkの両方の詳細を理解することが重要です。

ここには多くの要素があるため、さまざまな詳細を学ぶには Zendesk のドキュメントが最良のリソースです。このトレーニングドキュメントでは「最も重要」と見なされる部分を扱いますが、できるだけ頻繁に Zendesk 開発者向けドキュメントを読み、参照することを強く推奨します。

ZAT

ZAT（Zendesk App Tools）は、Zendesk アプリをローカルで扱う作業を大幅に容易にする Ruby gem です。コンピューターにインストールすることを強く推奨します。

gem install rake
gem install zendesk_apps_tools

更新するには、次を実行します。

gem update rake
gem update zendesk_apps_tools

Mac のターミナルでは、書き込み権限エラーが発生することがあります。その場合は、次を使用できます。

sudo gem update rake
sudo gem update zendesk_apps_tools

manifest.json

このファイルはアプリケーションの設定に使用します。そのため、正確であることが非常に重要です。

一般的な設定は次のとおりです。

場所

この設定は、アプリを表示して実行する場所を決定します。これは非常に重要な設定です。最初の設定でプロダクトタイプの場所を決定し、その設定内でアプリを表示する物理的な場所など、多くの設定を指定できます。プロダクトタイプの場所には、常に support を使用します。

物理的な場所は次のとおりです。

物理的な場所の設定内には、さらに多くの設定を含めることができます。最も一般的なものは次のとおりです。

例として、チケットサイドバーで開始時の高さを 200px にして https://google.com を自動的にロードするには、設定ブロックは次のようになります。

"location": {
  "support": {
    "ticket_sidebar": {
      "autoLoad": true,
      "url": "https://google.com/",
      "size": {
        "height": "200px"
      }
    }
  }
}

別の例として、ローカルの assets/iframe.html ファイルをレンダリングしてアプリをユーザーページと組織ページの両方にロードするには、次のようにします。

"location": {
  "support": {
    "user_sidebar": "assets/iframe.html",
    "organization_sidebar": "assets/iframe.html"
  }
}

パラメーター

ここでは、インストール中にアプリで使用する変数を定義します。

ドメインの許可リスト

アプリがセキュアパラメーターを使用し、Zendesk 外部へリクエストを送る予定である場合、該当ドメインを許可リストに登録する必要があります。例は次のとおりです。

{
  "domainWhitelist": [
    "gitlab.com",
    "google.com"
  ]
}

エントリ

各パラメーターエントリは、次を含むハッシュです。

• name: パラメーターの名前
• type: パラメーターの型
• secure: HTTP リクエストの作成時にユーザーが変数の値を確認できないようにする（これは常に使用してください）
• required: パラメーターがインストールに必須かどうかを指定する

例として、いずれも安全な方法で使用するテキストパラメーターである、必須の 2 つのパラメーター（param1 と param2）を使用するには、次のようにします。

{
  "parameters": [
    {
      "name": "param1",
      "type": "text",
      "secure": true,
      "required": true
    },
    {
      "name": "param2",
      "type": "text",
      "secure": true,
      "required": true
    }
  ]
}

アプリのインストール中に、Zendesk はこれらのパラメーターの値を指定するよう求めます。アプリのコード内でこれを使用するには、次を使用します。

{{setting.NAME_OF_PARAMETER}}

ここで、NAME_OF_PARAMETER は manifest.json ファイルでパラメーターに付けた名前です。

必須の JavaScript ライブラリ

ZAT を使用するには、アプリの HTML ファイルに次の JavaScript を含める必要があります。

<script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>

init

ZAF（Zendesk App Framework）クライアントのクライアントインスタンスを作成するには、アプリの JavaScript に次が含まれていることを確認する必要があります。

var zafclient = ZAFClient.init();

アプリのリサイズ

実行時にアプリのサイズを変更するには、invoke クラスを使用し、resize 関数を呼び出すよう指定します。次のように行います。

var zafclient = ZAFClient.init();
zafclient.invoke('resize', { width: '100%', height: '100px' });

メタデータの取得

メタデータを取得してアプリで使用するには、ZAF クライアントの get 関数を使用する必要があります。これはチケットメタデータから取得する値の配列を取り、それを関数内で使用します。

例として、チケットリクエスターの名前とチケットの組織を取得してコンソールに記録するには、次のようにします。

var zafclient = ZAFClient.init();
zafclient.get(['ticket.requester.name', 'ticket.organization']).then(function(data) {
  console.log("Ticket requester name: " + data['ticket.requester.name']);
  console.log("Ticket organization: " + data['ticket.organization.name']);
});

別の例として、チケットの期限日と期限日の注記（カスタムチケットフィールド）を取得してコンソールに記録するには、次のようにします。

var zafclient = ZAFClient.init();
zafclient.get(['ticket.customField:due_date', 'ticket.customField:custom_field_360017383799']).then(function(data) {
  console.log("Due date": + data['ticket.customField:due_date']);
  console.log("Due date notes:" + data['ticket.customField:custom_field_360017383799']);
});

リクエストの実行

アプリでは、“内部”（つまり Zendesk 内）または外部のリクエストを行う必要がある場合があります。これを行うには、クライアントオブジェクトの request 関数を使用します。

この形式は、jQuery での AJAX リクエストの作成形式に非常に近いものです。通常使用する形式は次のとおりです。

var zafclient = ZAFClient.init();
zafclient.request({
  method: 'REQUEST_TYPE',
  url: 'URL_TO_USE',
  contentType: 'CONTENT_MEDIA_TO_SEND',
  data: DATA_OBJECT,
  secure: BOOLEAN,
  headers: HEADERS_OBJECT
}).then(function(data) {
  // do stuff
}).catch(function(error) {
  console.error('Request failed:', error);
});

リクエスト内の正確なパラメーターは、リクエストごとに異なります。

例として、チケットの期限日を更新する場合は、次のようになります。

var zafclient = ZAFClient.init();
zafclient.request({
  method: 'PUT',
  url: '/api/v2/tickets/123456.json',
  contentType: 'application/json',
  data: JSON.stringify({
    due_at: new Date('2021-01-01').toISOString()
  }),
  secure: BOOLEAN,
  headers: HEADERS_OBJECT
}).then(function(data) {
  console.log('Due date updated to 2021-01-01');
});

別の例として、アプリのインストール時に設定したセキュアパラメーターを使用して、ユーザー ID 987654 の情報を見つけるために gitlab.com へ GET リクエストを行う場合は、次のようになります。

var zafclient = ZAFClient.init();
zafclient.request({
  method: "GET",
  url: 'https://gitlab.com/api/v4/users/987654?private_token={{setting.GitLab_token}}',
  secure: true
}).then(function(data) {
  console.log('User email: ' + data.email);
});

人が読める形式への置換

現在、同期リポジトリでは、JavaScript および HTML ファイル内で、さまざまな項目を人が読める項目から “Zendesk” の同等項目へ置換できます。これには次が含まれます。

例として、チケットフォーム Support Ops の ID を参照する場合は、次のようにします。

var support_ops_form_id = [[Form: Support Ops]]

同様に、チケットフィールド Customer Priority の ID を参照する場合は、次のようにします。

<div data-field-id='[[Field: Customer Priority]]'>
  <!-- Stuff goes here -->
</div>

これは JavaScript としては技術的に “無効” なコードであるため、zat を使用してローカルで実行するとエラーが発生することに注意してください。変換そのものを行うのは sync スタイルのスクリプトだけです。

アプリをテストする

Zendesk アプリを本番環境に導入する前にテストする方法は 2 つあります。

ローカル

アプリをローカルでテストするには、ローカルコンピューターのアプリディレクトリに cd してから、zat server コマンドを実行します。これによりコンピューター上で ZAT サーバーが起動します。起動したら、Zendesk URL に移動し、末尾に ?zat=true を追加します。これにより、ローカルコンピューターのアプリがロードされ、ローカルでアプリをテストできます。

Sandbox 経由

アプリがセキュアパラメーターを使用している場合は、代わりに Sandbox 経由でテストする必要があります。これは Sandbox にデプロイすることを意味します。詳細については、Zendesk アプリを参照してください。

ページのソースコードを見る - ページの編集 - please contribute.