Zendesk guide（ヘルプセンター)のローカルでの開発環境を構築する方法

これは何？

Zendesk Guide（ヘルプセンター）は、WebUIで簡単にhbsやCSSがカスタマイズできます。
ただ、本番環境だと即時反映されるため、大きな変更では直にいじるのはちょっと厳しい...

Zendeskでは、ローカルで開発が行えるようにツールが用意されていますので、その構築手順について、ざっとまとてみます。

少し蛇足ですが、、Zendeskのローカル開発環境の仕組みは、めちゃくちゃよくできています。
私も仕組みが良く分からないのですが...w
コンテンツは本番環境から取得し、テーマだけローカルのテーマが適用されて表示できるようになっています。
なので、ローカル環境ながら、本番データを使って開発ができるようになっています。スゴイ。

前提条件（ざっくり）

PC環境

• Rubymineを使っています。
• MacOSです。
• rbenv等が入っている環境です。

その他
Github連携等は行っていません。

参考資料

テーマをローカルで編集する方法
https://support.zendesk.com/hc/ja/articles/4408838187802

大まかな手順

1. Ruby構築
2. Zendesk 開発環境の準備
3. テーマをダウンロードし、ローカルでテーマを編集し、プレビューモードで確認しながら開発
4. 編集したテーマを再びGuideにインポートし、新しいテーマを公開する

0. Ruby構築

おそらく、Mac標準のRubyでやろうとすると、躓くと思います。なので、

• brewインストール
• rbenv ruby-buildインストール
  をやった方がスムーズです。

1. 開発環境の準備 Zendesk Apps Tool（ZAT）の導入

以下のURLを参考にして、ZATをインストールします。
ローカルプレビュー機能の準備ですね。
https://support.zendesk.com/hc/ja/articles/4408822095642

APIを有効にする

「管理」>「アプリおよびインテグレーション」>「Zendesk API」にアクセスして、Zendesk SupportアカウントでAPIアクセスを有効にします。
また、この際に、APIトークンを発行しておきましょう。後で認証情報に利用します。

ZATをインストール（過去にインストールした人はスキップ）

こちらを参考にして、ZATをインストールします。
各OSで異なる部分は、ページをみていただく方が良いかと思います。
https://developer.zendesk.com/documentation/apps/zendesk-app-tools-zat/installing-and-using-the-zendesk-apps-tools/

RubymineでProjectを作成

rubyバージョンの確認

ZATは、2.1以降であれば動きます。
バージョンを確認します。

$ruby -v
ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-darwin18]

rake&zendesk_apps_toolsのインストール

まずはビルドツールを入れる

$ gem install rake

その後に、ZATをインストール。

$ gem install zendesk_apps_tools

...
Successfully installed ipaddress_2-0.13.0
Successfully installed zendesk_apps_support-4.31.1
Successfully installed sinatra-cross_origin-0.3.2
Successfully installed hitimes-2.0.0
Successfully installed timers-4.0.4
Successfully installed celluloid-0.16.0
rbenv: cannot rehash: /Users/user-name/.rbenv/shims/.rbenv-shim exists
Successfully installed listen-2.10.1
Successfully installed rack-livereload-0.3.17
Successfully installed websocket-extensions-0.1.5
Building native extensions. This could take a while...
Successfully installed websocket-driver-0.7.5
Successfully installed faye-websocket-0.10.9
rbenv: cannot rehash: /Users/user-name/.rbenv/shims/.rbenv-shim exists
Successfully installed zendesk_apps_tools-3.8.6
39 gems installed

ZATのgemをupdate

一応、ZATのgemをアップデートします。

$ gem update zendesk_apps_tools

ZATコマンドを使い、動作確認用のテストアプリを作る

テストアプリ用のフォルダを作ります。
Project root
L test

その後、testフォルダにcdして、以下のコマンドを実行します。

$ zat new

rbenv使っている方は、rehashを忘れずに。
zatなんか知らんと言われます。

では、実際にZat newを実行しテストアプリを作成します。
以下のURLにも、実行例が載っています。
https://developer.zendesk.com/documentation/apps/zendesk-app-tools-zat/installing-and-using-the-zendesk-apps-tools/#creating-starter-files-for-a-new-app

$ zat new
Enter this app author's name:
 
Enter this app author's email:
 
Enter this app author's url:
  
Enter a name for this new app:
 
Enter your iFrame URI or leave it blank to use a default local template page:
 (assets/iframe.html) 

Enter a directory name to save the new app (will create the dir if it does not exist):
 (./) 
       exist  
      create  README.md
      create  assets/iframe.html
      create  assets/logo-small.png
      create  assets/logo.png
      create  assets/logo.svg
      create  manifest.json
      create  translations/en.json

アプリの起動と動作確認

サーバーを起動します。

$ zat server

正常に起動すると、以下のメッセージが表示されます。

== Sinatra (v1.4.8) has taken the stage on 4567 for development with backup from Thin
2022-03-26 19:07:42 +0900 Thin web server (v1.8.1 codename Infinite Smoothie)
2022-03-26 19:07:42 +0900 Maximum connections set to 1024
2022-03-26 19:07:42 +0900 Listening on localhost:4567, CTRL+C to stop

動作確認

次にきちんと動いているか確認します。以下URLの流れでテストしていきます。
なお、私の流れはあくまで参考までにして、本家の方をきちんとみてください。色々注意事項が書いてあります。
https://developer.zendesk.com/documentation/apps/zendesk-app-tools-zat/installing-and-using-the-zendesk-apps-tools/#testing-your-app-locally-in-a-browser

Zendesk supportを使って、動作確認できるようです。
まずは、適当にチケットを開いて、

https://subdomain.zendesk.com/agent/tickets/321

そのチケットが表示されたら、末尾に、『?zat=true』と入れると動作確認できるようです。（本当か？ｗ）

https://subdomain.zendesk.com/agent/tickets/321?zat=true

では、実際にやってみます〜！
適当にチケットを開きます。

そして、URLの末尾に『?zat=true』を入れて再度URLを叩くと...なんと右側のアプリに表示が出てきましたｗ

ZATアプリを実行しているコンソールにもメッセージが出てきました。

2.ローカルにテーマを配置し、ローカルでプレビューできるようにする

以下のURLを参考に進めていきます。
https://support.zendesk.com/hc/ja/articles/4408822095642

1.Zendesk guideから編集対象のテーマをダウンロード

テーマをダウンロードします。

そして、テーマを配置します。
ディレクトリ構造はこんな感じにしています。
Zendeskプロジェクトルート
L guide_themes
　　　　Lアプリ名フォルダ
　　　　　　　　L解凍したファイル

2.プレビューモードを起動

では、実際にプレビューモードを起動します。
以下のコマンドを実行すると、起動します。

$ zat theme preview 

で、起動すると、「オマエのドメインをオシエロ。ログイン情報をオシエロ」等のインタラクティブなやりとりになります。
ログイン情報の入力では、２パターンの指定方法があります。どちらでも普通にログインできます。
【パターン1】
ID:ZendeskのログインID
PW:ログインIDのパスワード

$ nomad-cloud zat theme preview
  Generating  Generating theme from local files
  Generating  OK
   Uploading  Uploading theme
Enter your Zendesk subdomain or full URL (including protocol): {{zendeskのドメイン}}
Enter your username: {{ログインメールアドレス}}
Enter your password: 
   Uploading  OK
       Ready  https://{{Zendeskドメイン}}.zendesk.com/hc/admin/local_preview/start
You can exit preview mode in the UI or by visiting https://{{zendeskのドメイン}}.zendesk.com/hc/admin/local_preview/stop
== Sinatra (v1.4.8) has taken the stage on 4567 for development with backup from Thin
2022-03-26 21:29:44 +0900 Thin web server (v1.8.1 codename Infinite Smoothie)
2022-03-26 21:29:44 +0900 Maximum connections set to 1024
2022-03-26 21:29:44 +0900 Listening on localhost:4567, CTRL+C to stop

【パターン2】
ID:ZendeskのログインID
PW:APIトークン

$ zat theme preview
  Generating  Generating theme from local files
  Generating  OK
   Uploading  Uploading theme
Enter your Zendesk subdomain or full URL (including protocol): {{zendeskのドメイン}}
Enter your username: {{ログインメールアドレス}}/token
Enter your password: 
   Uploading  OK
       Ready  https://{{zendeskのドメイン}}.zendesk.com/hc/admin/local_preview/start
You can exit preview mode in the UI or by visiting https://{{zendeskのドメイン}}.zendesk.com/hc/admin/local_preview/stop
== Sinatra (v1.4.8) has taken the stage on 4567 for development with backup from Thin
2022-03-26 21:32:28 +0900 Thin web server (v1.8.1 codename Infinite Smoothie)
2022-03-26 21:32:28 +0900 Maximum connections set to 1024
2022-03-26 21:32:28 +0900 Listening on localhost:4567, CTRL+C to stop

3.プレビュー画面にアクセス

上記で表示された、以下のURLにアクセスします。

Ready  https://{{zendeskのドメイン}}.zendesk.com/hc/admin/local_preview/start

プレビューURLには、chromeかfirefoxでアクセスしてください。
その後、注意事項は、以下URLの『ローカルテーマのプレビューを開始するの４と５をご確認ください。』
https://support.zendesk.com/hc/ja/articles/4408822095642

複数ブランドを使っている方へ（複数のヘルプセンターを運用されている方へ）
ブランド毎にサブドメインが異なると思いますので、編集対象のサブドメインを指定してください。

4.実際に試して見る

ということで、準備が整いましたので試して見ました。
ローカルで編集して適用すると、すぐに本番環境のURLに反映されます。
これはまじで便利だ...

プレビューモードを終了する場合は、

• ブラウザに切り替えて、プレビュー中のページの上部にある「To exit, click here」リンクをクリック
• コマンドラインインターフェイスに切り替えて、Ctrl + C
• コンソール表示されている、You can exit preview mode in the UI or by visiting ....のURLをクリック

のどれかを行えば終了です。

編集したテーマを再びGuideにインポートする

あとは、以下の記事に従って、テーマをZIPにして、アップロードし、公開したら終了です。
https://support.zendesk.com/hc/ja/articles/4408838187802