shopify_app 12.0.0 → 17.2.0

data/config/locales/nl.yml

@@ -1,20 +1,20 @@
 ---
 nl:
-  logged_out: u bent afgemeld
-  could_not_log_in: Kon niet aanmelden bij Shopify-winkel
+  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: U moet cookies in deze browser handmatig inschakelen om %{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 u verifiëren door uw voorkeuren en
+  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: Uw browser moet %{app} verifiëren
-  top_level_interaction_body: Uw browser heeft apps nodig zoals %{app} om u toegang
-    te vragen tot cookies voordat Shopify het voor u kan openen.
+  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 u verifiëren door uw persoonlijke
+  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.

data/config/locales/pt-BR.yml

@@ -4,7 +4,7 @@ pt-BR:
   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ê deve habilitar manualmente os cookies neste navegador
+  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.

data/config/locales/th.yml

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

data/config/locales/vi.yml

@@ -0,0 +1,22 @@
+---
+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

@@ -8,7 +8,7 @@ zh-CN:
   enable_cookies_footer: Cookie 使此应用能够通过暂时存储您的偏好设置和个人信息来验证您的身份。这些信息将在 30 天后过期。
   enable_cookies_action: 启用 Cookie
   top_level_interaction_heading: 您的浏览器需要对 %{app} 进行验证
-  top_level_interaction_body: 您的浏览器要求类似 %{app} 的应用向您请求访问 Cookie，之后 Shopify 才能为您打开它。
+  top_level_interaction_body: 您的浏览器要求类似 %{app} 的应用向您申请访问 Cookie，之后 Shopify 才能为您打开它。
   top_level_interaction_action: 继续
   request_storage_access_heading: "%{app} 需要访问 Cookie"
   request_storage_access_body: 这使此应用能够通过暂时存储您的个人信息来验证您的身份。单击继续并启用 Cookie 以使用此应用。

data/config/routes.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ShopifyApp::Engine.routes.draw do
   controller :sessions do
     get 'login' => :new, :as => :login

data/docs/Quickstart.md

@@ -1,103 +1,31 @@
-Quickstart
-==========
+# Quickstart
 
-Get started building and deploying a new Shopify App to Heroku in just a few minutes. This guide assumes you have Ruby/Rails installed on your computer already; if you haven't done that already start with [this guide.](https://guides.rubyonrails.org/v5.0/getting_started.html#installing-rails)
+This guide assumes you have completed the steps to create a new Rails app using the Shopify App gem found in the [*Usage*](/README.md#usage) section of the project's [*README*](/README.md).
 
-1. New Rails App (with postgres)
---------------------------------
+#### Table of contents
 
-To create a new Rails app and use this generator, open your terminal and run the following commands:
+[Make your app available to the internet](#make-your-app-available-to-the-internet)
 
-```sh
-$ rails new test-app --database=postgresql
-$ cd test-app
-$ git init
-$ git add .
-$ git commit -m 'new rails app'
-```
-
-2. Create a new Heroku app
---------------------------
-
-The next step is to create a new Heroku app to host your application. If you haven't got a Heroku account yet, create a free account [here](https://www.heroku.com/). 
-
-Head to the Heroku dashboard and create a new app, or run the following commands with the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli#download-and-install) installed, substituting `name` for the name of your own app:
-
-CLI:
-```sh
-$ heroku create name
-$ heroku git:remote -a name
-```
-
-Once you have created an app on Heroku, we need to let Git know where the Heroku server is so we can deploy to it later. Copy the app's name from your Heroku dashboard and substitute `appname.git` with the name you chose earlier:
+[Use Shopify App Bridge to embed your app in the Shopify Admin](#use-shopify-app-bridge-to-embed-your-app-in-the-shopify-admin)
 
-web:
-```sh
-# https://dashboard.heroku.com/new
-$ git remote add heroku git@heroku.com:appname.git
-```
+## Make your app available to the internet
 
-3. Create a new App in the Shopify Partner dashboard
------------------------------------------
-* Create a Shopify app in the [Partners dashboard](https://partner.shopify.com). For this tutorial, you can choose either a public or custom app, but you can [learn about App Types here.](https://help.shopify.com/en/manual/apps/app-types)
-[https://app.shopify.com/services/partners/api_clients](https://app.shopify.com/services/partners/api_clients)
-* Set the callback url to `https://<appname>.herokuapp.com/`
-* Choose an embedded app
-* Set the app's `redirect_uri` to `https://<appname>.herokuapp.com/auth/shopify/callback`
+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).
 
-4. Add ShopifyApp to Gemfile
-----------------------------
+Use a tunneling service like [ngrok](https://ngrok.com/), [Beeceptor](https://beeceptor.com/), [Mockbin](http://mockbin.org/), or [Hookbin](https://hookbin.com/) to make your development environment accessible to the internet.
 
-Run these commands to add the `shopify_app` Gem to your app:
+For example with [ngrok](https://ngrok.com/), run this command to set up a tunnel proxy to Rails' default port:
 
 ```sh
-$ echo "gem 'shopify_app'" >> Gemfile
-$ bundle install
+ngrok http 3000
 ```
 
-**Note:** we recommend using the latest version of Shopify Gem. Check the [Git tags](https://github.com/Shopify/shopify_app/tags) to see the latest release version and then add it to your Gemfile e.g `gem 'shopify_app', '~> 7.0.0'`
-
-5. Run the ShopifyApp generator
--------------------------------
-
-Generate the code for your app by running these commands: 
-
-```sh
-# Use the keys from your app you created in the partners area
-$ rails generate shopify_app --api_key <shopify_api_key> --secret <shopify_api_secret>
-$ git add .
-$ git commit -m 'generated shopify app'
-```
-
-If you forget to set your keys or redirect uri above, you will find them in the shopify_app initializer at: `/config/initializers/shopify_app.rb`.
-
-We recommend adding a gem or utilizing environment variables (`.env`) to handle your keys before releasing your app. [Learn more about using environment variables.](https://www.honeybadger.io/blog/ruby-guide-environment-variables/)
-
-6. Deploy your app
----------
-
-Once you've generated your app, push it into your Heroku environment to see it up and running:
-```sh
-$ git push heroku
-$ heroku run rake db:migrate
-```
-
-7. Install the App!
--------------------
-
-Ensure you have created a [development store](https://help.shopify.com/en/api/getting-started/making-your-first-request#create-a-development-store) using the Shopify Partner Dashboard. If you don't already have one, [create one by following these instructions](https://help.shopify.com/en/api/getting-started/making-your-first-request#create-a-development-store).
-
-##### Note: The following step will cause your store to become `transfer-disabled.` Read more about store transfer and why it's important [here](https://help.shopify.com/en/api/guides/store-transfers#transfer-disabled-stores). This is an irreversible change, so be sure you don't plan to transfer this store to a merchant.
-
-Install the app onto your new development store using the Partner Dashboard. Log in to your account, visit the apps page, click the app you created earlier, and looking for the `Test your app` instructions where you can select a store to install your app on.
-
-![Installing an app on the partners dashboard dropdown](/docs/install-on-dev-shop.png)
+See the [*Embed the app in Shopify*](https://shopify.dev/tutorials/build-rails-react-app-that-uses-app-bridge-authentication#embed-the-app-in-shopify) section of [*Build a Shopify app with Rails, React, and App Bridge*](https://shopify.dev/tutorials/build-rails-react-app-that-uses-app-bridge-authentication) to learn more.
 
-### OR
+## Use Shopify App Bridge to embed your app in the Shopify Admin
 
-![Installing an app on the partners dashboard card](/docs/test-your-app.png)
+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). 
 
-8. Great work! 
--------------------
+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). 
 
-You're done creating your first app on Shopify. Keep going and learn more by [diving into our full documentation](https://help.shopify.com/en/api/getting-started), or join our [community of developers.](https://community.shopify.com/c/Shopify-Apps/bd-p/shopify-apps)
+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/Releasing.md

@@ -1,17 +1,21 @@
-Releasing ShopifyApp
+# Releasing ShopifyApp
 
-1. Check the Semantic Versioning page for info on how to version the new release: http://semver.org
-2. Create a pull request with the following changes:
-  * Update the version of ShopifyApp in lib/shopify_app/version.rb
-  * Add a CHANGELOG entry for the new release with the date
-  * Change the title of the PR to something like: "Packaging for release X.Y.Z"
-3. Merge your pull request
-4. Pull from master so you have the latest version of the shopify_app
-5. Tag the HEAD with the version (Leave REV blank for HEAD or provide a SHA)
-  $ git tag vX.Y.Z
-6. Push out your tags
-  $ git push --tags
-7. Use Shipit to build and push the gem
+1. Make the code changes in a separate PR that doesn't modify the version.
+1. After that is merged, check the Semantic Versioning page for info on how to version the new release: http://semver.org
+1. Create a pull request with the following changes:
+    - Update the version of ShopifyApp in lib/shopify_app/version.rb
+    - Update the version of shopify_app in package.json
+    - Run `bundle` to update `Gemfile.lock`
+    - Add a CHANGELOG entry for the new release with the date
+    - Change the title of the PR to something like: "Packaging for release X.Y.Z"
+1. Merge your pull request
+1. Checkout and pull from master so you have the latest version of the shopify_app
+1. Tag the HEAD with the version
+    ```bash
+    $ git tag -f vX.Y.Z && git push --tags --force
+    ```
+1. Check that Create Release workflow successfully runs
+1. Use Shipit to build and push the gem
 
-If you see an error like 'You need to create the vX.Y.X tag first', clear GIT
+If you see an error like 'You need to create the vX.Y.X tag first', clear git
 cache in Shipit settings

data/docs/Troubleshooting.md

@@ -1,7 +1,24 @@
-Troubleshooting Shopify App
-===========
+# Troubleshooting Shopify App
 
-### Generator shopify_app:install hangs
+#### Table of contents
+
+[Generators](#generators)
+  * [The `shopify_app:install` generator hangs](#the-shopifyappinstall-generator-hangs)
+
+[Rails](#rails)
+  * [Known issues with Rails `v6.1`](#known-issues-with-rails-v61)
+
+[App installation](#app-installation)
+  * [My app won't install](#my-app-wont-install)
+  * [My app keeps redirecting to login](#my-app-keeps-redirecting-to-login)
+
+[JWT session tokens](#jwt-session-tokens)
+  * [My app is still using cookies to authenticate](#my-app-is-still-using-cookies-to-authenticate)
+  * [My app can't make requests to the Shopify API](#my-app-cant-make-requests-to-the-shopify-api)
+
+## Generators
+
+### The shopify_app:install generator hangs
 
 Rails uses spring by default to speed up development. To run the generator, spring has to be stopped:
 
@@ -11,6 +28,114 @@ $ bundle exec spring stop
 
 Run shopify_app generator again.
 
-### App installation fails with 'The page you’re looking for could not be found' if the app was installed before
+## Rails
+
+### Known issues with Rails `v6.1`
+
+If you recently upgraded your application's `Rails::Application` configuration to load the default configuration for Rails `v6.1`, then you will need to update the following `cookies_same_site_protection` ActionDispatch configuration.
+
+```diff
+# config/application.rb
+
+require_relative 'boot'
+
+require 'rails/all'
+
+Bundler.require(*Rails.groups)
+
+module AppName
+  class Application < Rails::Application
++    config.load_defaults 6.1
+
++    config.action_dispatch.cookies_same_site_protection = :none
+    ...
+  end
+end
+```
+
+As of Rails `v6.1`, the same-site cookie protection setting defaults  to `Lax`. This does not allow an embedded app to make cross-domain requests in the Shopify Admin.
+
+Alternatively, you can upgrade to [`v17.2.0` of the shopify_app gem](/docs/Upgrading.md#upgrading-to-v1720).
+
+## App installation
+
+### My app won't install
+
+#### App installation fails with 'The page you’re looking for could not be found' if the app was installed before
 
 This issue can occur when the session (the model you set as `ShopifyApp::SessionRepository.storage`) isn't deleted when the user uninstalls your app. A possible fix for this is listening to the `app/uninstalled` webhook and deleting the corresponding session in the webhook handler.
+
+## JWT session tokens
+
+### My app is still using cookies to authenticate
+
+#### `shopify_app` gem version
+
+Ensure the app is using shopify_app gem v13.x.x+. See [*Upgrading to `v13.0.0`*](/docs/Upgrading.md#upgrading-to-v1300).
+
+#### `shopify_app` gem Rails configuration
+
+Edit `config/initializer/shopify_app.rb` and ensure the following configurations are set:
+
+```diff
++ config.embedded_app = true
+
++ config.allow_jwt_authentication = true
++ config.allow_cookie_authentication = false
+
+# This line should already exist if you're using shopify_app gem 13.x.x+
++ 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).
+
+#### The Shopify API returns `401 Unauthorized`
+
+If your app uses [user-based token storage](/docs/shopify_app/session-repository.md#user-based-token-storage), then your app is configured to use **online** access tokens (see [API access modes](https://shopify.dev/concepts/about-apis/authentication#api-access-modes) to learn the difference between "online" and "offline" access tokens ). Unlike offline access tokens, online access tokens expire daily and cannot be used to make authenticated requests to the Shopify API once they expire.
+
+Converting your app to use session tokens means that your app will most likely not go through the OAuth flow as often as it did when relying on cookie sessions. Since the online access tokens stored in your app's database are refreshed during OAuth, this may cause your app's user session repository to use expired online access tokens.
+
+If the Shopify API  returns `401 Unauthorized`, handle this error on your app by redirecting the user to your login path to start the OAuth flow. As a result, your app will be given a new online access token for the current user.
+
+> **Note:** The following are examples to common app configurations. Your specific use-case may differ.
+
+##### Example solution
+
+Add the following line to your app's unauthorized response handler:
+
+```diff
++ redirect_to(ShopifyApp.configuration.login_url, shop: current_shopify_domain)
+```
+
+_Example:_ If your embedded app cannot handle server-side XHR redirects, then configure your app's unauthorized response handler to set a response header:
+
+```
+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.

data/docs/Upgrading.md

@@ -0,0 +1,126 @@
+# Upgrading 
+
+This file documents important changes needed to upgrade your app's Shopify App version to a new major version.
+
+#### Table of contents
+
+[Upgrading to `v17.2.0`](#upgrading-to-v1720)
+
+[Upgrading to `v13.0.0`](#upgrading-to-v1300)
+
+[Upgrading to `v11.7.0`](#upgrading-to-v1170)
+
+[Upgrading from `v8.6` to `v9.0.0`](#upgrading-from-v86-to-v900)
+
+## Upgrading to `v17.2.0`
+
+### Different SameSite cookie attribute behaviour
+
+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.
+
+```diff
+# same_site_cookie_middleware.rb
+- cookie << '; SameSite=None' unless cookie =~ /;\s*samesite=/i
++ cookie << '; SameSite=None' if ShopifyApp.configuration.embedded_app?
+```
+
+By default, Rails `v6.1` configures `SameSite=Lax` on all cookies that don't specify this attribute.
+
+## Upgrading to `v13.0.0`
+
+Version 13.0.0 adds the ability to use both user and shop sessions, concurrently. This however involved a large
+change to how session stores work. Here are the steps to migrate to 13.x
+
+### Changes to `config/initializers/shopify_app.rb`
+
+- *REMOVE* `config.per_user_tokens = [true|false]` this is no longer needed
+- *CHANGE* `config.session_repository = 'Shop'` To  `config.shop_session_repository = 'Shop'`
+- *ADD (optional)*  User Session Storage `config.user_session_repository = 'User'`
+
+### Shop Model Changes (normally `app/models/shop.rb`)
+
+-  *CHANGE* `include ShopifyApp::SessionStorage` to `include ShopifyApp::ShopSessionStorage`
+
+### Changes to the @shop_session instance variable (normally in `app/controllers/*.rb`)
+
+- *CHANGE* if you are using shop sessions, `@shop_session` will need to be changed to `@current_shopify_session`.
+
+### Changes to Rails `session`
+
+- *CHANGE* `session[:shopify]` is no longer set. Use `session[:user_id]` if your app uses user based tokens, or `session[:shop_id]` if your app uses shop based tokens.
+
+### Changes to `ShopifyApp::LoginProtection`
+
+`ShopifyApp::LoginProtection`
+
+- CHANGE if you are using `ShopifyApp::LoginProtection#shopify_session` in your code, it will need to be
+changed to `ShopifyApp::LoginProtection#activate_shopify_session`
+- CHANGE if you are using `ShopifyApp::LoginProtection#clear_shop_session` in your code, it will need to be
+changed to `ShopifyApp::LoginProtection#clear_shopify_session`
+
+### Notes
+You do not need a user model; a shop session is fine for most applications.
+
+---
+
+## Upgrading to `v11.7.0`
+
+### Session storage method signature breaking change
+If you override `def self.store(auth_session)` method in your session storage model (e.g. Shop), the method signature has changed to `def self.store(auth_session, *args)` in order to support user-based token storage. Please update your method signature to include the second argument.
+
+---
+
+## Upgrading from `v8.6` to `v9.0.0`
+
+### Configuration change
+
+Add an API version configuration in `config/initializers/shopify_app.rb`
+Set this to the version you want to run against by default. See [Shopify API docs](https://help.shopify.com/en/api/versioning) for versions available.
+```ruby
+config.api_version = '2019-04'
+```
+
+### Session storage change
+
+You will need to add an `api_version` method to your session storage object.  The default implementation for this is.
+```ruby
+def api_version
+  ShopifyApp.configuration.api_version
+end
+```
+
+### Generated file change
+
+`embedded_app.html.erb` the usage of `shop_session.url` needs to be changed to `shop_session.domain`
+```erb
+<script type="text/javascript">
+  ShopifyApp.init({
+    apiKey: "<%= ShopifyApp.configuration.api_key %>",
+
+    shopOrigin: "<%= "https://#{ @shop_session.url }" if @shop_session %>",
+
+    debug: false,
+    forceRedirect: true
+  });
+</script>
+```
+is changed to
+```erb
+<script type="text/javascript">
+  ShopifyApp.init({
+    apiKey: "<%= ShopifyApp.configuration.api_key %>",
+
+    shopOrigin: "<%= "https://#{ @shop_session.domain }" if @shop_session %>",
+
+    debug: false,
+    forceRedirect: true
+  });
+</script>
+```
+
+### ShopifyAPI changes
+
+You will need to also follow the ShopifyAPI [upgrade guide](https://github.com/Shopify/shopify_api/blob/master/README.md#-breaking-change-notice-for-version-700-) to ensure your app is ready to work with API versioning.
+
+[dashboard]:https://partners.shopify.com
+[app-bridge]:https://help.shopify.com/en/api/embedded-apps/app-bridge