Getting started with Shopify App Bridge
Embed your app in the Shopify admin
Anchor link to section titled "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:
- From your Partner Dashboard, click Apps.
- Click the name of your app.
- From the app overview screen, click App setup.
- In the Embedded app section, click Manage.
- In the Embed your app in Shopify admin section, click Enable.
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
Anchor link to section titled "Embed your app in Shopify POS"First, create a development store and an app.
To embed your app in Shopify POS:
- From your Partner Dashboard, click Apps.
- Click the name of your app.
- From the app overview screen, click App setup.
- In the Embedded app section, click Manage.
- In the Embed your app in Shopify POS section, click Enable.
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
Anchor link to section titled "HTTPS, SSL certificates, and mixed content restrictions"The Shopify admin uses HTTPS for all pages. Embedded applications also need to use HTTPS.
Failure to use SSL when running an embedded app will cause errors in web browsers, due to mixed content restrictions.
Set the frame-ancestors directive
Anchor link to section titled "Set the frame-ancestors directive"The Content Security Policy frame-ancestors
directive controls where the app can be framed. You must ensure your app is only frameable by the authenticated shop domain and the admin domain to avoid clickjacking attacks.
You can do this with the Content Security Policy frame-ancestors
directive:
Learn more about the frame-ancestors
directive and app security.
Set up Shopify App Bridge in your app
Anchor link to section titled "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:
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.
Authorize with OAuth
Anchor link to section titled "Authorize with OAuth"Since embedded applications are loaded inside an iframe, the initial OAuth redirect to Shopify must occur 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. 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.
What's next?
Anchor link to section titled "What's next?"At the end of the OAuth flow, the user is redirected to the redirectUri
you provided. We recommend 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
Anchor link to section titled "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.
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
Anchor link to section titled "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
.
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.