Skip to main content

App Architecture

In its simplest form an app consists of two parts:

  • App manifest - Defines your app, for example which permissions it requires and from where it can be loaded
  • main.js - App code

Example of App manifest:

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

Example of main.js:

const appContext = await bambuserAppFramework.getContext();
console.log('Hello World', appContext);
info

The global variable bambuserAppFramework is automatically exposed by the App Framework Runtime before the app is loaded within the Bambuser product. The method bambuserAppFramework.getContext() returns a promise that resolves a communication layer been your app and the Bambuser product that includes the app context and available APIs that may be used.

Apps host​

In Bambuser platform the Apps host has the responsibility to start all apps that a Bam Hub organization have installed. We identify each Apps host seperately and you will see and use the following ids when building your app:

  • "showsPlayer" - One-to-Many Player
  • "callsWidget" - One-to-One Call Widget (shopper side)
  • "callsAgentTool" - One-to-One Agent Tool (agent side)

Execution context​

When the Apps host starts your app it will initially start in something we call the main context. An app can then register custom views (ex. screens, dialogs and tools) which will be loaded and run into something we call a view context. Each context runs in a separate iframe.

Main context​

This is the execution context for the app’s main logic. Every app needs to provide an entry point to this main context. It will be available from that the app is initially loaded and until the user decides to close the Bambuser product.

In this context an app can register custom views, setup global state handling and perform long running tasks.

This context will not be able to display a UI, that is handled by a view context.

View context​

A view context is a context created for a specific custom view. There can be none, one or multiple view contexts visible at any given time to the user from one or multiple apps.

Screens, dialogs and tools are example of custom views that will be able to have a view context that can provide custom UI.

A view context will only be made available from when it’s shown until it’s hidden either by the user or from the Bambuser product’s logic. When a view context is closed, it will be destroyed and all its resources will be released, so you should make sure to send any necessary data to the main context to keep any state until next time its shown

A view context can interact with the main context and other Bambuser app framework APIs.

User Interfaces​

When providing any custom views we recommend that you follow the design guidlines provided in our Design Library to create a coherent look and feel for the end user. The quickest way to do so is leveraging our Bam UI library that also automatically applies any theming that the merchant have configured in the Bam Hub. The theming configuration can also be accessed from css variables or javascript app context that is automatically made available in custom views.

State Management​

Since view contexts cannot keep their state when they are closed, the main context is responsible for keeping the state of the app and sharing it with the view context when they are opened.

The view instance APIs have methods to handle bi-directional communication between the main context and the views context to keep the state in sync.

Considerations for building in iframes​

When you are building an app that runs in an iframe, there are some things you might need to consider. The app will be loaded from a different origin than the Bambuser product and merchant site and the same-origin policy will not apply and app iframe is treated as a third party context. It will also be sandboxed which will restrict the app from doing certain things that may otherwise be available.

Window object​

Accessing the window object will give you the window object of the iframe, not the top window.

Limited access to top window​

You cannot access things outside of the app iframe such as the top url the user has in their address bar. Trying to access things outside of your app’s frame may throw errors and crash your app.

Limited navigation​

You cannot navigate the user outside of the app iframe, trying to do so may throw errors and crash your app.

Cookies and local storage​

Your app runs it what would be considered a third-party context, and as such, you do not have access to the same cookies and local storage as the top window. Third party cookies are often blocked by default in browsers, and you should not rely on cookies or local storage to store state or user data.

Limited Web APIs​

Some web apis that normally may be available like creating new popup windows, modals, file downloads, orientation lock and pointer lock will be unavailable and trying to use them may throw errors and crash your app.

Post message​

window.postMessage is a way to communicate between iframes, and is the recommended way to communicate between your app and the top window if necessary.

Content Security Policy​

Content Security Policy (CSP) is a security feature that helps prevent attacks such as Cross Site Scripting (XSS) and may need to be taken into consideration when hosting your app’s code. Your app will either be loaded from https://<your-app-id>.app-framework.bambuser.com or your own domain.

X-Frame-Options​

X-Frame-Options is a security feature that can prevent your app from being loaded in an iframe and may need to be taken into consideration when hosting your app’s code. Your app will either be loaded from https://<your-app-id>.app-framework.bambuser.com or your own domain.