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, seeGetting 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, seehttp://www.python.org/download/.

• AnAsanaaccount. Asana offers a free plan you can use for the tutorial. To sign up, seeCreate an accountin the Asana documentation.

• AGlitchaccount. You'll use Glitch to deploy and host your web app. To create an account, seeCreating an Accountin the Glitch documentation.

• The Zendesk Command Line Interface (ZCLI). To install or upgrade ZCLI, seeInstalling and updating ZCLI. You also need to authenticate ZCLI with your Zendesk account. SeeAuthenticationin the ZCLI documentation.

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

• Familiarity with theZendesk Apps framework (ZAF). Before you start, complete theBuilding your first Support apptutorial.

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 thelocationproperty of the Zendesk app'smanifest.json文件。例子:

             

              
..."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, seeFile 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:

             

              
<scriptsrc="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 likeclient.get()orclient.invoke()to access the framework APIs from the iframe. Example:

             

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

To learn more, seeUsing 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, anapp_guidvalue 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 specifieshttps://example.com/apps/my_app/sidebaras 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.亚博.com
             

Your web app must retrieve the query string and append it to the link URL of any framework-interactive page. Example (usingBottle,我们一个Python微b framework):

             

              
@route('/sidebar')defindex():qs=request.query_stringreturntemplate('Manage tasks',qs=qs)
             

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

When an agent clicks theManage taskslink, the query string in the URL is sent to your server and then returned to the iframe in the response'sreferrerheader, along with the requested page. The ZAF SDK can then use theoriginandapp_guidparameters behind the scenes to create a client object for the page:

             

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

ZAFclient.init()returnsfalseif 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 withAsana, a popular task management application. SeePart 2 - Displaying server-side content in a Zendesk app.