Getting started with Shopify App Bridge

Embed your app in the Shopify admin

First, create a development store and an app.

By default, new apps are embedded in the Shopify admin. If you need to turn on embedding for an app, follow these steps:

  1. From your Partner dashboard, click Apps.
  2. Click the name of your app.
  3. From the app overview screen, click Extensions.
  4. Expand the Embedded App section.
  5. Click Manage embedded app.
  6. Click Enable.
  7. Click Save at the top of the screen to confirm the changes to your app.

After you've enabled embedding for an app, Shopify attempts to load your app inside an iframe in the admin.

Embed your app in Shopify POS

First, create a development store and an app.

To embed your app in Shopify POS:

  1. From your Partner Dashboard, click Apps.

  2. Click the name of your app.

  3. Click Extensions.

  4. Click Point of Sale.

  5. In the Embedded POS app section, click Manage embedded POS app.

  6. Select the Embed in Shopify POS checkbox.

After you've enabled embedding for an app, your app appears in the Shopify POS mobile app.

To learn more about using your app with Shopify POS, visit our guide on Shopify POS.

HTTPS, SSL certificates, and mixed content restrictions

The Shopify admin uses HTTPS for all pages. Mixed content restrictions in web browsers require all embedded applications to also use HTTPS.

Failure to use SSL when running an embedded app will cause errors in web browsers, due to mixed content restrictions.

X-Frame-Options header

Web servers have the option of setting a response header of X-Frame-Options: DENY, which causes the web browser to refuse to render that page if the content window is inside some kind of frame. Since all embedded applications are rendered inside an iframe, this option must be turned off on your web server.

To learn more about X-Frame-Option headers, see the MDN web docs.

Set up Shopify App Bridge in your app

Shopify App Bridge is available as a JavaScript module on npm. To install it in your app (to use with bundlers or build systems like webpack), you can use npm or yarn:

Terminal
npm install --save @shopify/app-bridge

or

Terminal
yarn add @shopify/app-bridge

Shopify App Bridge can also be included directly on a page with a <script> tag pointing to a CDN-hosted copy of the library. Unpkg is an example of a CDN that hosts npm modules.

<script src="https://unpkg.com/@shopify/app-bridge"></script>
<script>
  var AppBridge = window['app-bridge'];
  var actions = window['app-bridge'].actions;
</script>

Authenticate with OAuth

Since embedded applications are loaded inside an iframe, it is critical that the initial OAuth redirect to Shopify occurs at the parent level, escaped from the iframe. Shopify returns the X-Frame-Options=DENY header and prevents any Shopify admin pages from being loaded inside an iframe. The Shopify App Bridge provides an action that can be used to perform a redirect within the parent window.

This means that where the OAuth process would normally begin with redirecting the merchant to the authorization prompt, it should instead return a page containing a script which escapes the frame.

Using modular JavaScript

import createApp from '@shopify/app-bridge';
import { Redirect } from '@shopify/app-bridge/actions';

const apiKey = 'API key from Shopify Partner Dashboard';
const redirectUri = 'allowed redirect URI from Shopify Partner Dashboard';
const permissionUrl = `https://${shopOrigin}/admin/oauth/authorize?client_id=${apiKey}&scope=read_products,read_content&redirect_uri=${redirectUri}`;

// If the current window is the 'parent', change the URL by setting location.href
if (window.top == window.self) {
  window.location.assign(permissionUrl);

  // If the current window is the 'child', change the parent's URL with Shopify App Bridge's Redirect action
} else {
  const app = createApp({
    apiKey: apiKey,
    shopOrigin: shopOrigin
  });

  Redirect.create(app).dispatch(Redirect.Action.REMOTE, permissionUrl);
}

Using ES5 and the CDN-hosted version

var AppBridge = window['app-bridge'];
var createApp = AppBridge.createApp;
var actions = AppBridge.actions;
var Redirect = actions.Redirect;

var apiKey = 'API key from Shopify Partner Dashboard';
var redirectUri = 'allowed redirect URI from Shopify Partner Dashboard';

var permissionUrl = 'https://'+
                    shopOrigin+
                    '/admin'+
                    '/oauth/authorize?client_id='+
                    apiKey+
                    '&scope=read_products,read_content&redirect_uri='+
                    redirectUri;

// If the current window is the 'parent', change the URL by setting location.href
if (window.top == window.self) {
  window.location.assign(permissionUrl);

  // If the current window is the 'child', change the parent's URL with Shopify App Bridge's Redirect action
} else {
  var app = createApp({
    apiKey: apiKey,
    shopOrigin: shopOrigin
  });

  Redirect.create(app).dispatch(Redirect.Action.REMOTE, permissionUrl);
}

What's next?

At the end of the authentication flow, the user will end up at the redirectUri you provided. It's highly recommended that you let App Bridge redirect the user back to Shopify. As part of the initialization process, App Bridge redirects the user if necessary to ensure your app is embedded in the Shopify admin.

Initialize Shopify App Bridge in your app

Once you’ve added Shopify App Bridge to your app, you need to initialize it by passing in your API key and the shop name.

Using modular JavaScript:

import createApp from '@shopify/app-bridge';
const app = createApp({
  apiKey: 'API key from Shopify Partner Dashboard',
  shopOrigin: shopOrigin
});

Using ES5 and the CDN-hosted version:

var AppBridge = window['app-bridge'];
var createApp = AppBridge.default;
var app = createApp({
  apiKey: 'API key from Shopify Partner Dashboard',
  shopOrigin: shopOrigin
});

The script detects if your app was loaded inside an iframe. If it wasn't, then the script creates a redirection back into the relative embedded URL in the Shopify admin. You can disable this functionality by passing forceRedirect: false as a configuration option.

Set up the Shopify TitleBar

On every page of your app, you should define the behavior of the Shopify TitleBar in relation to your application. For single-page apps (SPAs) you can update the title bar based on your app state. The following example script updates the TitleBar.

Using modular JavaScript:

import { TitleBar, Button, Redirect } from '@shopify/app-bridge/actions';

const breadcrumb = Button.create(app, { label: 'My breadcrumb' });
breadcrumb.subscribe(Button.Action.CLICK, () => {
  app.dispatch(Redirect.toApp({ path: '/breadcrumb-link' }));
});

const titleBarOptions = {
  title: 'My page title',
  breadcrumbs: breadcrumb
};

const myTitleBar = TitleBar.create(app, titleBarOptions);

Using CDN-hosted version:

var AppBridge = window['app-bridge'];
var actions = AppBridge.actions;
var TitleBar = actions.TitleBar;
var Button = actions.Button;
var Redirect = actions.Redirect;

var breadcrumb = Button.create(app, { label: 'My breadcrumb' });
breadcrumb.subscribe(Button.Action.CLICK, function() {
  app.dispatch(Redirect.toApp({ path: '/breadcrumb-link' }));
});

var titleBarOptions = {
  title: 'My page title',
  breadcrumbs: breadcrumb
};

var myTitleBar = TitleBar.create(app, titleBarOptions);

Next steps

Now that you've initialized your app, you can use any Shopify App Bridge actions.

You can also debug your app with Shopify App Bridge.