Getting started

What you get

The Embedded App SDK has a robust API that provides:

  • Custom modal windows
  • Alert, confirm and input dialogs
  • Top bar with icon, breadcrumbs, buttons, pagination and dropdown menus
  • Flash messages

Shopify's Polaris design system includes content guidelines, a component library, and a UI kit that you can use to build the Shopify look and feel into your own apps.

Enabling the Embedded App SDK

First, follow the Getting Started guide to create a development store and an app. Next, follow these steps to enable the Embedded App SDK for your Shopify app:

  1. From your Partner dashboard, click Apps.
  2. Click on the name of your app.
  3. From the app overview screen, click Extensions.
  4. Next to Embed in Shopify Admin, click Enable.
  5. Click Save at the top of the screen to confirm the changes to your app.
Enable easdk

Caution

Enabling this for existing apps that are not designed to use the SDK will result in users being unable to use your app. Once enabled, Shopify will attempt to load your app inside an iframe.

HTTPS, SSL Certificates and mixed content restrictions

The Shopify Admin uses HTTPS for all pages. Mixed content restrictions in web browsers requires all embedded applications to also run on HTTPS.

Publishing an embedded app in the App Store requires the app to have an SSL certificate. Failure to use SSL when running an embedded app will cause errors in web browsers, due to mixed content restrictions.

Note

To simplify local development, you can use an SSL tunnel to localhost such as ngrok.

OAuth

Since the application is 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 Embedded App SDK provides a method 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.

<script src="https://cdn.shopify.com/s/assets/external/app.js"></script>

<script type='text/javascript'>
  // substitute apiKey for your API key, and redirectUri for your whitelisted redirect URI
  const permissionUrl = `/oauth/authorize?client_id=${apiKey}&scope=read_products,read_orders&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(`https://${shopDomain}/admin/${permissionUrl}`);

  // If the current window is the 'child', change the parent's URL with ShopifyApp.redirect
  } else {
    ShopifyApp.redirect(permissionUrl);
  }
</script>

Read more about how to use OAuth with Shopify ›