Zenn
💡

[Zendesk]ZCLIを使って、お役立ちリンクを表示するZendeskアプリを作ってみた

2023/05/08に公開
zendesk
tech

想定読者

  • Zendesk アプリ開発の未経験者/これから挑戦しようと思う方
  • ZCLI を使ったことがない方

Zendeskでアプリを作ったことはありますか？

僕は正直そんなにZendeskアプリを作った経験はありません。
ただZendeskアプリを作れるようになれば、Zendeskのエージェント体験の向上が期待できそうです。そこで手始めとして、コンテキストパネルにお役立ちリンクを表示する簡単なアプリを作ってみようと思います。

成果物

https://github.com/takaakikakei/blog_zendesk_useful_links

Zendeskアプリってどうやって開発するの？

まずは開発の参考となるページを探します。zendesk apps docsなどで調べていると、以下の公式ページに出会いました。

https://developer.zendesk.com/documentation/apps/

Zendesk app quick startの章を眺めると、以下を使って開発を進めていくことが分かります。

  • ZCLI（Zendesk Command Line Interface）
    • Zendesk アプリをローカルでビルドおよびテストできるコマンドラインツール
  • ZAF（Zendesk Apps framework）
    • アプリからZendeskリソースにアクセスする際に使う
    • ユーザー名を取得したり、チケットにコメントを追加するなど

今回はアプリからZendeskリソースにアクセスしないので、ZCLIだけでなんとなかなりそうです。

ZCLIのセットアップ

ZCLIのセットアップ方法について言及された章がありました。

https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/

必要な環境

執筆時点では、ZCLI をインストールするには、次のものが必要とのことでした。

  • Node.js 14.17.3 以降
  • Linux を使用している場合、ディストリビューションによっては、次を実行する必要がある
    • Debian/Ubuntu: sudo apt install libsecret-1-dev
    • Red Hat-based: sudo yum install libsecret-devel
    • Arch Linux: sudo pacman -S libsecret

インストール

ZCLIをインストールします。

npm install @zendesk/zcli -g

以下のコマンドでhelpが表示されたら成功です。

zcli help

認証

ZCLIで利用するサブドメインの認証を行います。

zcli login -i 

Subdomain: サブドメイン名
Email: メールアドレス/token
Password: APIトークン
Successfully logged in.

補足ですが、認証関連のコマンドを紹介します。

# 認証情報のリスト
zcli profiles:list
# 認証情報の一括削除
zcli logout
# 特定サブドメインにおける認証情報削除
zcli profiles:remove {subdomain}
# 認証情報のスイッチ
zcli profiles:use {subdomain}

ZCLIを使った開発

プロジェクトの作成

cd プロジェクトフォルダ/ステージ名

# サブドメインの切り替え
zcli profiles:list
zcli profiles:use サブドメイン名

# プロジェクト作成
zcli apps:new

Enter a directory name to save the new app (will create the dir if it does not exist): blog_zendesk_useful_links
Enter this app authors name: kakei.takaaki               
Enter this app authors email: kakei.takaaki@example.com
Enter this app authors website (optional): 
Enter a name for this new app: Useful Links
  • アプリ名に_は使えないので、Enter a name for this new appに_は使わないことをおすすめします。
  • 後ほど実行するデプロイコマンドで、サブドメインごとに切り替えるオプションがないようです。なのでサブドメインやステージごとにフォルダを掘るのをおすすめします。私はサブドメインをステージで分けているので、ステージごとにフォルダを掘っています。
% tree
.
├── README.md
├── dev
│   ├── LICENSE
│   ├── assets
│   │   ├── iframe.html
│   │   ├── logo-small.png
│   │   ├── logo.png
│   │   ├── logo.svg
│   │   └── screenshots-image.png
│   ├── manifest.json
│   ├── tmp
│   ├── translations
│   │   └── en.json
│   └── zcli.apps.config.json
└── prod

ローカルサーバで起動して、Zendesk上で動作確認

zcli profiles:list
zcli profiles:use サブドメイン名

# サーバーを停止するには、Ctrl+C 
zcli apps:server

ローカルサーバーを起動した状態で以下のURLにブラウザでアクセスします。キャッシュの影響を受けないために、シークレット ウィンドウで開くの推奨します。

https://{subdomain}.zendesk.com/agent/tickets/チケット番号?zcli_apps=true

エージェント画面の右袖のコンテキストパネルのアプリを開くと、Hello Worldと表示されれば成功です。

ファイル編集

iframe.htmlを編集します。ulタグ>liタグ>aタグにお役立ちリンクを追加しています。

/ステージ名/assets/iframe.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <!--   See Using Zendesk Garden:
    https://developer.zendesk.com/apps/docs/developer-guide/setup#using-zendesk-garden
    https://garden.zendesk.com/css-components/bedrock/
    https://garden.zendesk.com/css-components/utilities/typography/
   -->
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/combine/npm/@zendeskgarden/css-bedrock@7.0.21,npm/@zendeskgarden/css-utilities@4.3.0"
    />
  </head>
  <body>
    <ul>
      <li>
        <a
          target="_blank"
          href="https://twitter.com/TakaakiKakei"
          rel="noopener noreferrer"
          >筧のTwitter
        </a>
      </li>
    </ul>
    <script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>
    <script>
      // Initialise Apps framework client. See also:
      // https://developer.zendesk.com/apps/docs/developer-guide/getting_started
      var client = ZAFClient.init();
      client.invoke("resize", { width: "100%", height: "200px" });
    </script>
  </body>
</html>

ローカルサーバで起動している状態であれば、画面をリロード or コンテキストパネルのリロードすれば、変更が反映されます。

開発が完了したら、Ctrl+Cでサーバーを停止しておきましょう。

ZCLIを使ったデプロイ

適切なフォルダに移動＆適切な認証設定にスイッチ

cd プロジェクトフォルダ/ステージ名

# サブドメインの切り替え
zcli profiles:list
zcli profiles:use サブドメイン名

初回デプロイ

初回デプロイ時は以下のコマンドでデプロイします。自動でzcli.apps.config.jsonが作成され、app_idも払い出されます。前述の通り、デプロイコマンドには、サブドメインごとに切り替えるオプションがないようです。なのでサブドメインやステージごとにフォルダを掘るのをおすすめします。私はdevはサブドメインA、prodはサブドメインBのように分けているので、ステージごとにフォルダを掘っています。

zcli apps:create

Successfully installed app: useful_links with app_id: 1234567

Zendeskのチケット画面を開き、デプロイしたアプリが表示されれば成功です！

更新

更新時はファイルを編集後、以下のコマンドでデプロイします。新しいサブドメインにデプロイする場合は、専用フォルダを作成して、初回デプロイの手順を実施します。

zcli apps:update

Uploading app... Uploaded
Deploying app... Deployed
Successfully updated app: Useful Links with app_id: 1234567

おわりに

最後まで読んでいただきありがとうございました。
ZCLIを使うことで、アプリをローカルでビルドおよびテストでき、スムーズに開発できることが分かりました。よかったら実際に手を動かしてアプリ開発してみてください。

参考

https://dev.classmethod.jp/articles/zendesk-app-develop-tool-and-flow/

Discussion