Skip to main content

App Manifest

The app manifest is usually defined in the bam-app.config.js file in during development. It includes information about your app, such as which permissions it requires and from where it can be loaded. To later get your app deployed you will need to provide a similar structure in a JSON-file to Bambuser, but for your staging / production setup.

Example of App manifest:

{
  "appManifest": {
    "permissions": [
      "showsPlayer:screens.write"
    ],
    "src": {
      "type": "module",
      "url": "https://your-domain.com/path-to-main.js"
    }
  }
}

Permissions​

All permissions are scoped per Apps host and during development you may start with allowing all permissions by using:

  • "showsPlayer:*" - Live Player
  • "callsWidget:*" - Video Consultation Calls Widget (shopper side)
  • "callsAgentTool:*" - Video Consultation Agent Tool (agent side)

While this is fine for development, it is not recommended for production because when a merchant installs your app in their Bam Hub, they will be asked to approve the permissions you have requested. If you request too many permissions, the merchant may not approve your app.

Permissions are defined as an array of strings in the permissions key in the app manifest. Each permission enables certain APIs for your app, and you should only request the permissions that your app actually needs. You can find the required permission for each API in the documentation for that API.

Entry point​

The src key in the app manifest is used to define the entry point of your app, which is the code that will run in the main context of your app without any visible UI.

You should select an entry point type that will allow the app framework to properly load your app, the supported types are:

  • "module" - This is the recommended type and is used to load a JavaScript module file from an URL.
  • "script" - When the app build tooling creates a bundle without javascript module support use this option.
  • "page" - Sometimes it may be easier to reference a full html page than a specific javascript entry point file. This option doesn’t need to contain more html code than setting up the necessary javascript environment like loading the required app framework runtime.js and the app code.

Definitions​

Some components, like screens require you to define your custom UI components in the app manifest. This is done by adding the related key to the app manifest (scoped per host), e.g. showsPlayer: { screens: [...] }. More details of how to provide these definitions can be found in the documentation for the related API.

Configurations​

Some apps may require configuration to be set up before they can be used. This may be things as simple as a color scheme or more complex things like API keys.

During development you can set up default values for these configurations in the bam-app.config.js file. When the merchant installs your app, they will be able to provide their own configuration values, so that your app receives it on start up.

We recommend you to build the app with logic that handles any missing configuration values by either having hardcoded defaults, skipping executing dependent code or as a last resort showing some error to the user for missing required configuration values.

The appConfig is provided as a root key in the configurations file, on the same level as appManifest.

Example file:

 "appManifest": {
    ...
  },
  "appConfig": {
    "myOwnVariable": "someDefaultValue",
  }

Example accessing app config variable:

  const { appConfig } = await bambuserAppFramework.getContext();
  console.log(appConfig.myOwnVariable); // "someDefaultValue"