Update your embedded app OAuth flow: Ruby
On August 23, 2022, we've updated the recommended method for authorizing embedded apps using OAuth. The new method increases performance and eliminates screen flicker caused by the number and types of redirects. Follow this tutorial to update your Ruby app to optimize your OAuth flow for user experience and performance.
What you'll learnAnchor link to section titled "What you'll learn"
In this tutorial, you'll learn how to update the
shopify_app gem to a version that lets you take advantage of the improved OAuth flow, and then update your app to follow our OAuth performance best practices.
This tutorial focuses on apps built using the Shopify Ruby app template. To learn about how to update your Node or PHP app, or to understand the steps that you might apply to an app written in another language, refer to Update your embedded app OAuth flow: Node and PHP.
You'll perform the following tasks:
- Update your
shopify_appgem to a version that follows OAuth performance best practices.
- Add code to escape the iframe used to display your embedded app.
- Add code to redirect to the embedded app URL.
RequirementsAnchor link to section titled "Requirements"
- Your app is embedded.
- Your app is built in Ruby, and uses the
- One of the following is true:
- Your app was created before August 23, 2022, either using Shopify CLI, or using the Ruby app template.
- Your app was created after August 23, 2022 using Shopify CLI, or using the Ruby app template, but you made significant changes to the OAuth flow.
- Your app was created after August 23, 2022, but you didn't use Shopify CLI or a Shopify app template as a starting point.
Step 1: Update the Anchor link to section titled "Step 1: Update the shopify_app gem"
shopify_app gem to version
20.1.1 or higher. Version
20.1.1 contains the bulk of the OAuth improvements.
Step 2: Add a new iframe escape routeAnchor link to section titled "Step 2: Add a new iframe escape route"
To handle escaping the iframe using Shopify App Bridge, you need to add a new route to your application frontend. This route initializes App Bridge, then uses the App Bridge
Redirect action to redirect to a URI defined in a new
redirectURI parameter. You'll conditionally redirect to the new route in a later step.
Using our previous recommendations, your app might have loaded Shopify App Bridge from the Shopify CDN using an inline script tag. Loading Shopify App Bridge from your app bundle increases the chance that the user’s browser can attempt to access this code from the cache.
Step 3: Configure an Anchor link to section titled "Step 3: Configure an embedded_redirect_url"
shopify_app initializer, configure
embedded_redirect_url to point to the path of your new iframe escape route. This configuration is used when your app needs to escape the iframe to redirect to the grant screen.
Step 4: Update controllers that render a full page reloadAnchor link to section titled "Step 4: Update controllers that render a full page reload"
To update the begin auth logic, update any controller that renders a full-page reload.
Using our previous recommendations, your app might use Shopify App Bridge to redirect to the embedded app URL. This would cause the app to load twice: once outside the iframe, and then again inside the iframe.
Your code should check whether a query parameter of
embedded exists, and has a value of
embedded doesn't exist or the value isn't
1, then redirect to
The following snippet is an example of this logic in the Shopify Ruby app template's home controller: