Manifest reference

The manifest.json file is used to configure your app. Example:

{
  "name": "My App",
  "author": {
    "name": "Jean Thompson",
    "email": "support@omniwear.com",
    "url": "https://www.omniwear.com/profiles/jthompson"
  },
  "defaultLocale": "en",
  "private": false,
  "location": {
    "support": {
      "background": "assets/iframe.html",
      "ticket_sidebar": {
        "autoLoad": false
      },
      "top_bar": {
        "autoHide": true,
        "url": "assets/top_bar.html",
        "size": {
          "width": "450px",
          "height": "500px"
        }
      }
    }
  },
  "domainWhitelist": ["omniwear.com"],
  "parameters": [
    {
      "name": "token",
      "type": "text",
      "secure": true,
      "required": true
    }
  ],
  "version": "1.0",
  "frameworkVersion": "2.0"
}

Manifest properties

name

Specifies a name for the app. The name is used in the header of the app when it's visible when running the app locally on the ZAT server.

author

Required. Specifies the author of the app. The property contains a JSON object with values for "name", "email", and "url".

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

The name can be an individual or a company name. The email 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.

version

Specifies a version number for the app. The version number will be displayed alongside your app details in the Zendesk Marketplace.

frameworkVersion

Required. Specifies the framework version used to build your app. See Understanding framework versions.

"frameworkVersion": "2.0",

location

Required. Specifies where the app appears in the product interface, and per-location options. See Setting the app location. Locations vary by product. For the locations in Zendesk Support, see:

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 in Zendesk Support can get and set ticket properties, and listen for changes to the ticket.

Properties that may be specified for each location:

  • autoHide specifies whether the app starts as hidden on first load
  • autoLoad specifies whether the iframe is automatically loaded (defaults to true)
  • signed specifies whether to use signed URLs
  • url specifies the URL of the page to display in the iframe at that location
  • size specifies the initial size of the app to display in the iframe at that location. Some locations have size restrictions that override this property. For example, the width of an app in the ticket sidebar is restricted to 320px and can't be changed.

Example:

"location": {
  "support": {
    "ticket_sidebar": {
      "autoHide": true,
      "signed": true,
      "url": "https://myapp.example.org/",
      "size": {
        "height": "220px"
      }
    }
  }
},

Optionally, to leave all other options as defaults, you can specify only the url property as a string. Example:

"location": {
  "support": {
    "ticket_sidebar": "assets/iframe.html"
  }
},

You can also specify multiple locations across Zendesk products in your manifest file (currently only Zendesk Support and Zendesk Chat are supported). Example:

"location": {
  "support": {
    "ticket_sidebar": "assets/iframe.html"
  },
  "chat": {
    "chat_sidebar": "assets/chat_iframe.html"
  }
},

It is also possible to use any setting in the url (except for secure settings).

"location": {
  "support": {
    "ticket_sidebar": "http://{{setting.domain}}.my_server.com/iframe.html"
  },
  "chat": {
    "chat_sidebar": {
      "url": "{{setting.url}}"
    }
  }
},

gaID

Specifies a Google Analytics tracking ID if you want to analyze how many visitors view your app's detail page on the Zendesk Marketplace.

"gaID": "ua-123456",

defaultLocale

Required. Sets the default locale of the app. While still required, this value is not actively used in the Zendesk Apps framework v2. It is up to you to determine how internationalization tasks are implemented and managed.

The value must be a two- or three-letter ISO 639 language code.

"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. For details, see Internationalization.

parameters

Defines settings you want your users to set for your app during installation. See Defining installation settings. Example:

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

domainWhitelist

Specifies a domain whitelist if you make one or more of your app settings secure. For details, see Using secure settings.

"domainWhitelist": ["www.teachmyapi.com", "techmyapi.herokuapp.com"],

The setting prevents attackers from hijacking the secure setting to reroute it to another domain and hijack the token or password.

Omit this property if not making secure requests.

The domainWhitelist entries also support interpolation of setting values to customize the whitelist on a per installation basis. To specify a setting value in a domain whitelist entry, use double curly brackets. Example:

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

private

Sets whether the app is private or not. By default, an app without this property is treated as private, and therefore can only be installed in the app developer's account.

"private": true,

When submitting an app to the Zendesk Marketplace, this property must be false.

requirementsOnly

Specifies that the app's only job is to create resources in a Zendesk Support instance. See Creating a requirements-only app.

"requirementsOnly": true,

singleInstall

Specifies that each account can only have one installation of the app at a time.

"singleInstall": true,

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

signedUrls

When true, Zendesk includes a JWT token in the HTTP request it makes for the initial page of a server-side app. The page is specified by the url in the location object. See Authenticating Zendesk in your server-side app. This property doesn't apply to client-side apps.

You can add "signedUrls": true to the top-level manifest object:

{
  "name": "My App",
  "signedUrls": true,
  ...
}

The property applies to the app in all locations in the manifest's location object. If you want the feature to be enabled only in a specific location, add "signed": true to the named location in the location object:

...
"location": {
  "support": {
    "ticket_sidebar": {
      "signed": true,
      "url": "https://myapp.example.org/"
    }
  }
},

termsConditionsURL

If you plan on listing a paid app in the Zendesk Marketplace, you must provide a link to your Terms & Conditions.

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

experiments

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

Available experiments:

  • hashParams - set to true to send the parameters to ZAF SDK using hash urls to improve cacheability
"experiments": {
  "hashParams": true
}

marketingOnly

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

You can also choose which Zendesk products the Marketing Only app can be used in by specifying a { "location": {} } object in your manifest.

Note: if you do not specify a { "location": {} } object in your manifest, the default product is Zendesk Support.

For more information see Partner Program intro.

Example Zendesk Support Marketing Only app:

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

Example Zendesk Chat Marketing Only app:

{
  "name": "WordPress",
  "author": {
    "name": "Zendesk",
    "email": "support@zendesk.com",
    "url": "https://www.zendesk.com"
  },
  "location": {
    "chat": {
    }
  },
  "defaultLocale": "en",
  "marketingOnly": true,
  "private": false
}

Example multi-product Marketing Only app:

{
  "name": "WordPress",
  "author": {
    "name": "Zendesk",
    "email": "support@zendesk.com",
    "url": "https://www.zendesk.com"
  },
  "location": {
    "support": {
    },
    "chat": {
    }
  },
  "defaultLocale": "en",
  "marketingOnly": true,
  "private": false
}