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 5-part 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:

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

Disclaimer: Zendesk provides this article for instructional purposes only. The Zendesk Support team does not provide support for the content. Please post any issue in the comments section below or in the Zendesk Apps community, or search for a solution online.

Specifying the first page to display

When the app starts in a Zendesk product, the product sends a request for the first page to display in the iframe. You specify the first page's URL in the app's manifest.json file. Example:

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

Installing a basic framework app

Even if you're building a server-side app, you must still package the following required files in a framework app, and then upload and install the app in the Zendesk product:

A manifest.json file in the app's root folder - See the previous section and the Manifest reference in the reference docs

A translation file named {locale}.json in a folder named translations in the root folder - The value of {locale} is specified by the defaultLocale property in manifest.json. For example, if "defaultLocale" is "en", then make sure a file named en.json exists in the translations folder. See Apps internationalization in the reference docs

A small app icon named logo-small.png in a folder named assets in the root folder - The image is used in the header of the app. You can still upload and install the app without it, but a broken image icon will appear in the app's header. See Styles and assets in the reference docs for the image specifications

A larger app icon named logo.png in the assets folder - The image is used in the product admin pages for managing apps. You can still upload and install the app without it but a broken image icon will appear in the interface. Styles and assets in the reference docs for the image specifications

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 app's manifest file). It appends the values to the URL as query string parameters. For example, if your manifest specifies https://omniwear.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:

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

When the user clicks the Manage tasks link in the app, the query string in the URL is sent to your server and then returned to the iframe in the response's referer 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:

var 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. Get started: Part 2 - Display server-side content in a Zendesk app.