Skip to main content

Methods

Deprecated

The Embedded App SDK (EASDK) is deprecated. After March 1st, 2022, apps that are using this SDK won't be listed on the Shopify App Store. Use Shopify App Bridge instead.

Anchor to ShopifyApp.init(config)ShopifyApp.init(config)

Note

The equivalent method in Shopify App Bridge is createApp.

Should be called immediately after the script file has loaded, as early as possible on the page (not in a jQuery.ready() or something). It will initialize data values, add postMessage listeners, check that the app is embedded in an iframe, and setup our initializers.

The config hash can contain the following keys:

KeyTypeDescription
apiKeyStringff9b1d04414785029e066f8fd0465d00 or similar. The client credentials provided to you for your application in the Partner Dashboard.
shopOriginStringThe origin of the Shopify shop. This will come out of the session values returned from the Shopify API and should be set dynamically for each different store. It'll be something like "https://example.myshopify.com" and should always include the protocol.
forceRedirectBooleanDefaults to true. Can be used to disable redirection into the admin for debugging or testing purposes.
debugbooleanDefaults to false. Will activate some console.log logging output.
ShopifyApp.init({
apiKey: "ff9b1d04414785029e066f8fd0465d00",
shopOrigin: "https://example.myshopify.com",
debug: false,
forceRedirect: true
});

Anchor to ShopifyApp.ready(fn)ShopifyApp.ready(fn)

Note

There is no equivalent method in Shopify App Bridge, as this functionality is no longer necessary.

Works similarly to jQuery's ready() function. It can be called many times on a page, it accepts functions, and when the Admin and the app are loaded it will call the functions in order.

ShopifyApp.ready(function(){
alert("Ready");
});

Anchor to ShopifyApp.pushState(path)ShopifyApp.pushState(path)

Note

The equivalent action in Shopify App Bridge is History.

Used to rewrite the current URL. This is called automatically and probably doesn't need to be explicitly called at all.

Anchor to ShopifyApp.flashNotice(message)ShopifyApp.flashNotice(message)

Note

The equivalent action in Shopify App Bridge is Toast.

Displays a message in the Shopify admin chrome styled as a notice. Use only for successful or neutral messages.

ShopifyApp.flashNotice("Unicorn was created successfully.");

Anchor to ShopifyApp.flashError(message)ShopifyApp.flashError(message)

Note

The equivalent action in Shopify App Bridge is Toast.

Displays a message in the Shopify admin chrome styled as an error. Use only for errors or failures.

ShopifyApp.flashError("Unicorn could not be created.");

Anchor to ShopifyApp.remoteRedirect(path)ShopifyApp.remoteRedirect(path)

Note

The equivalent action in Shopify App Bridge is Redirect.

Dispatches away from the app to a remote URL. The path must be an absolute URL prefixed with http or https.

ShopifyApp.remoteRedirect("https://my-app.example.com/auth/shopify?shop=my-shop-name")

Anchor to ShopifyApp.redirect(path)ShopifyApp.redirect(path)

Note

The equivalent action in Shopify App Bridge is Redirect.

Dispatches away from the app and into another section in the Shopify admin. The path should be prefixed with a slash, but should not include the /admin part. Example: /customers/120999015 or /settings/domains.

ShopifyApp.redirect("/orders");

Anchor to ShopifyApp.Bar.initialize(config)ShopifyApp.Bar.initialize(config)

Note

The equivalent action in Shopify App Bridge is TitleBar.

Accepts an object that defines how the top bar and buttons will look and behave. This should almost always be called in the ready() method. Default behavior if initialize is never called will result in some pretty safe defaults, except that the loading bar will never disappear.

The config object has a number of keys, all optional.

KeyTypeDescription
buttonsObjectAn object describing the buttons displayed in the top bar. The object contains two keys, primary and secondary, and each of those keys contain an array of button objects. Primary buttons default to blue, and have a maximum of one button. Secondary buttons have a maximum of four buttons.
titleStringThe title string displayed in the header behind the application's name.
paginationObjectAn object configuring and toggling the pagination arrow button group.
breadcrumbObjectA button object configuring and toggling the breadcrumb in the top bar. Can be applied only if a title has been set.

The configuration for pagination is a simplified version of button objects. When the pagination: key contains anything that is not falsy, the buttons will appear but will be inactive. The pagination: key expects an object containing two objects as previous: and next:, each describing a button. The button definition objects look like this:

KeyTypeDescription
callbackFunctionWhen the button is clicked, this function will be executed in the app.
hrefStringThe URL to be opened in the app.
loadingBooleanA boolean value stating if the loading bar should activate when this button is pressed. This defaults to true.
ShopifyApp.Bar.initialize({
buttons: {
primary: {
label: "Save",
message: 'bar_save'
},
secondary: [
{ label: "Help", callback: function(){ alert('help'); } },
{ label: "More",
type: "dropdown",
links: [
{ label: "Update", href: "/update", target: "app" },
{ label: "Delete", callback: function(){ alert("destroy") } }
]
},
{ label: "Preview", href: "http://my-app.com/preview_url", target: "new" }
],
},
title: 'Page Title',
pagination: {
next: {
href: "/posts?page=2"
},
previous: {
callback: function(){ alert('no previous pages') },
loading: false
}
},
breadcrumb: {
label: "Subsection",
href: "/subsection",
target: 'app',
loading: false
}
});

Anchor to ShopifyApp.Bar.loadingOff()ShopifyApp.Bar.loadingOff()

Note

The equivalent action in Shopify App Bridge is Loading.

Stops the loading bar. Should probably be called on every page in ShopifyApp.ready().

Anchor to ShopifyApp.Bar.loadingOn()ShopifyApp.Bar.loadingOn()

Note

The equivalent action in Shopify App Bridge is Loading.

Restarts the loading bar. It is a best practice to call it when moving between pages or firing off AJAX requests.

Anchor to ShopifyApp.Bar.setTitle(title)ShopifyApp.Bar.setTitle(title)

Note

The equivalent action in Shopify App Bridge is TitleBar.

Manually set the title string in the top bar. See ShopifyApp.Bar.initialize().

Anchor to ShopifyApp.Bar.setPagination(config)ShopifyApp.Bar.setPagination(config)

Note

The equivalent action in Shopify App Bridge is TitleBar.

Manually set the pagination arrows, or pass undefined to remove them entirely. See ShopifyApp.Bar.initialize().

Anchor to ShopifyApp.Bar.setBreadcrumb(config)ShopifyApp.Bar.setBreadcrumb(config)

Note

The equivalent action in Shopify App Bridge is TitleBar.

Manually set the breadcrumb in the top bar for an extra level of navigation. Pass a button object, or pass undefined to remove it entirely. See ShopifyApp.Bar.initialize(). Can be applied only if a title has been set with ShopifyApp.Bar.setTitle().

Anchor to ShopifyApp.Modal.open(init, fn)ShopifyApp.Modal.open(init, fn)

Note

The equivalent action in Shopify App Bridge is Modal.

Opens a modal dialog in the Shopify admin that in turn loads an iframe inside of it with the passed in URL. It accepts a src attribute to be loaded (which must have the same origin as the rest of your app), a title for the top of the bar, and a configuration of primary and secondary buttons identical to Bar.initialize(). It also accepts a callback function that is called when the modal is closed.

KeyTypeDescription
srcStringThe URL to be opened in the iframe.
titleStringThe title of the modal.
widthStringDefaults to small. This allows you to set a predetermined width for the modal. The acceptable values are:
large - 980px wide
fullwidth - Fills the width of the screen.
heightIntegerThis determines the height of the modal in pixels up to a maximum height of 700px and a minimum of 100px. The height is applied to the body (excluding the header and footer) of the rendered modal. This can also be set from within the modal using the ShopifyApp.Modal.setHeight() method.
buttonsObjectAn object describing the buttons displayed at the bottom of the modal. The object contains three keys, primary, secondary, and tertiary. Each of those keys contain an array of button objects. Primary buttons default to blue, are floated right, and have a maximum of one button. Secondary buttons are floated right and have a maximum of two buttons. Tertiary buttons are floated left and have a maximum of two buttons.
callbackFunctionWhen the modal is closed, this function will be executed in the app. Params are (result, data).
ShopifyApp.Modal.open({
src: 'https://example.com/app/path',
title: 'A new modal',
width: 'small',
height: 300,
buttons: {
primary: { label: "OK" },
secondary: [
{ label: "Cancel", callback: function (label) { ShopifyApp.Modal.close(); } }
]
}
}, function(result, data){
alert("result: " + result + " data: " + data);
});

Anchor to ShopifyApp.Modal.alert(options, fn)ShopifyApp.Modal.alert(options, fn)

Note

The equivalent action in Shopify App Bridge is Modal.

Opens a JavaScript style alert() in the admin. When the modal is closed the optional callback is called and a modal close message is sent.

ShopifyApp.Modal.alert("An alert message", function(result){
alert("The modal was closed.");
});

The options parameter can be a message to be displayed in the alert window, or it can be an object containing a message, a title for the modal, and a button label.

ShopifyApp.Modal.alert({
title: "Warning!",
message: "An alert message",
okButton: "I understand"
}, function(result){
alert("The modal was closed.");
});

Anchor to ShopifyApp.Modal.confirm(options, fn)ShopifyApp.Modal.confirm(options, fn)

Note

The equivalent action in Shopify App Bridge is Modal.

Opens a JavaScript style confirm() in the admin. When the modal is closed the optional callback is called and a modal close message is sent. The callback has the status of the closure passed in.

ShopifyApp.Modal.confirm("Are you sure you want to?", function(result){
if(result){
alert("yeah they're sure");
}
else{
alert("no, lets not");
}
});

The options parameter can be a message to be displayed in the confirm window, or it can be an object containing a message, a title for the modal, and labels for the 'OK' and 'Cancel' buttons.

ShopifyApp.Modal.confirm({
title: "Delete your account?",
message: "Do you want to delete your account? This can't be undone.",
okButton: "Yes, delete my account",
cancelButton: "No, keep my account",
style: "danger"
}, function(result){
alert("The modal was closed.");
});

All modal dialogs can also accept a style: 'danger' attribute which will change the primary button from blue to red, useful for delete confirmations.

Anchor to ShopifyApp.Modal.close(result, data)ShopifyApp.Modal.close(result, data)

Note

The equivalent action in Shopify App Bridge is Modal.

Closes the currently open modal window and manually sets the result and data payload. Result expects a true or false and data can contain the message payload, or nothing.

ShopifyApp.Modal.close(true, 'some data');

Anchor to ShopifyApp.Modal.setHeight(height)ShopifyApp.Modal.setHeight(height)

Note

The equivalent action in Shopify App Bridge is Modal.

Sets the height of the currently open modal window up to a maximum height of 700px and a minimum of 100px. The height is applied to the body (excluding the header and footer) of the rendered modal.

ShopifyApp.Modal.setHeight(320);

Anchor to ShopifyApp.User.currentShopifyApp.User.current

Note

The equivalent method in Shopify App Bridge is app.getState.

Returns an object representing the current user logged in to the admin. It is available anytime after the Shopify.ready call. Currently it only returns the accountAccess of the user.

KeyDescription
accountAccessCan have 3 possible values: Account owner, Full access, or Limited access. The value will depend on the account access level of the current logged-in user.

Here is an example:

ShopifyApp.ready(function(){
alert(ShopifyApp.User.current.accountAccess);
});

Anchor to ShopifyApp.Modal.productPicker(options, fn)ShopifyApp.Modal.productPicker(options, fn)

Note

The equivalent action in Shopify App Bridge is ResourcePicker.

Opens a modal dialog containing a list of the products or collections available in the store, with a search field for filtering results. The modal can be used for selecting one or more products/collections, using the resource picker's options.

The callback passed into the resource picker is invoked when the dialog is closed or a button is pressed. The callback is passed a success flag (boolean) which will be true if products are selected. The second parameter is a data object (JSON) which contains the selected products (if any) and any errors that may have surfaced.

Anchor to OptionsOptions

KeyDescription
selectMultipleDetermines if the user can select multiple products or collections.
showHiddenSelects if only published products are shown, or if true allows hidden (unpublished) resources to be selected. Defaults to true.

Anchor to Callback ,[object Object], argumentsCallback fn(success, data) arguments

KeyDescription
successWill be true if any products are selected.
data.productsWill contain an array of product objects (JSON), if any.
data.errorsWill contain an array of errors (string), if any.
var productPickerOptions = {
selectMultiple: false
};

ShopifyApp.Modal.productPicker(productPickerOptions, function(success, data) {
// Callback is triggered any time a button
// is clicked or the window is closed.

if (!success) {
// Success is true when a resource is picked successfully
return;
}

if (data.products.length > 0) {
var selectedProducts = data.products;
useSelectedProducts(selectedProducts);
}

if (data.errors) {
console.error(data.errors);
}
});

Anchor to ShopifyApp.Modal.collectionPicker(options, fn)ShopifyApp.Modal.collectionPicker(options, fn)

Note

The equivalent action in Shopify App Bridge is ResourcePicker.

The collection picker has the same interface as the product picker.

var multipleCollectionOptions = {
selectMultiple: true
};

ShopifyApp.Modal.collectionPicker(multipleCollectionOptions, function(
success,
data
) {
// Callback is triggered any time a button
// is clicked or the window is closed.

if (!success) {
// Success is true when a resource is picked successfully
return;
}

if (data.products.length > 0) {
var selectedProducts = data.products;
useSelectedProducts(selectedProducts);
}

if (data.errors) {
console.error(data.errors);
}
});

Anchor to Button objectsButton objects

Note

The equivalent action in Shopify App Bridge is Button.

Button objects are used to define buttons on the top bar and in modal windows. A button object has a required label field for the button text. It has optional fields for message which is the postMessage the admin will send when the button is clicked. It also accepts a callback function that is called on click. Alternatively it accepts a href attribute which will make the button open the provided link in a new window. The use case for the link is something like "Open preview in a new window".

Buttons can be defined as follows:

KeyTypeDescription
labelStringThe text displayed in the button.
messageStringThe value of the post message that Shopify will send down to the application that can then be listened for. Attributes such as callback and href create these messages manually and do not require this to be set.
callbackFunctionWhen the button is clicked, this function will be executed in the app. Params are (message, data).
hrefStringThe URL to be opened. It should be absolute for Admin links or external links. For links within Shopify it should be of the format /orders/123. The specific location where this link will be opened depends on the target attribute.
targetStringThe location where the value of the href will be opened. Default is app. The acceptable values are: new - Open a new window/tab.parent - Replace the current frame/window.shopify - A redirect to within the Shopify admin. A relative path without the admin prefix, like /products.app - Redirects the app's iframe to this URL. Essentially clicking a regular navigation link in the app.
loadingBooleanA boolean value stating if the loading bar should activate when this button is pressed. Shopify attempts to make a rational guess as to if this should be true or false depending on the action (ie: target: 'new' defaults to false, but target: 'app' defaults to true). It is always safe and prudent to override this value to be exactly what you require for your specific application.
styleStringOptional color styling for the button. It will always be a sane default, but can accept danger and disabled. If this is not set, primary buttons appear blue and secondary and tertiary buttons are white.
typeStringSets the button to become a dropdown button. Should be used alongside the links attribute. Current accepted value is dropdown. Only valid for secondary top bar buttons.
linksArrayA list of buttons. Accepts the same attributes as a regular button, like label, target and callback. Only valid for secondary top bar buttons.
Was this page helpful?