App Extensions help developers extend the capabilities of the BigCommerce control panel by registering custom menu items that appear on select native control panel pages. This article is a high-level explanation of what App Extensions are and what they can do, and covers the following topics:
For more detail about each attribute of the App Extension object, see the App Extensions Glossary or the full AppExtension object schema in GraphQL Admin API Reference.
As the preceding section says, App Extensions let you add custom menu items on select control panel pages. This section describes what that’s like from the user’s point of view.
App Extensions support all available control panel languages, so you can show the user app content in the language they are already using. You can register alternate link text for any supported control panel language (Help Center) and handle content rendering to present markup in translation on a per-user basis, using the user.locale property of the signed_payload_jwt that accompanies BigCommerce’s load callback to your app.
When a control panel user clicks an App Extension-generated menu item, the app can either render content in a side panel - without navigating the user away from the native page - or it can redirect the user to the app’s home iFrame in the Apps sub-menu, and render App Extension-specific content there.
The following set of tabs show example pictures of the menu item and two load contexts, along with the schemas that describe them. If image diagrams are not accessible to you, use the alt text to determine which sections of the App Extensions Glossary to read instead.
The menu item also includes one of the app images you upload as part of the app profile. A production app that uses App Extensions should have high-quality app images. You can read more about app images in the Apps Guide.
The following tabs show a screenshot of an App Extensions menu item and the corresponding AppExtensions object. For more about the menu item URL and default label, see the App Extensions Glossary.
Use English for label.defaultValue.
In the panel context, the App Extension renders your response to the load callback in an overlay panel that opens from the right. The panel is responsive, so make sure to send responsive markup. The width can vary from 45% to nearly 100% of the control panel content page.
The following tabs show both a panel and an example of an alternate user locale. The first tab contains screenshots of the control panel locale, an App Extensions menu item, and app content rendered in the panel context. The second tab shows the corresponding AppExtensions object and signed_payload_jwt, with highlighted lines that indicate what information is useful in determining which locale’s markup to send. For more about rendering context and label locales, see the App Extensions Glossary.
You can register, update, query, and remove App Extensions using the GraphQL Admin API. For example requests and responses, as well as additional information about each call, see the App Extensions Guide.
App Extensions are registered independently for each store that installs your app; they are scoped to the store, not the app client ID. This means you must register a given App Extension separately for each store. This provides several benefits, including the following:
It’s a best practice for your app to keep track of how it has instantiated its types of App Extensions on each store; namely, the mapping between the store’s App Extension IDs and your set of possible App Extensions. This is particularly crucial if you offer several related App Extensions distinguished by settings or pricing. You can retrieve your app’s App Extensions from BigCommerce using the Store appExtensions query.
The simplest design pattern is registering identical App Extensions on each store as part of your app’s initial installation flow. You can use the updateAppExtension mutation to modify them later or use the deleteAppExtension mutation to remove them.
Several components go into using App Extensions effectively. The following table lists some of the key components of App Extensions and disambiguates the source of truth for each:
Each App Extension is associated with one control panel page, which you define using the model property. The model corresponds with the page’s primary API entity.
For supported models, see the App Extensions Glossary and the GraphQL Admin API Reference.
There is a limit of two App Extensions per app, per model. Your app can register up to two App Extensions for the orders model, two for the products model, and two for customers. If these limits are detrimental to your use case or user experience, please reach out through our Developer Community.
When you develop an App Extension, keep in mind the two available page load contexts: the side panel, or panel, and the deep link, or link. Panel-type App Extensions load in an <iframe> element that overlays the content of the control panel page in which they are embedded. Link-type App Extensions redirect to a detail view in the app’s dedicated iFrame in the Apps sub-menu.
The side panel context can enhance a lot of use cases that benefit from keeping the control panel user on the page for task context or workflow efficiency reasons. The user can expand the panel to full screen, but if the task the App Extension assists would benefit from additional control over page routing, the link context can provide the desired experience. The link context allows users to jump to the relevant page within the app. It supports transparent multi-page workflows because the app can expose additional URLs that let the user navigate more intuitively between different routes in the app.
The App Extensions feature unlocks new use cases. The following sections organize use cases by the supported control panel page.
Public apps that use App Extensions have the following additional requirements for approval: