AppBridge

AppBridge is an interface that connects an App (running inside Dashboard) with the Dashboard itself.

Setup

Create instance of AppBridge by running the following code:

import { AppBridge } from "@saleor/app-sdk/app-bridge";

const appBridge = new AppBridge(options);

Options object is the following:

type AppBridgeOptions = {
  targetDomain?: string;
  saleorApiUrl?: string;
  initialLocale?: LocaleCode;
  autoNotifyReady?: boolean;
  initialTheme?: "dark" | "light";
};

AppState

You can get the current state of the app by calling appBridge.getState():

const { token, saleorApiUrl, ready, id } = appBridge.getState();

Available state represents AppBridgeState:

type AppBridgeState = {
  /**
  * JWT token provided by Dashboard. Represents user's session.
  */
  token?: string;
  /**
  * ID of the app
  */
  id: string;
  /**
  *  Flag if app bridge has properly initialized and authorized
  */
  ready: boolean;
  /**
  * Current path on the frontend
  */
  path: string;
  theme: ThemeType;
  locale: LocaleCode; // See src/locales.ts
  /**
   * Full URL including protocol and path where GraphQL API is available
   **/
  saleorApiUrl: string;
  /**
   * Versions of Saleor that app is being installed. Available from 3.15.
   */
  saleorVersion?: string;
  dashboardVersion?: string;
  user?: {
    /**
     * Original permissions of the user that is using the app.
     * *Not* the same permissions as the app itself.
     *
     * Can be used by app to check if user is authorized to perform
     * domain specific actions
     */
    permissions: Permission[];
    email: string;
  };
  /**
   * Permissions of the app itself
   */
  appPermissions?: AppPermission[];
};

Expand ▼

AppBridgeProvider

AppBridgeProvider and useAppBridge hook are exposed from @saleor/app-sdk:

// app.tsx
import { AppBridgeProvider } from "@saleor/app-sdk/app-bridge";

<AppBridgeProvider>
  <YourApp />
</AppBridgeProvider>;

AppBridgeProvider can optionally receive AppBridge instance in props, otherwise it will create one automatically.

useAppBridge hook

In components wrapped with AppBridgeProvider, you can use the useAppBridge hook:

import { useAppBridge } from "@saleor/app-sdk/app-bridge";
import { useEffect } from "react";

const MyComponent = () => {
  const { appBridge, appBridgeState } = useAppBridge();

  useEffect(() => {
    appBridge?.dispatch(/* Something */);
  }, [appBridge]);

  return <div>Current locale is: {appBridgeState?.locale}</div>;
};

appBridgeState? and appBridge can be nullish, because they don't exist in the server side context.

Events

Events are messages that originate in Saleor Dashboard. AppBridge can subscribe to events and the App can react to them.

Subscribing to events

subscribe(eventType, callback) - can be used to listen to particular event type. It returns an unsubscribe function, which unregister the callback.

Example:

const unsubscribe = appBridge.subscribe("handshake", (payload) => {
  setToken(payload.token); // do something with event payload

  const { token } = appState.getState(); // you can also get app's current state here
});

// unsubscribe when callback is no longer needed
unsubscribe();

Unsubscribing multiple listeners

unsubscribeAll(eventType?) - unregister all callbacks of provided type. If no type was provided, it will remove all event callbacks.

Example:

// unsubscribe from all handshake events
appBridge.unsubscribeAll("handshake");

// unsubscribe from all events
appBridge.unsubscribeAll();

Available event types

Event type	Description
handshake	Fired when iFrame containing the App is initialized or new token is assigned
response	Fired when Dashboard responds to an Action
redirect	Fired when Dashboard changes a subpath within the app path
theme	Fired when Dashboard changes the theme
localeChanged	Fired when Dashboard changes locale (and passes locale code in payload)
tokenRefresh	Fired when Dashboard receives a new auth token and passes it to the app

See source code for detailed payload

Actions

Actions expose a high-level API to communicate with Saleor Dashboard. They're exported under an actions namespace.

Available methods

dispatch(action) - dispatches an Action. Returns a promise which resolves when action is successfully completed.

Example:

import { actions } from "@saleor/app-sdk/app-bridge";

const handleRedirect = async () => {
  await appBridge.dispatch(actions.Redirect({ to: "/orders" }));

  console.log("Redirect complete!");
};

handleRedirect();

Available actions

Action	Arguments	Description
Redirect	to (string) - relative (inside Dashboard) or absolute URL path
	newContext (boolean) - should open in a new browsing context
Notification	status (info / success / warning / error / undefined)
	title (string / undefined) - title of the notification
	text (string / undefined) - content of the notification
	apiMessage (string / undefined) - error log from api
NotifyReady		Inform Dashboard that AppBridge is ready
UpdateRouting	newRoute - current path of App to be set in URL
RequestPermissions (>=3.15)	permissions - array of Permissions you want to add, redirectPath - value of query param app will receive in ?redirectUrl= after user approves/rejects permissions	Ask Dashboard to give more permissions to the app. Dashboard will unmount app. After user approves or denies, Dashboard will redirect to redirectPath. If operation fails, ?error=REASON will be appended