Edit

Share via

Office Add-ins manifest

  • Article

Every Office add-in has a manifest. There are two types of manifests:

  • Add-in only manifest: This is the only type of manifest that's currently supported for non-Outlook add-ins. Its format is XML. This type of manifest can't be used for an app that combines an add-in with some other kind of extension of the Microsoft 365 platform.
  • Unified manifest for Microsoft 365: This is an expanded version of the JSON-formatted manifest that has been used for years as the manifest for Teams Apps. Add-ins that use this manifest can be combined with other kinds of extensions of the Microsoft 365 platform in a single app that's installable as a unit.

Note

Office Add-ins that use the unified manifest for Microsoft 365 are directly supported in Office on the web, in new Outlook on Windows, and in Office on Windows connected to a Microsoft 365 subscription, Version 2304 (Build 16320.00000) or later.

When the app package that contains the unified manifest is deployed in AppSource or the Microsoft 365 Admin Center then, if the manifest has a valid "alternateIcons" property, an add-in only manifest is generated from the unified manifest and stored. This add-in only manifest enables the add-in to be installed on platforms that don't directly support the unified manifest, including Office on Mac, Office on mobile, subscription versions of Office on Windows earlier than 2304 (Build 16320.00000), and perpetual versions of Office on Windows.

The remainder of this article is applicable to both types of manifest.

Tip

The manifest file of an Office Add-in describes how your add-in should be activated when an end user installs and uses it with Office documents and applications.

A manifest file enables an Office Add-in to do the following:

  • Describe itself by providing an ID, version, description, display name, and default locale.

  • Specify the images used for branding the add-in and iconography used for add-in commands in the Office app ribbon.

  • Specify how the add-in integrates with Office, including any custom UI, such as ribbon buttons the add-in creates.

  • Specify the requested default dimensions for content add-ins, and requested height for Outlook add-ins.

  • Declare permissions that the Office Add-in requires, such as reading or writing to the document.

Note

If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the Commercial marketplace certification policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 1120.3 and the Office Add-in application and availability page).

Hosting requirements

All image URIs, such as those used for add-in commands, must support caching in production. The server hosting the image shouldn't return a Cache-Control header specifying no-cache, no-store, or similar options in the HTTP response. However, when you're developing the add-in and making changes to image files, the caching can prevent you from seeing your changes, so using Cache-Control headers is advisable in development.

All URLs to code or content files in the add-in should be SSL-secured (HTTPS). While not strictly required in all add-in scenarios, using an HTTPS endpoint for your add-in is strongly recommended. Add-ins that are not SSL-secured (HTTPS) generate unsecure content warnings and errors during use. If you plan to run your add-in in Office on the web or publish your add-in to AppSource, it must be SSL-secured. If your add-in accesses external data and services, it should be SSL-secured to protect data in transit. Self-signed certificates can be used for development and testing, so long as the certificate is trusted on the local machine.

Best practices for submitting to AppSource

Make sure that the add-in ID is a valid and unique GUID. Various GUID generator tools are available on the web that you can use to create a unique GUID.

Add-ins submitted to AppSource must also include a support URL in the manifest. For more information, see Validation policies for apps and add-ins submitted to AppSource.

Specify domains you want to open in the add-in window

When running in Office on the web or new Outlook on Windows, your task pane can be navigated to any URL. However, in desktop platforms, if your add-in tries to go to a URL in a domain other than the domain that hosts the start page (as specified in the manifest file), that URL opens in a new browser window outside the add-in pane of the Office application.

To override this (desktop Office) behavior, specify each domain you want to open in the add-in window in the manifest. If the add-in tries to go to a URL in a domain that is in the list, then it opens in the task pane in both Office on the web and desktop. If it tries to go to a URL that isn't in the list, then, in desktop Office, that URL opens in a new browser window (outside the add-in pane).

Note

There are two exceptions to this behavior.

  • It applies only to the root pane of the add-in. If there is an iframe embedded in the add-in page, the iframe can be directed to any URL regardless of whether it is listed in the manifest, even in desktop Office.
  • When a dialog is opened with the displayDialogAsync API, the URL that is passed to the method must be in the same domain as the add-in, but the dialog can then be directed to any URL regardless of whether it is listed in the manifest, even in desktop Office.

Specify domains from which Office.js API calls are made

Your add-in can make Office.js API calls from the add-in's domain referenced in the manifest file. If you have other iframes within your add-in that need to access Office.js APIs, add the domain of that source URL to the manifest file. If an iframe with a source not listed in the manifest attempts to make an Office.js API call, then the add-in will receive a permission denied error.

See also