Update your embedded app OAuth flow: Node and PHP
On August 23, 2022, we've updated the recommended method for authorizing embedded apps using OAuth. The new method improves performance and eliminates screen flicker caused by the number and types of redirects. Follow this tutorial to update your Node or PHP app to optimize your OAuth flow for user experience and performance.
This tutorial focuses on apps built using Shopify Node and PHP app templates. However, you can still use this tutorial to understand the scope of the recommended changes, and review some example implementations.
What you'll learnAnchor link to section titled "What you'll learn"
In this tutorial, you'll learn how to update an app to follow our OAuth performance best practices.
You'll perform the following tasks:
- Add code to check for and 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 isn't built using Ruby. If it is, then follow the Ruby-specific tutorial.
- One of the following is true:
- Your app was created before August 23, 2022, either using Shopify CLI, or using the Node or PHP app template.
- Your app was created after August 23, 2022 using Shopify CLI, or using the Node or PHP 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: Add a new iframe escape routeAnchor link to section titled "Step 1: 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 2: Update the begin auth logicAnchor link to section titled "Step 2: Update the begin auth logic"
Using our previous recommendations, your app might attempt to escape an iframe whether or not it's present. In this step, you'll update your app's logic to escape the iframe only when needed.
To update the begin auth logic, add a utility that checks whether a request query parameter of
embedded exists, and has a value of
embedded=1, then the utility should render the route that you added to escape the iframe.
Call the iframe escape utilityAnchor link to section titled "Call the iframe escape utility"
The following table includes cases where you should call your new utility, and examples of how and where this utility is called in Shopify Node and PHP templates.
|Case||App template examples|
|The app isn't installed yet||Node
In previous versions of the PHP template, this logic was also present in a
Step 3: Redirect to the embedded app URLAnchor link to section titled "Step 3: Redirect to the embedded app URL"
After the user has granted access to your requested scopes, they should be returned to your app UI.
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.
Instead of using App Bridge, you should use the Shopify Admin API library
getEmbeddedAppUrl utility to build the embedded app URL. After you build the URL, you can perform a 3xx redirect to it.
Redirect to the URL provided by Anchor link to section titled "Redirect to the URL provided by getEmbeddedAppUrl"
The following table includes cases where you should
3xx redirect to the URL returned by the
getEmbeddedAppUrl utility, and examples of how and where this utility is called in Shopify Node and PHP templates.
|Case||App template examples|
|At the end of the OAuth process||
|When you receive a
Step 4: Remove old iframe escape codeAnchor link to section titled "Step 4: Remove old iframe escape code"
After you implement the changes to your OAuth flow, you can remove unused code. The following components were included in previous versions of Shopify app templates. If you didn't use an app template, then you might have components or code that fulfill similar functions.
|A top-level redirect utility that loaded Shopify App Bridge from the CDN, and then escaped the iframe and performed a redirect back to your app||