Skip to main content

Methods

Note

Most of Shopify App Bridge's functionality relies on actions. See the Actions section to learn more about how to use these.

Anchor to Initialization methodsInitialization methods

Anchor to [object Object]createApp(config)

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

The config object should contain the following keys:

KeyTypeDescription
apiKeystringThe client ID provided for your application in the Partner Dashboard.
hoststringThe base64-encoded origin/domain of the Shopify shop, which is provided by Shopify as a query parameter on the initial load of your app in the Shopify Admin. The host is set dynamically and should be stored in the session from the initial load.
Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

import createApp from '@shopify/app-bridge';
const app = createApp(config);
var AppBridge = window['app-bridge'];
var createApp = AppBridge.createApp;
const app = createApp(config);

Anchor to App object methodsApp object methods

Anchor to [object Object]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.

KeyTypeDescription
actionActionOne of Shopify App Bridge's included actions.
app.dispatch(
Redirect.toRemote({
url: 'http://example.com',
}),
);

Anchor to [object Object]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.

KeyTypeDescription
callbackfunctionThe 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.Action.INVALID_PAYLOAD:
// Do something with the error
break;
}
});

// Unsubscribe from all errors
unsubscribeFromErrors();

Anchor to [object Object]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;
});

Anchor to [object Object]app.subscribe(callback, id?)

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

Arguments:

KeyTypeDescription
callbackfunctionThe function you want to execute when an action is dispatched.
idintThe 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();

Anchor to [object Object]app.subscribe(eventNameSpace, callback, id?)

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

Arguments:

KeyTypeDescription
eventNameSpacestringInclude this to subscribe only to actions of a particular type: for example, Modal.Action.OPEN. (optional)
callbackfunctionThe function you want to execute when an action is dispatched.
idintThe 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();

Anchor to Platform methodsPlatform methods

The following utility methods, available in the app-bridge 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.
  • isShopifyEmbedded: Returns true if the app is running as an embedded app.
import {isMobile, isShopifyEmbedded} from '@shopify/app-bridge/utilities';

if (isShopifyEmbedded()){
if (isMobile()) {
// app is running as an embedded on mobile
} else {
// app is running as an embedded app in a desktop web browser
}
} else {
// app is not running as an embedded app
}
Was this page helpful?