Building a server-side app - Part 1: Core concepts

Because a Zendesk app runs in an iframe in the product, you can use a server-side web application to generate the content for the iframe. You can use any server-side technology you want so long as you have a component that can send HTML pages in response to HTTP requests.

In this tutorial series, you'll learn how to build a server-side Zendesk app. The first part covers the following core concepts about building server-side Zendesk apps:

• Server-side basics
• Accessing framework APIs

The other tutorials in the series teach you how to build and deploy a small server-side app:

• Part 2: Displaying server-side content in a Zendesk app
• Part 3: Accessing external APIs
• Part 4: Accessing framework APIs
• Part 5: Securing the app
• Part 6: Deploying the app

The tutorials build on each other, so tackle them in order before moving on to the next one.

Disclaimer: Zendesk provides this tutorial series for instructional purposes only. Zendesk doesn't provide support for the apps or example code in the series. Zendesk doesn't provide support for third-party technologies, such as Asana, Bottle, or Glitch.

What you'll need

• A Zendesk account with the Zendesk Suite Growth plan or above, or the Support Professional plan or above. To get a free account for testing, see Getting a trial or sponsored account for development.

• Python 3.7 or later. You'll use Python 3 to build a remote web app. To download and install it, see http://www.python.org/download/.

• An Asana account. Asana offers a free plan you can use for the tutorial. To sign up, see Create an account in the Asana documentation.

• A Glitch account. You'll use Glitch to deploy and host your web app. To create an account, see Creating an Account in the Glitch documentation.

• The Zendesk Command Line Interface (ZCLI). To install or upgrade ZCLI, see Installing and updating ZCLI. You also need to authenticate ZCLI with your Zendesk account. See Authentication in the ZCLI documentation.

  ZCLI replaces the Zendesk Apps Tools (ZAT), which are in maintenance mode. To use ZAT instead, refer to Installing and using ZAT.

• Familiarity with the Zendesk Apps framework (ZAF). Before you start, complete the Building your first Support app tutorial.

Server-side basics

A server-side Zendesk app consists of two components:

• A Zendesk app that's installed in one or more Zendesk products
• A web application that runs on a remote server outside of Zendesk

When loaded, the Zendesk app creates an iframe in the Zendesk product. This iframe loads one or more HTML pages from the remote web app. As long as it can serve HTML pages, you can build the web app using any technologies you like. The web app can still make calls to Zendesk Apps framework APIs.

Specifying the first page to display

When the Zendesk app loads, it sends a request to the web app. The request gets the first page to display in the iframe. You specify the first page's URL in the location property of the Zendesk app's manifest.json file. Example:

...
"location": {
  "support": {
    "ticket_sidebar": {
      "url": "http://example.com/apps/my_app/sidebar",
      "flexible": true
    }
  }
},
...

Make sure the web app serves an HTML page in response to a request to that URL.

Installing a basic Zendesk app

The Zendesk app must include any files required for installation. For a list of required files, see File requirements.

Accessing framework APIs

Server-side apps access Zendesk Apps Framework (ZAF) APIs the same way client-side apps do. First, each HTML file that needs to access the framework imports the ZAF SDK in a script tag. Example:

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

Second, the page creates a ZAFClient object, and then calls methods like client.get() or client.invoke() to access the framework APIs from the iframe. Example:

const client = ZAFClient.init();
client.invoke("notify", "Ticket successfully updated!");

To learn more, see Using the Apps framework.

The big difference is that the web app must provide the following 2 parameters that the ZAF SDK needs to create a client object:

• origin - the url of the host Zendesk product. Example: https://example.zendesk.com
• app_guid - the app's unique identifier. Unlike an id typically returned by an API, an app_guid value is ephemeral

The Zendesk product provides these values to a web app when it requests the first page (the page specified in the Zendesk app's manifest file). It appends the values to the URL as query string parameters. For example, if your manifest specifies https://example.com/apps/my_app/sidebar as the first page to display in the iframe, then the product will use the following URL to request the page:

https://example.com/apps/my_app/sidebar?app_guid=f278bc69-6098-aab88a5ec49f&origin=https%3A%2F%example.zendesk.com

Your web app must retrieve the query string and append it to the link URL of any framework-interactive page. Example (using Bottle, a Python micro web framework):

@route('/sidebar')
def index():
    qs = request.query_string
    return template('<a href="manage?{{qs}}">Manage tasks</a>', qs=qs)

The route grabs the query string sent by the Zendesk product, appends it to the Manage tasks link URL, then returns a page consisting only of the link.

When an agent clicks the Manage tasks link, the query string in the URL is sent to your server and then returned to the iframe in the response's referrer header, along with the requested page. The ZAF SDK can then use the origin and app_guid parameters behind the scenes to create a client object for the page:

const client = ZAFClient.init();
// now do something with the client

ZAFclient.init() returns false if the query string parameters are wrong.

Now that you understand the basics of server-side Zendesk apps, you can start building your own. In the next tutorials in the series, you'll learn how to build a small server-side app that integrates with Asana, a popular task management application. See Part 2 - Displaying server-side content in a Zendesk app.