Manifest

The manifest file is a .json file included with your app source code. It describes certain details about your app. If you use the Zendesk App Tools to create the files for your app, some values are set for you.

Example:

{
  "name": "My App",
  "version": "1.0.0",

  "author": {
    "name": "The Mentor",
    "email": "support@zendesk.com",
    "url": "http://www.zendesk.com/apps"
  },

  "frameworkVersion": "1.0",
  "location": "ticket_sidebar",
  "defaultLocale": "en",
  "private": false,
  "singleInstall": true,
  "parameters": [
    {
      ...
    },
    ...
  ]
}

Use the manifest file to specify the following information about your app:

Version

The version number of the app must be specified by the "version" property.

Author

The author of the app must be specified by the "author" property. The value of the property is a JSON object with values for "name", "email", and, optionally, "url". The name can be an individual or a company name. The email address should be the address where users of the app can send support requests. The URL can point to a page about the author or the app. For example, "http://www.company.com" or "http://www.company.com/app-page".

Example:

  "author": {
    "name": "The Mentor",
    "email": "support@company.com",
    "url": "http://www.company.com/apps"
  },

Framework Version

The framework version that your app is built for must be specified by the "frameworkVersion" property. Example:

  "frameworkVersion": "1.0",

See Understanding framework versions.

Location

You must declare where you want the app to appear in the Zendesk Support interface with the "location" property.

In many cases, apps appear in the Apps panel on the right side of the ticket in the agent interface. The framework calls this location the ticket_sidebar (or the new_ticket_sidebar in the case of the new ticket page). Don't confuse the ticket_sidebar with the vertical icon bar on the left side of the interface. In the framework, the bar on the left is called the nav_bar.

You can specify multiple locations for an app. Also, some framework APIs are available only to apps in certain locations. For example, only apps appearing on the ticket page can get and set ticket properties, and listen for changes to the ticket.

Available locations:

Location Agent interface
nav_bar Navigation bar on the left side
top_bar Right side of the bar on the upper side
ticket_sidebar Panel on the right side of the ticket
new_ticket_sidebar Panel on the right side of the new ticket
user_sidebar Panel on the right side of the user page
organization_sidebar Panel on the right side of the organization page
background No UI, always running in the background to receive special events

If you specify nav_bar or top_bar, the app appears as an icon in the location. Clicking the icon opens the app.

image

Example:

  "location": "ticket_sidebar",

Use an array to specify multiple locations:

  "location": ["ticket_sidebar","new_ticket_sidebar"],

Google Analytics Code

If you want to analyze how many visitors view your app's detail page on the Zendesk App Marketplace, specify a Google Analytics tracking ID by adding the "gaID" property to your app's manifest file.

Example:

  "gaID": "ua-123456",

Default Locale

The default locale of the app must be specified with the "defaultLocale" property. The value of the property must be a two- or three-letter ISO 639 language code. Example:

  "defaultLocale": "en",

The app can support any number of additional languages. If the agent selects a language the app doesn't support, the app is displayed in the default locale. See also the internationalization documentation.

App Settings

You can define settings you want your users to set for your app. The settings are defined by the parameters property with a value consisting of a list of JSON objects. Example:

"parameters": [
  {
    "name": "subdomain",
    "type": "text",
    "required": true
  },
  {
    "name": "useSSL",
    "type": "checkbox"
  }
]

For details, see Settings.

Domain Whitelist

If you make one or more of your app settings secure (see Secure Settings), you can specify a domain whitelist with the "domainWhitelist" property. Example:

  "domainWhitelist": ["www.teachmyapi.com", "{{setting.subdomain}}.herokuapp.com"],

If not making secure requests, omit this property.

The domain whitelist is another layer of security you can use if you're making secure requests. The setting prevents attackers from hijacking the secure setting to reroute it to another domain and hijack the token or password.

Private App

You must declare whether the app is private or not with the "private" property. Example:

  "private": true,

If "private" is set to true, then only the app developer's account can install the app.

No-template App

You can set your app or part of your app to run in the background with the noTemplate property. Use the property to build apps with no user interface or with a hidden user interface, as described in the following sections.

Apps with no user interface

Setting noTemplate to true prevents your templates from rendering. This lets you build an app that runs in the defined location but doesn't have an interface for the agent or admin. For example, an app could hide a few fields on the ticket, or display a notification message when an error occurs.

Example:

  ...
    "frameworkVersion": "1.0",
    "location": "ticket_sidebar",
    "noTemplate": true,
    "parameters": [
      {
        ...
      },
      ...
    ]
  ...
Apps with a hidden user interface

You can also use the noTemplate parameter to build an app that starts with part or all of the user interface hidden in certain locations. Specify the locations in an array. The templates are compiled but aren't displayed in those location on start up. You can display them at any time using this.show() and then hide them again with this.hide(). This behavior is different from "noTemplate": true, which prevents you from using any templates at all. For example, an app could use the nav_bar location to take user input, then act on that input in the ticket_sidebar and new_ticket_sidebar locations.

Example:

  ...
    "frameworkVersion": "1.0",
    "location": ["nav_bar", "ticket_sidebar", "new_ticket_sidebar"],
    "noTemplate": ["ticket_sidebar","new_ticket_sidebar"],
    "parameters": [
      {
        ...
      },
      ...
    ]
  ...

See also the conditional locations demo app on Github.

Note: A notification is displayed at the top of the ticket sidebar specifying the number of hidden apps in that location.

Single-install App

You can specify that each account can only have one active installation of the app at a time with the "singleInstall" property. Example:

  "singleInstall": true,

If in doubt, leave this property out or set it to false.

Terms & Conditions URL

If you plan on listing a paid app in the Zendesk App Marketplace, you will need to provide a link to your Terms & Conditions. You can use the termsConditionsURL property to set this URL.

  "termsConditionsURL": "https://www.mycompany.com/terms.html"

Experiments

The experiments property enables the app to opt-in to app framework features that are available from time to time. These features are experimental, and their API, usage or definition may change.

Available experiments
  • newCssCompiler - set to true to compile app.css using a different compiler with a smaller output size, reducing the download size for users of the app. It's recommended to turn this on for your app because it will become the default.
"experiments": {
  "newCssCompiler": true
}

Marketing Only

Marketing Only apps are integrations built for a third-party product. These apps are discoverable in the Zendesk App Marketplace but cannot be installed like regular apps. If you plan on listing an integration app in the Zendesk App Marketplace, you must provide a zip file with marketing assets along with a simple manifest file that specifies { "marketingOnly": true }. See Publish Your App.

Example:

{
  "name": "WordPress",
  "author": {
    "name": "Zendesk",
    "email": "support@zendesk.com"
  },
  "defaultLocale": "en",
  "marketingOnly": true,
  "private": false
}