Methods

Initialization methods

createApp(config)

Returns an app object. Used to initialize your app instance.

The config object should contain the following keys:

Key Type Description
apiKey string The API key provided for your application in the Partners Dashboard.
shopOrigin string The origin/domain of the Shopify shop. This should be stored in the session. It is returned from the Shopify API and should be set dynamically for each different merchant/shop. The format is similar to "example.myshopify.com".

App object methods

app.dispatch(action)

Dispatches an action to Shopify App Bridge. Hosts (like Shopify Admin and Shopify Mobile) can subscribe to actions to listen for these dispatches.

Key Type Description
action Action One of Shopify App Bridge’s included actions.
app.dispatch(
  Redirect.toRemote({
    url: 'http://example.com',
  }),
);

app.error(callback)

Subscribe to all errors, including those that are caused by actions. Returns a method you can use to unsubscribe from all errors.

Key Type Description
callback function The function you want to execute when an error occurs.
const unsubscribeFromErrors = app.error((data) => {
  const {
    type,    // the error type
    action,  // the original action including its id
    message, // additional hints on how to fix the error
  } = data;

  // Handle all errors here

  switch(type) {
    case Error.ActionType.INVALID_PAYLOAD:
    // Do something with the error
    break;
  }
});

// Unsubscribe from all errors
unsubscribeFromErrors();

app.getState()

Returns a Promise which, when resolved, returns information about your app’s current state, including the currently logged in staff member.

app.getState().then((data) => {
  const {
    appInfo,
    loading,
    modal,
    navigation,
    pos,
    resourcePicker,
    staffMember,
    titleBar,
    toast
  } = data;
});

app.subscribe(callback, id?)

Subscribe to all actions. Returns a method you can use to unsubscribe.

Arguments:

Key Type Description
callback function The function you want to execute when an action is dispatched.
id int The ID of a particular action set instance to subscribe to (optional).
const unsubscribeFromAll = app.subscribe((data) => {
  // Handle all actions here
  console.log(data);
});

// Unsubscribe from all actions
unsubscribeFromAll();

app.subscribe(eventNameSpace, callback, id?)

When eventNameSpace or id are provided, this method subscribes to actions of the provided type.

Arguments:

Key Type Description
eventNameSpace string Include this to subscribe only to actions of a particular type: for example, Modal.Action.OPEN. (optional)
callback function The function you want to execute when an action is dispatched.
id int The ID of a particular action set instance to subscribe to (optional).
const unsubscribeModalOpen = app.subscribe(Modal.Action.OPEN, (data) => {
  // Do something whenever a Modal open action is dispatched
});

// Unsubscribe from Modal open actions
unsubscribeModalOpen();

Platform methods

The following utility methods, available in the app-bridge-utils package, return true or false depending on which platform an embedded app is running on:

  • isShopifyMobile: Returns true if the app is running on Shopify Mobile.
  • isShopifyPOS: Returns true if the app is running on Shopify POS.
  • isShopifyPing: Returns true if the app is running on Shopify Ping.
  • isMobile: Returns true if any of the conditions above are true.
import {isMobile} from '@shopify/app-bridge-utils';

if (isMobile()) {
  // app is running on mobile
} else {
  // app is running in a desktop web browser
}