Glossary

The following glossary describes key App Extensions features.

Context

An App Extension’s context describes the control panel location where the Extension’s UI loads. The context determines the window dimensions of the iFrame where the Extension’s UI loads. There are currently two possible contexts:

Model

An App Extension’s model describes the control panel view it extends. Currently, App Extensions apply to the View All page of an API entity. There are currently three possible models:

Label

An App Extension’s label is the human-readable link text that describes it in the Action menu of each item listed on its model page.

For example, in the following App Extension, when a user is on the View Orders page and clicks Add personal thanks in the Action menu for any order, Add personal thanks is the label.

{
  "id": "bc/store/appExtension/2",
  "url": "/orders/${id}/personal-thanks",
  "model": "ORDERS",
  "label": {
    "defaultValue": "Add personal thanks"
  }
}

Label.defaultValue

Use English for an App Extension’s default label. BigCommerce uses this link text when the control panel locale settings do not correspond with any of the locale codes defined in the App Extension at label.locales.localeCode. The technical string length limit is 255 characters, but for the most predictable user experience, we suggest a length of ≤25 characters.

Label.locales

In the AppExtension mutation, the label.locales array describes alternate label text for control panel users using languages other than English. The locale labels render based on the Preferred language configured in My Profile > Profile Information. For a list of locales the control panel currently supports, see User Profile: Edit Profile (Help Center).

For example, in the following App Extension, when a user with their control panel language set to French is on the View Orders page and clicks Envoyez un merci personnel in the Action menu for any order, Envoyez un merci personnel is the label.

{
  "id": "bc/store/appExtension/2",
  "url": "/orders/${id}/personal-thanks",
  "model": "ORDERS",
  "label": {
    "defaultValue": "Add personal thanks",
    "locales": [
      {
        "value": "Envoyez un merci personnel",
        "localeCode": "fr-FR"
      }
    ]
  }
}

Label.locales.localeCode

For a list of locales the control panel currently supports, see User Profile: Edit Profile (Help Center).

Label.locales.value

BigCommerce uses this link text when the control panel locale settings correspond with the text’s accompanying locale code. The technical string length limit is 255 characters, but for the most predictable user experience, we suggest a length of ≤25 characters.

URL

The url is the App Extension’s path, or deep link. In the AppExtension mutation, the url contains variable parameters templated as JavaScript ES6+ strings. The string length limit is 255 characters.

When the user clicks the App Extension’s label, BigCommerce sends your app a load callback. The load callback’s signed_payload_jwt contains a url property in which the variable parameters you defined are replaced with data points injected by the referring model. Consider the following App Extension and action diagram:

{
  "id": "bc/store/appExtension/2",
  "url": "/orders/${id}/personal-thanks",
  "model": "ORDERS",
  "label": {
    "defaultValue": "Add personal thanks"
  }
}

signed_payload_jwt

The contextual information your app needs to load an App Extension is delivered using properties of our load callback’s signed_payload_jwt.

For more information, see Handling App Callbacks: Data Properties in the signed_payload_jwt.

Load callback

Clicking an App Extension menu item triggers the load callback. If you’re using the Next.js starter app, a significant amount of app callback complexity is handled for you under the covers. If you’re using a different stack or want to learn more, see Handling App Callbacks.