DocumentationAPI Reference

Building your first Support app - Part 5: Installing the app in Zendesk Support

If you followed along in the series, you should now have a working Zendesk app that you built from scratch. In this tutorial, you'll install the app in your instance of Zendesk Support. The tutorial will also show you how to test and validate the app, and then package it for uploading.

You can only upload and install private Support apps on the Zendesk Suite Growth plan or above, or the Support Professional plan or above. To get a free eligible account for testing, see Getting a trial or sponsored account for development.

This tutorial is part of a series on building a Zendesk app:

Testing and validating the app

Thoroughly test your app with the ZCLI server. For example, open different tickets and switch between tickets.

Test the app

  1. If your ZCLI server is not already started, use the command line to navigate to the xr_app folder and start the server.

    zcli apps:server

  2. If your test ticket is not already open, use a browser to navigate to any ticket in Zendesk Support, append ?zcli_apps=true to the ticket URL, and reload the page. The URL should look something like this:

    https://subdomain.zendesk.com/agent/tickets/123?zcli_apps=true

  3. In your browser's Address bar, click the shield icon on the left (Chrome) or lock icon on the right (Firefox) and agree to load an unsafe script (Chrome) or to disable protection (Firefox). If you don't do this, the browser will block your app.

    In Chrome, click Load Unsafe Scripts.

    In Firefox, make sure Content Blocking is set to Standard. Click the gear icon to change it, if necessary.

    Note: Safari has no option to disable content blocking. You must use Chrome or Firefox.

  4. Try different tests.

  5. When you're finished, shut down the ZCLI server by pressing Control+C.

Once you're satisfied the app is stable, run the ZCLI validate command to catch any problems before uploading the app to Zendesk Support.

Validate your app

  1. Use the command line to run the following command in your xr_app folder:

    zcli apps:validate

    Note: If the command prompt isn't displayed, make sure you shut down the ZCLI server by pressing Control+C.

  2. Fix any problems reported by the tool, then run validate again.

Packaging the app

The next step is to package the app in a zip file that can be uploaded to your instance of Zendesk Support.

Package your app

  • Run the following command in your xr_app folder:

    zcli apps:package

ZCLI packages the app in a ZIP file and saves it in a tmp folder in your app root folder.

Uploading and installing the app in Zendesk Support

At last you're ready to upload and install the app in your instance of Zendesk Support. You need to sign in to Zendesk Support as an admin. You must be on the Growth plan or above, or you must have a free sponsored account for developers.

Upload and install the app

  1. In Zendesk Support, click the Admin icon () in the sidebar, then select Manage from the Apps category.
  2. Click Upload Private App in the upper-right corner of the page.
  3. Enter the name of your app (Requester X-ray). If you did the tutorial for ZAF v1 and installed the app, use a slightly different name for this second version of the app.
  4. Click Choose File and select the zip file of your app.

ZCLI placed the ZIP file in the tmp folder in your xr_app folder.

  1. Click Upload to upload the app to Zendesk Support, then again after reading the risks and limitations.

  2. When prompted, click Install.

    Note: If you want to restrict access to your app to just administrators or just agents, click Enable Role Restrictions before installing and choose the users.

    When the process is complete, your app should appear as a private app in your list of installed apps on the page.

Your support team is ready to use the app. Open a ticket and click the Apps button in the upper-right corner if the apps are not visible.

If you build an app that other support organizations might find useful, consider making it publicly available in the Zendesk Marketplace. See Publishing your app in the Zendesk Marketplace.

The app you built in this tutorial is a client-side app, meaning all the code runs on the client — the user's browser. You can also build server-side apps. For a step-by-step guide, see Building a server-side app.