shopify_app 21.0.0 → 22.5.0

data/config/locales/nb.yml

@@ -3,19 +3,3 @@ nb:
   logged_out: Logget ut
   could_not_log_in: Kunne ikke logge på Shopify-butikken
   invalid_shop_url: Ugyldig butikkdomene
-  enable_cookies_heading: Aktiver informasjonskapsler fra %{app}
-  enable_cookies_body: Du kan manuelt aktivere informasjonskapsler i denne nettleseren
-    for å kunne bruke %{app} i Shopify.
-  enable_cookies_footer: Informasjonskapsler lar appen autentisere deg ved å midlertidig
-    lagre innstillingene og personopplysningene dine. De går ut etter 30 dager.
-  enable_cookies_action: Aktiver informasjonskapsler
-  top_level_interaction_heading: Nettleseren din må autentisere %{app}
-  top_level_interaction_body: Nettleseren din krever apper som %{app} for å spørre
-    deg om tilgang til informasjonskapsler før Shopify kan åpne den for deg.
-  top_level_interaction_action: Fortsett
-  request_storage_access_heading: "%{app} må ha tilgang til informasjonskapsler"
-  request_storage_access_body: Informasjonskapsler lar appen autentisere deg ved å
-    midlertidig lagre personopplysningene dine. Klikk på Fortsett og gi informasjonskapsler
-    tillatelse til å bruke appen.
-  request_storage_access_footer: Informasjonskapslene går ut etter 30 dager.
-  request_storage_access_action: Fortsett

data/config/locales/nl.yml

@@ -3,19 +3,3 @@ nl:
   logged_out: Je bent afgemeld
   could_not_log_in: Kon niet inloggen bij Shopify-winkel
   invalid_shop_url: Ongeldig winkeldomein
-  enable_cookies_heading: Schakel cookies in van %{app}
-  enable_cookies_body: Je moet cookies in deze browser handmatig inschakelen om %{app}
-    binnen Shopify te gebruiken.
-  enable_cookies_footer: Met cookies kan de app je verifiëren door je voorkeuren en
-    persoonlijke informatie tijdelijk op te slaan. Ze vervallen na 30 dagen.
-  enable_cookies_action: Schakel cookies in
-  top_level_interaction_heading: Je browser moet %{app} verifiëren
-  top_level_interaction_body: Je browser heeft apps nodig zoals %{app} om je toegang
-    te vragen tot cookies voordat Shopify het voor je kan openen.
-  top_level_interaction_action: Doorgaan
-  request_storage_access_heading: "%{app} heeft toegang tot cookies nodig"
-  request_storage_access_body: Hiermee kan de app je verifiëren door je persoonlijke
-    gegevens tijdelijk op te slaan. Klik op Doorgaan en sta cookies toe om de app
-    te gebruiken.
-  request_storage_access_footer: Cookies verlopen na 30 dagen.
-  request_storage_access_action: Doorgaan

data/config/locales/pl.yml

@@ -3,19 +3,3 @@ pl:
   logged_out: Pomyślne wylogowanie
   could_not_log_in: Nie można zalogować się do sklepu Shopify
   invalid_shop_url: Nieprawidłowa domena sklepu
-  enable_cookies_heading: Włącz korzystanie z plików cookie z %{app}
-  enable_cookies_body: Aby móc korzystać z %{app} w Shopify, musisz ręcznie włączyć
-    korzystanie z plików cookie w tej przeglądarce.
-  enable_cookies_footer: Pliki cookie umożliwiają uwierzytelnianie aplikacji przez
-    tymczasowe przechowywanie preferencji i danych osobowych. Wygasają one po 30 dniach.
-  enable_cookies_action: Włącz korzystanie z plików cookie
-  top_level_interaction_heading: Twoja przeglądarka wymaga uwierzytelnienia %{app}
-  top_level_interaction_body: Twoja przeglądarka wymaga takich aplikacji jak %{app},
-    aby poprosić o dostęp do plików cookie, zanim Shopify będzie mógł ją otworzyć.
-  top_level_interaction_action: Kontynuuj
-  request_storage_access_heading: "%{app} potrzebuje dostępu do plików cookie"
-  request_storage_access_body: Dzięki temu aplikacja może Cię uwierzytelniać, tymczasowo,
-    przechowując Twoje dane osobowe. Kliknij przycisk Kontynuuj i zezwalaj na pliki
-    cookie, aby korzystać z aplikacji.
-  request_storage_access_footer: Pliki cookie wygasają po 30 dniach.
-  request_storage_access_action: Kontynuuj

data/config/locales/pt-BR.yml

@@ -3,19 +3,3 @@ pt-BR:
   logged_out: Você saiu.
   could_not_log_in: Não foi possível fazer login na Shopify store
   invalid_shop_url: Domínio de loja inválido
-  enable_cookies_heading: Habilitar cookies de %{app}
-  enable_cookies_body: Você precisa habilitar manualmente os cookies neste navegador
-    para usar %{app} dentro da Shopify.
-  enable_cookies_footer: Os cookies permitem que o app o autentique armazenando temporariamente
-    suas preferências e dados pessoais. Eles expiram depois de 30 dias.
-  enable_cookies_action: Habilitar cookies
-  top_level_interaction_heading: Seu navegador precisa autenticar %{app}
-  top_level_interaction_body: Seu navegador exige que apps como o %{app} consultem
-    você sobre o acesso a cookies antes que a Shopify os abra.
-  top_level_interaction_action: Continuar
-  request_storage_access_heading: "%{app} precisa acessar cookies"
-  request_storage_access_body: Isso permite que o app autentique você armazenando
-    temporariamente seus dados pessoais. Clique em continuar e permita os cookies
-    para usar o app.
-  request_storage_access_footer: Os cookies expiram depois de 30 dias.
-  request_storage_access_action: Continuar

data/config/locales/pt-PT.yml

@@ -3,20 +3,3 @@ pt-PT:
   logged_out: Terminou a sessão com sucesso
   could_not_log_in: Não foi possível iniciar sessão na loja da Shopify
   invalid_shop_url: Domínio de loja inválido
-  enable_cookies_heading: Ativar cookies de %{app}
-  enable_cookies_body: Tem de ativar manualmente os cookies neste navegador para utilizar
-    %{app} dentro da Shopify.
-  enable_cookies_footer: Os cookies permitem que a aplicação o autentique armazenando
-    temporariamente as suas preferências e informações pessoais. Expiram ao fim de
-    30 dias.
-  enable_cookies_action: Ativar cookies
-  top_level_interaction_heading: O seu navegador tem de autenticar %{app}
-  top_level_interaction_body: O seu navegador exige que aplicações como %{app} lhe
-    solicitem o acesso de cookies, antes que a Shopify as possa abrir.
-  top_level_interaction_action: Continuar
-  request_storage_access_heading: "%{app} tem de aceder a cookies"
-  request_storage_access_body: Isto permite que a aplicação o autentique armazenando
-    temporariamente as suas informações pessoais. Clique em continuar e permita os
-    cookies para utilizar a aplicação.
-  request_storage_access_footer: Os cookies expiram ao fim de 30 dias.
-  request_storage_access_action: Continuar

data/config/locales/sv.yml

@@ -3,19 +3,3 @@ sv:
   logged_out: Har loggats ut
   could_not_log_in: Det gick inte att logga in i Shopify-butiken
   invalid_shop_url: Ogiltig butiksdomän
-  enable_cookies_heading: Aktivera cookies från %{app}
-  enable_cookies_body: Du måste aktivera cookies manuellt i den här webbläsaren för
-    att kunna använda %{app} inom Shopify.
-  enable_cookies_footer: Cookies låter appen autentisera dig genom att tillfälligt
-    lagra dina inställningar och personuppgifter. De upphör efter 30 dagar.
-  enable_cookies_action: Aktivera cookies
-  top_level_interaction_heading: Din webbläsare måste verifiera %{app}
-  top_level_interaction_body: Din webbläsare kräver att appar som %{app} frågar dig
-    om tillgång till cookies innan Shopify kan öppna den för dig.
-  top_level_interaction_action: Fortsätt
-  request_storage_access_heading: "%{app} behöver tillgång till cookies"
-  request_storage_access_body: Detta gör det möjligt för appen att autentisera dig
-    genom att tillfälligt lagra din personliga information. Klicka på fortsätt och
-    tillåta cookies att använda appen.
-  request_storage_access_footer: Cookies upphör efter 30 dagar.
-  request_storage_access_action: Fortsätt

data/config/locales/th.yml

@@ -3,18 +3,3 @@ th:
   logged_out: ออกจากระบบสำเร็จ
   could_not_log_in: ไม่สามารถเข้าสู่ระบบร้านค้า Shopify ได้
   invalid_shop_url: โดเมนร้านค้าไม่ถูกต้อง
-  enable_cookies_heading: เปิดใช้คุกกี้จาก %{app}
-  enable_cookies_body: คุณต้องเปิดใช้คุกกี้ด้วยตนเองในเบราว์เซอร์นี้เพื่อใช้งาน %{app}
-    ภายใน Shopify
-  enable_cookies_footer: คุกกี้ช่วยให้แอปตรวจสอบความถูกต้องของคุณด้วยการจัดเก็บความชื่นชอบและข้อมูลส่วนตัวของคุณชั่วคราว
-    คุกกี้จะหมดอายุหลังจาก 30 วัน
-  enable_cookies_action: เปิดใช้คุกกี้
-  top_level_interaction_heading: เบราว์เซอร์ของคุณต้องรับรองความถูกต้องของ %{app}
-  top_level_interaction_body: เบราว์เซอร์ของคุณต้องการแอปอย่าง %{app} เพื่อขอให้คุณเข้าถึงคุกกี้ก่อนที่
-    Shopify จะสามารถเปิดมันให้คุณได้
-  top_level_interaction_action: ดำเนินการต่อ
-  request_storage_access_heading: "%{app} ต้องการสิทธิ์การเข้าถึงคุกกี้"
-  request_storage_access_body: สิ่งนี้ช่วยให้แอปตรวจสอบความถูกต้องของคุณด้วยการจัดเก็บข้อมูลส่วนตัวของคุณชั่วคราว
-    คลิกดำเนินการต่อและอนุญาตให้คุกกี้ใช้แอป
-  request_storage_access_footer: คุกกี้จะหมดอายุหลังจาก 30 วัน
-  request_storage_access_action: ดำเนินการต่อ

data/config/locales/tr.yml

@@ -3,20 +3,3 @@ tr:
   logged_out: Oturum başarıyla kapatıldı
   could_not_log_in: Shopify mağazasında oturum açılamadı
   invalid_shop_url: Geçersiz mağaza alan adı
-  enable_cookies_heading: "%{app} uygulamasından çerezleri etkinleştir"
-  enable_cookies_body: "%{app} uygulamasını Shopify içinde kullanabilmek için bu tarayıcıda
-    çerezleri manuel olarak etkinleştirmelisiniz."
-  enable_cookies_footer: Çerezler, tercihlerinizi ve kişisel bilgilerinizi geçici
-    olarak saklayıp uygulamanın kimliğinizi doğrulamasına imkan tanır. Çerezlerin
-    süresi 30 gün sonra sonra sona erer.
-  enable_cookies_action: Çerezleri etkinleştir
-  top_level_interaction_heading: Tarayıcınızın %{app} kimliğini doğrulaması gerekiyor
-  top_level_interaction_body: Tarayıcınız, Shopify tarafından açılmadan önce %{app}
-    gibi uygulamaların sizden çerezlere erişim izni istemesini zorunlu tutuyor.
-  top_level_interaction_action: Devam
-  request_storage_access_heading: "%{app} uygulamasının çerezlere erişmesi gerekiyor"
-  request_storage_access_body: Böylece uygulama, kişisel bilgilerinizi geçici olarak
-    saklayıp kimliğinizi doğrulayabilir. Devam et'e tıklayın ve çerezlerin uygulamayı
-    kullanmasına izin verin.
-  request_storage_access_footer: Çerezlerin süresi 30 gün sonra sonra sona erer.
-  request_storage_access_action: Devam

data/config/locales/vi.yml

@@ -3,20 +3,3 @@ vi:
   logged_out: Đã đăng xuất thành công
   could_not_log_in: Không thể đăng nhập vào cửa hàng trên Shopify
   invalid_shop_url: Miền cửa hàng không hợp lệ
-  enable_cookies_heading: Bật cookie từ %{app}
-  enable_cookies_body: Bạn phải bật cookie trong trình duyệt này theo cách thủ công
-    để sử dụng %{app} trong Shopify.
-  enable_cookies_footer: Cookie cho phép ứng dụng xác thực bạn bằng cách tạm thời
-    lưu trữ tùy chọn và thông tin cá nhân của bạn. Những thông tin này sẽ hết hạn
-    sau 30 ngày.
-  enable_cookies_action: Bật cookie
-  top_level_interaction_heading: Trình duyệt của bạn cần xác thực %{app}
-  top_level_interaction_body: Trình duyệt của bạn cần các ứng dụng như %{app} để yêu
-    cầu quyền truy cập vào cookie thì Shopify mới có thể mở giúp bạn.
-  top_level_interaction_action: Tiếp tục
-  request_storage_access_heading: "%{app} cần quyền truy cập cookie"
-  request_storage_access_body: Nhờ vậy, ứng dụng có thể xác thực bạn bằng cách tạm
-    thời lưu trữ thông tin cá nhân của bạn. Nhấp vào tiếp tục và cho phép cookie sử
-    dụng ứng dụng.
-  request_storage_access_footer: Cookie sẽ hết hạn sau 30 ngày.
-  request_storage_access_action: Tiếp tục

data/config/locales/zh-CN.yml

@@ -3,14 +3,3 @@ zh-CN:
   logged_out: 已成功退出
   could_not_log_in: 无法登录到 Shopify 商店
   invalid_shop_url: 商店域名无效
-  enable_cookies_heading: 从 %{app} 启用 Cookie
-  enable_cookies_body: 您必须在此浏览器中手动启用 Cookie 才能在 Shopify 中使用 %{app}。
-  enable_cookies_footer: Cookie 使此应用能够通过暂时存储您的偏好设置和个人信息来验证您的身份。这些信息将在 30 天后过期。
-  enable_cookies_action: 启用 Cookie
-  top_level_interaction_heading: 您的浏览器需要对 %{app} 进行验证
-  top_level_interaction_body: 您的浏览器要求类似 %{app} 的应用向您申请访问 Cookie，之后 Shopify 才能为您打开它。
-  top_level_interaction_action: 继续
-  request_storage_access_heading: "%{app} 需要访问 Cookie"
-  request_storage_access_body: 这使此应用能够通过暂时存储您的个人信息来验证您的身份。点击继续并启用 Cookie 以使用此应用。
-  request_storage_access_footer: Cookie 将在 30 天后过期。
-  request_storage_access_action: 继续

data/config/locales/zh-TW.yml

@@ -3,14 +3,3 @@ zh-TW:
   logged_out: 登出成功
   could_not_log_in: 無法登入 Shopify 商店
   invalid_shop_url: 商店網域無效
-  enable_cookies_heading: 啟用 %{app} 的 Cookie
-  enable_cookies_body: 您必須在此瀏覽器中手動啟用 Cookie，才能夠在 Shopify 使用 %{app}。
-  enable_cookies_footer: Cookie 可讓應用程式暫時儲存您的偏好設定和個人資訊，藉此驗證您的身分，這些資料會在 30 天後失效。
-  enable_cookies_action: 啟用 Cookie
-  top_level_interaction_heading: 您的瀏覽器需要驗證 %{app}
-  top_level_interaction_body: 您的瀏覽器要求 %{app} 等應用程式向您請求 Cookie 的存取權限，才能讓 Shopify 為您開啟該應用程式。
-  top_level_interaction_action: 繼續
-  request_storage_access_heading: "%{app} 需要 Cookie 存取權限"
-  request_storage_access_body: Cookie 可讓應用程式暫時儲存您的個人資訊，藉此驗證您的身分。按一下繼續並允許 Cookie 使用此應用程式。
-  request_storage_access_footer: Cookie 將於 30 天後失效。
-  request_storage_access_action: 繼續

data/config/routes.rb

@@ -8,6 +8,7 @@ ShopifyApp::Engine.routes.draw do
     get login_url => :new, :as => :login
     post login_url => :create, :as => :authenticate
     get "logout" => :destroy, :as => :logout
+    get "patch_shopify_id_token" => :patch_shopify_id_token
 
     # Kept to prevent apps relying on these routes from breaking
     if login_url.gsub(%r{^/}, "") != "login"
@@ -26,6 +27,6 @@ ShopifyApp::Engine.routes.draw do
   end
 
   namespace :webhooks do
-    post ":type" => :receive
+    post "(:type)" => :receive
   end
 end

data/docs/Quickstart.md

@@ -4,13 +4,15 @@ This guide assumes you have completed the steps to create a new Rails app using
 
 #### Table of contents
 
-[Setup SSH tunnel for development](#setup-ssh-tunnel-for-development)
+[Optionally Setup SSH tunnel for development](#setup-ssh-tunnel-for-development)
 
 [Use Shopify App Bridge to embed your app in the Shopify Admin](#use-shopify-app-bridge-to-embed-your-app-in-the-shopify-admin)
 
-## Setup SSH tunnel for development
+## Optionally Setup SSH tunnel for development
 
-Your local app needs to be accessible from the public Internet in order to install it on a Shopify store, to use the [App Proxy Controller](/lib/generators/shopify_app/app_proxy_controller/templates/app_proxy_controller.rb) or receive [webhooks](/docs/shopify_app/webhooks.md).
+Local development supports both `http` and `https` schemes. By default `http` and localhost are used.
+
+To use `https`, your local app needs to be accessible from the public Internet in order to install it on a Shopify store to use the [App Proxy Controller](/lib/generators/shopify_app/app_proxy_controller/templates/app_proxy_controller.rb) or receive [webhooks](/docs/shopify_app/webhooks.md).
 
 In order to receive requests securely, you'll need to setup a tunnel from the internet to localhost. You can use [Cloudflare](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/run-tunnel/trycloudflare/) for this.
 
@@ -32,8 +34,15 @@ HOST='https://some-random-words.trycloudflare.com/'
 
 ## Use Shopify App Bridge to embed your app in the Shopify Admin
 
-A basic example of using [*Shopify App Bridge*](https://shopify.dev/tools/app-bridge) is included in the install generator. An instance Shopify App Bridge is automatically initialized in [shopify_app.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/shopify_app.js). 
+A basic example of using [*Shopify App Bridge*](https://shopify.dev/tools/app-bridge) is included in the install generator. An instance Shopify App Bridge is automatically initialized in [shopify_app.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/shopify_app.js).
+
+If you are using the `shopify_app` gem **without** the [frontend react template](https://github.com/Shopify/shopify-frontend-template-react), the [flash_messages.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/flash_messages.js) file converts Rails [flash messages](https://api.rubyonrails.org/classes/ActionDispatch/Flash.html) to App Bridge Toast actions automatically. If your app is embedded and you want to display flash messages you will need to update the session storage to allow for 3rd party cookies. So that the flash messages can be save in the session cookie.
+
+```ruby
+#session_store.rb
+Rails.application.config.session_store(:cookie_store, key: '_example_session', expire_after: 14.days, secure: true, same_site: 'None')
+```
 
-The [flash_messages.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/flash_messages.js) file converts Rails [flash messages](https://api.rubyonrails.org/classes/ActionDispatch/Flash.html) to App Bridge Toast actions automatically. By default, this library is included via [unpkg in the embedded_app layout](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/embedded_app.html.erb#L27). 
+By default, this library is included via [unpkg in the embedded_app layout](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/embedded_app.html.erb#L27).
 
 For more advanced uses it is recommended to [install App Bridge via npm or yarn](https://help.shopify.com/en/api/embedded-apps/app-bridge/getting-started#set-up-shopify-app-bridge-in-your-app).

data/docs/Troubleshooting.md

@@ -3,7 +3,7 @@
 #### Table of contents
 
 [Generators](#generators)
-  * [The `shopify_app:install` generator hangs](#the-shopifyappinstall-generator-hangs)
+  * [The `shopify_app:install` generator hangs](#the-shopify_appinstall-generator-hangs)
 
 [Rails](#rails)
   * [Known issues with Rails `v6.1`](#known-issues-with-rails-v61)
@@ -18,6 +18,8 @@
   * [My app can't make requests to the Shopify API](#my-app-cant-make-requests-to-the-shopify-api)
   * [I'm stuck in a redirect loop after OAuth](#im-stuck-in-a-redirect-loop-after-oauth)
 
+[Debugging Tips](#debugging-tips)
+
 ## Generators
 
 ### The shopify_app:install generator hangs
@@ -90,29 +92,6 @@ Edit `config/initializer/shopify_app.rb` and ensure the following configurations
 + config.shop_session_repository = 'Shop'
 ```
 
-#### Inspect server logs
-
-If you have checked the configurations above, and the app is still using cookies, then it is possible that the `shopify_app` gem defaulted to relying on cookies. This would happen when your browser allows third-party cookies and a session token was not successfully found as part of your request.
-
-In this case, check the server logs to see if the session token was invalid:
-
-```los
-[ShopifyApp::JWT] Failed to validate JWT: [JWT::<Error>] <Failure message>
-```
-
-*Example*
-
-```
-[ShopifyApp::JWT] Failed to validate JWT: [JWT::ImmatureSignature] Signature nbf has not been reached
-```
-
-**Note:** In a local development environment, you may want to temporarily update your `Gemfile` to point to a local instance of the `shopify_app` library instad of an installed gem. This will enable you to use a debugging tool like `byebug` to debug the library.
-
-```diff
-- gem 'shopify_app', '~> 14.2'
-+ gem 'shopify_app', path: '/path/to/shopify_app'
-```
-
 ### My app can't make requests to the Shopify API
 
 > **Note:** Session tokens cannot be used to make authenticated requests to the Shopify API. Learn more about authenticating your backend requests to Shopify APIs at [Shopify API authentication](https://shopify.dev/concepts/about-apis/authentication).
@@ -143,9 +122,43 @@ X-Shopify-API-Request-Failure-Unauthorized: true
 
 Then, use the [Shopify App Bridge Redirect](https://shopify.dev/tools/app-bridge/actions/navigation/redirect) action to redirect your app frontend to the app login URL if this header is set.
 
-
 ### I'm stuck in a redirect loop after OAuth
 
 In previous versions of `ShopifyApp::Authenticated` controller concern, App Bridge embedded apps were able to include the `Authenticated` controller concern in the `HomeController` and other embedded controllers. This is no longer supported due to browsers blocking 3rd party cookies to increase privacy. App Bridge 3 is needed to handle all embedded sessions.
 
 For more details on how to handle embeded sessions, refer to [the session token documentation](https://shopify.dev/apps/auth/oauth/session-tokens).
+
+### `redirect_uri is not whitelisted`
+
+* Ensure you have set the `HOST` environment variable to match your host's URL, e.g. `http://localhost:3000` or `https://my-host-name.trycloudflare.com`.
+* Update the app's URL and whitelisted URLs in App Setup on https://partners.shopify.com
+
+### `This app can’t load due to an issue with browser cookies`
+
+This can be caused by an infinite redirect due to a coding error
+To investigate the cause, you can add a breakpoint or logging to the `rescue` clause of `ShopifyApp::CallbackController`.
+
+One possible cause is that for XHR requests, the `Authenticated` concern should be used, rather than `RequireKnownShop`.
+See below for further details.
+
+## Controller Concerns
+### Authenticated vs RequireKnownShop
+The gem heavily relies on the `current_shopify_domain` helper to contextualize a request to a given Shopify shop. This helper is set in different and conflicting ways if the request is authenticated or not.
+
+Because of these conflicting approaches the `Authenticated` (for use in authenticated requests) and `RequireKnownShop` (for use in unauthenticated requests) controller concerns must *never* be included within the same controller.
+
+#### Authenticated Requests
+For authenticated requests, use the [`Authenticated` controller concern](https://github.com/Shopify/shopify_app/blob/main/app/controllers/concerns/shopify_app/authenticated.rb). The `current_shopify_domain` is set from the JWT for these requests.
+
+#### Unauthenticated Requests
+For unauthenticated requests, use the [`RequireKnownShop` controller concern](https://github.com/Shopify/shopify_app/blob/main/app/controllers/concerns/shopify_app/require_known_shop.rb). The `current_shopify_domain` is set from the query string parameters that are passed.
+
+## Debugging Tips
+
+If you do run into issues with the gem there are two useful techniques to apply: Adding log statements, and using an interactive debugger, such as `pry`.
+
+You can temporarily add log statements or debugger calls to the `shopify_app` or `shopify-api-ruby` gems:
+  * You can modify a gem using [`bundle open`](https://boringrails.com/tips/bundle-open-debug-gems)
+  * Alternatively, you can your modify your `Gemfile` to use local locally checked out gems with the the [`path` option](https://bundler.io/man/gemfile.5.html).
+
+Note that if you make changes to a gem, you will need to restart the app for the changes to be applied.

data/docs/Upgrading.md

@@ -4,6 +4,16 @@ This file documents important changes needed to upgrade your app's Shopify App v
 
 #### Table of contents
 
+[General Advice](#general-advice)
+
+[Unreleased](#unreleased)
+
+[Upgrading to `v22.2.0`](#upgrading-to-v2220)
+
+[Upgrading to `v22.0.0`](#upgrading-to-v2200)
+
+[Upgrading to `v20.3.0`](#upgrading-to-v2030)
+
 [Upgrading to `v20.2.0`](#upgrading-to-v2020)
 
 [Upgrading to `v20.1.0`](#upgrading-to-v2010)
@@ -20,7 +30,88 @@ This file documents important changes needed to upgrade your app's Shopify App v
 
 [Upgrading from `v8.6` to `v9.0.0`](#upgrading-from-v86-to-v900)
 
+## General Advice
+
+Although we strive to make upgrades as smooth as possible, some effort may be required to stay up to date with the latest changes to `shopify_app`.
+
+We strongly recommend you avoid 'monkeypatching' any existing code from `ShopifyApp`, e.g. by inheriting from `ShopifyApp` and then overriding particular methods. This can result in difficult upgrades. If your app does so, you will need to carefully check the gem's internal changes when upgrading.
+
+If you need to upgrade by more than one major version (e.g. from v18 to v20), we recommend doing one at a time. Deploy each into production to help to detect problems earlier.
+
+We also recommend the use of a staging site which matches your production environment as closely as possible.
+
+If you do run into issues, we recommend looking at our [debugging tips.](https://github.com/Shopify/shopify_app/blob/main/docs/Troubleshooting.md#debugging-tips)
+
+## Unreleased
+
+#### (v23.0.0) - Deprecated methods in CallbackController
+The following methods from `ShopifyApp::CallbackController` have been deprecated in `v23.0.0`
+- `perform_after_authenticate_job`
+- `install_webhooks`
+- `perform_post_authenticate_jobs`
+
+If you have overwritten these methods in your callback controller to modify the behavior of the inherited `CallbackController`, you will need to
+update your app to use configurable option `config.custom_post_authenticate_tasks` instead. See [post authenticate tasks](/docs/shopify_app/authentication.md#post-authenticate-tasks)
+for more information.
+
+#### (v23.0.0) - Removed `ShopifyApp::JWTMiddleware`
+The `ShopifyApp::JWTMiddleware` middleware has been removed in `v23.0.0`. This middleware was used to populate the following environment variables from the JWT session token:
+- `request.env["jwt.token"]`
+- `request.env["jwt.shopify_domain"]`
+- `request.env["jwt.shopify_user_id"]`
+- `request.env["jwt.expire_at"]`
+
+If you are using any of these variables in your app, you'll need to replace them. You can instead include the `ShopifyApp::WithShopifyIdToken` concern, which does the same JWT parsing as the middleware, and exposes the same values in the following helper methods:
+- `shopify_id_token`
+- `jwt_shopify_domain`
+- `jwt_shopify_user_id`
+- `jwt_expire_at`
+
+#### (v23.0.0) - Deprecated "ShopifyApp::JWT" class
+The `ShopifyApp::JWT` class has been deprecated in `v23.0.0`. Use [ShopifyAPI::Auth::JwtPayload](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/jwt_payload.rb)
+class from the `shopify_api` gem instead. A search and replace should be enough for this migration.
+  - `ShopifyAPI::Auth::JwtPayload` is a superset of the `ShopifyApp::JWT` class, and contains methods that were available in `ShopifyApp::JWT`.
+  - `ShopifyAPI::Auth::JwtPayload` raises `ShopifyAPI::Errors::InvalidJwtTokenError` if the token is invalid.
+
+## Upgrading to `v22.2.0`
+#### Added new feature for zero redirect embedded app authorization flow - Token Exchange
+A new embedded app authorization strategy has been introduced in `v22.2.0` that eliminates the redirects that were previously necessary for OAuth.
+It can replace the existing installation and authorization code grant flow.
+See [new embedded app authorization strategy](/README.md#new-embedded-app-authorization-strategy-token-exchange) for more information.
+
+## Upgrading to `v22.0.0`
+#### Dropped support for Ruby 2.x
+Support for Ruby 2.x has been dropped as it is no longer supported. You'll need to upgrade to 3.x.x
+
+#### Renamed Controller Concerns
+The following controller concerns have been renamed/replaced in `v21.10.0` and have now been removed. To upgrade, please rename any usage in your apps's controllers that include them to the following:
+
+|Old Deprecated Controller Concern |Replaced By New Controller Concern|
+|---|---|
+|`Authenticated`|`EnsureHasSession`|
+|`RequireKnownShop`|`EnsureInstalled`|
+
+The new names better reflect what assurances the including the controller concern provide. The new concern provide similar if not identical functionality as the concerns they replaced.
+
+#### Remove ScripttagManager
+Script tag usage has largely been replaced with the adoption of [theme app extensions](https://shopify.dev/docs/apps/online-store/theme-app-extensions) and [thank you order status customization](https://shopify.dev/docs/apps/checkout/thank-you-order-status). The manager has been removed with this major release due to effective replacement and a goal to have parity in supported functionality across language stacks.
+
+If you find yourself still using Scipt Tags and want to continue the pattern of declarative management of script tags this gem used to use, we recommend porting the logic [the manager used in prior versions](https://github.com/Shopify/shopify_app/blob/2336fabc6d0b45a4dee3f336455dace4d2d88bc4/lib/shopify_app/managers/scripttags_manager.rb#L4) and implementing it in a [post authentication job](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/authentication.md#run-jobs-after-the-oauth-flow). This is the recommended flow to create script tags (or any other logic) for stores that install your app.
+
+#### No longer rescue non-shopify API errors during customized OAuth flow
+If you have customized authentication logic and are counting on the `CallbackController` to catch your error and redirect to login, you'll need to catch that error and redirect to `login_url_with_optional_shop`.
+
+## Upgrading to 21.3.0
+The `Itp` controller concern has been removed from `LoginProtection` which is included by the `Authenticated`/`EnsureHasSession` controller concern.
+If any of your controllers are dependant on methods from `Itp` then you can include `ShopifyApp::Itp` directly.
+You may notice a deprecation notice saying, `Itp will be removed in an upcoming version`.
+This is because we intend on removing `Itp` completely in `v22.0.0`, but this will work in the meantime.
+
+## Upgrading to `v20.3.0`
+Calling `LoginProtection#current_shopify_domain` will no longer raise an error if there is no active session. It will now return a nil value. The internal behavior of raising an error on OAuth redirect is still in place, however. If you were calling `current_shopify_domain` in authenticated actions and expecting an error if nil, you'll need to do a presence check and raise that error within your app.
+
 ## Upgrading to `v20.2.0`
+
 All custom errors defined inline within the `ShopifyApp` gem have been moved to `lib/shopify_app/errors.rb`.
 
 - If you rescue any errors defined in this gem, you will need to rename them to match their new namespacing.
@@ -36,8 +127,11 @@ Note that the following steps are *optional* and only apply to **embedded** appl
 
 ## Upgrading to `v19.0.0`
 
-This update moves API authentication logic from this gem to the [`shopify_api`](https://github.com/Shopify/shopify-api-ruby)
-gem.
+There are several major changes in this release:
+
+* A change of strategy regarding sessions: Due to security changes with browsers, support for cookie based sessions was dropped. JWT is now the only supported method for managing sessions.
+* As part of that change, this update moves API authentication logic from this gem to the [`shopify_api`](https://github.com/Shopify/shopify-api-ruby) gem.
+* Previously the `shopify_api` gem relied on `ActiveResource`, an outdated library which was [removed](https://github.com/rails/rails/commit/f1637bf2bb00490203503fbd943b73406e043d1d) from Rails in 2012. v10 of `shopify_api` has a replacement approach which aims to provide a similar syntax, but changes will be necessary.
 
 ### High-level process
 
@@ -48,18 +142,20 @@ gem.
 - Remove `allow_jwt_authentication=` and `allow_cookie_authentication=` invocations from
   `config/initializers/shopify_app.rb` as the decision logic for which authentication method to use is now handled
   internally by the `shopify_api` gem, using the `ShopifyAPI::Context.embedded_app` setting.
-- `v19.0.0` updates the `shopify_api` dependency to `10.0.0`. This version of `shopify_api` has breaking changes. See
-  the documentation for addressing these breaking changes on GitHub [here](https://github.com/Shopify/shopify-api-ruby#breaking-change-notice-for-version-1000).
+- [Follow the guidance for upgrading `shopify-api-ruby`](https://github.com/Shopify/shopify-api-ruby#breaking-change-notice-for-version-1000).
 
 ### Specific cases
 
-#### Shopify user id in session
+#### Shopify user ID in session
 
 Previously, we set the entire app user object in the `session` object.
 As of v19, since we no longer save the app user to the session (but only the shopify user id), we now store it as `session[:shopify_user_id]`. Please make sure to update any references to that object.
 
 #### Webhook Jobs
 
+It is assumed that you have an ActiveJob implementation configured for `perform_later`, e.g. Sidekiq.
+Ensure your jobs inherit from `ApplicationJob` or `ActiveJob::Base`.
+
 Add a new `handle` method to existing webhook jobs to go through the updated `shopify_api` gem.
 
 ```ruby
@@ -95,32 +191,7 @@ Shopify API session, or `nil` if no such session is available.
 
 #### Setting up `ShopifyAPI::Context`
 
-The `shopify_app` initializer must configure the `ShopifyAPI::Context`. The Rails generator will
-generate a block in the `shopify_app` initializer. To do so manually, ensure the following is
-part of the `after_initialize` block in `shopify_app.rb`.
-
-```ruby
-Rails.application.config.after_initialize do
-  if ShopifyApp.configuration.api_key.present? && ShopifyApp.configuration.secret.present?
-    ShopifyAPI::Context.setup(
-      api_key: ShopifyApp.configuration.api_key,
-      api_secret_key: ShopifyApp.configuration.secret,
-      old_api_secret_key: ShopifyApp.configuration.old_secret,
-      api_version: ShopifyApp.configuration.api_version,
-      host_name: URI(ENV.fetch('HOST', '')).host || '',
-      scope: ShopifyApp.configuration.scope,
-      is_private: !ENV.fetch('SHOPIFY_APP_PRIVATE_SHOP', '').empty?,
-      is_embedded: ShopifyApp.configuration.embedded_app,
-      session_storage: ShopifyApp::SessionRepository,
-      logger: Rails.logger,
-      private_shop: ENV.fetch('SHOPIFY_APP_PRIVATE_SHOP', nil),
-      user_agent_prefix: "ShopifyApp/#{ShopifyApp::VERSION}"
-    )
-
-    ShopifyApp::WebhooksManager.add_registrations
-  end
-end
-```
+The `shopify_app` initializer must configure the `ShopifyAPI::Context`. The Rails generator will generate a block in the `shopify_app` initializer. To do so manually, you can refer to `after_initialize` block in the [template](https://github.com/Shopify/shopify_app/blob/main/lib/generators/shopify_app/install/templates/shopify_app.rb.tt).
 
 ## Upgrading to `v18.1.2`
 
@@ -128,7 +199,7 @@ Version 18.1.2 replaces the deprecated EASDK redirect with an App Bridge 2 redir
 
 ## Upgrading to `v17.2.0`
 
-### Different SameSite cookie attribute behaviour
+### Different SameSite cookie attribute behavior
 
 To support Rails `v6.1`, the [`SameSiteCookieMiddleware`](/lib/shopify_app/middleware/same_site_cookie_middleware.rb) was updated to configure cookies to `SameSite=None` if the app is embedded. Before this release, cookies were configured to `SameSite=None` only if this attribute had not previously been set before.