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 learn
Anchor 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_app
gem 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.
Requirements
Anchor link to section titled "Requirements"- Your app is embedded.
- Your app is built in Ruby, and uses the
shopify_app
gem. - 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 shopify_app
gem
Anchor link to section titled "Step 1: Update the shopify_app gem"Update 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 route
Anchor 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 embedded_redirect_url
Anchor link to section titled "Step 3: Configure an embedded_redirect_url"In your 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 reload
Anchor 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 1
. If embedded
doesn't exist or the value isn't 1
, then redirect to Shopify::Auth.embedded_app_url
.
The following snippet is an example of this logic in the Shopify Ruby app template's home controller: