shopify_app 13.2.0 → 20.2.0

data/docs/Upgrading.md

@@ -0,0 +1,247 @@
+# 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 `v20.2.0`](#upgrading-to-v2020)
+
+[Upgrading to `v20.1.0`](#upgrading-to-v2010)
+
+[Upgrading to `v19.0.0`](#upgrading-to-v1900)
+
+[Upgrading to `v18.1.2`](#upgrading-to-v1812)
+
+[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 `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.
+
+## Upgrading to `v20.1.0`
+
+Note that the following steps are *optional* and only apply to **embedded** applications. However, they can improve the loading time of your embedded app at installation and re-auth.
+
+- For embedded applications, update any controller that renders a full page reload (e.g: your home controller) to redirect using `Shopify::Auth.embedded_app_url`, if the `embedded` query argument is not present or does not equal `1`. Example [here](https://github.com/Shopify/shopify-app-template-ruby/pull/35/files#)
+- If your app already has a frontend that uses App Bridge, this gem now supports using that to redirect out of the iframe before OAuth.  Example [here](https://github.com/Shopify/shopify-frontend-template-react/blob/main/pages/ExitIframe.jsx)
+  - In your `shopify_app.rb` initializer, configure `.embedded_redirect_url` to the path of the route you added above.
+  - If you don't set this route, then the `shopify_app` gem will automatically load its own copy of App Bridge and perform this redirection without any additional configuration.
+
+## 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.
+
+### High-level process
+
+- Delete `config/initializers/omniauth.rb` as apps no longer need to initialize `OmniAuth` directly.
+- Delete `config/initializers/user_agent.rb` as `shopify_app` will set the right `User-Agent` header for interacting
+  with the Shopify API. If the app requires further information in the `User-Agent` header beyond what Shopify API
+  requires, specify this in the `ShopifyAPI::Context.user_agent_prefix` setting.
+- 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).
+
+### Specific cases
+
+#### 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
+
+Add a new `handle` method to existing webhook jobs to go through the updated `shopify_api` gem.
+
+```ruby
+class MyWebhookJob < ActiveJob::Base
+  extend ShopifyAPI::Webhooks::Handler
+
+  class << self
+    # new handle function
+    def handle(topic:, shop:, body:)
+      # delegate to pre-existing perform_later function
+      perform_later(topic: topic, shop_domain: shop, webhook: body)
+    end
+  end
+
+  # original perform function
+  def perform(topic:, shop_domain:, webhook:)
+    # ...
+```
+
+#### Temporary sessions
+
+The new `shopify_api` gem offers a utility to temporarily create sessions for interacting with the API within a block.
+This is useful for interacting with the Shopify API outside of the context of a subclass of `AuthenticatedController`.
+
+```ruby
+ShopifyAPI::Auth::Session.temp(shop: shop_domain, access_token: shop_token) do |session|
+  # make invocations to the API
+end
+```
+
+Within a subclass of `AuthenticatedController`, the `current_shopify_session` function will return the current active
+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
+```
+
+## Upgrading to `v18.1.2`
+
+Version 18.1.2 replaces the deprecated EASDK redirect with an App Bridge 2 redirect when attempting to break out of an iframe. This happens when an app is installed, requires new access scopes, or re-authentication because the login session is expired.
+
+## 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/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-ruby/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://shopify.dev/apps/tools/app-bridge

data/docs/shopify_app/authentication.md

@@ -0,0 +1,128 @@
+# Authentication
+
+The Shopify App gem implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) to get [access tokens](https://shopify.dev/concepts/about-apis/authentication#api-access-modes). These are used to authenticate requests made by the app to the Shopify API. 
+
+By default, the gem generates an embedded app frontend that uses [Shopify App Bridge](https://shopify.dev/tools/app-bridge) to fetch [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens). Session tokens are used by the embedded app to make authenticated requests to the app backend. 
+
+See [*Authenticate an embedded app using session tokens*](https://shopify.dev/tutorials/authenticate-your-app-using-session-tokens) to learn more. 
+
+> ⚠️ Be sure you understand the differences between the types of authentication schemes before reading this guide.
+
+#### Table of contents
+
+[OAuth callback](#oauth-callback)
+
+[Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+
+[Rotate API credentials](#rotate-api-credentials)
+
+[Available authentication mixins](#available-authentication-mixins)
+  * [`ShopifyApp::Authenticated`](#shopifyappauthenticated)
+  * [`ShopifyApp::EnsureAuthenticatedLinks`](#shopifyappensureauthenticatedlinks)
+
+## OAuth callback
+
+>️ **Note:** In Shopify App version 8.4.0, we have extracted the callback logic in its own controller. If you are upgrading from a version older than 8.4.0 the callback action and related helper methods were defined in `ShopifyApp::SessionsController` ==> you will have to extend `ShopifyApp::CallbackController` instead and port your logic to the new controller.
+
+Upon completing the OAuth flow, Shopify calls the app at the `callback_path`. If the app needs to do some extra work, it can define and configure the route to a custom callback controller, inheriting from `ShopifyApp::CallbackController` and hook into or override any of the defined helper methods. The default callback controller already provides the following behaviour:
+* Logging into the shop and resetting the session
+* [Installing Webhooks](/docs/shopify_app/webhooks.md)
+* [Setting Scripttags](/docs/shopify_app/script-tags.md)
+* [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+* Redirecting to the return address
+
+## Run jobs after the OAuth flow
+
+See [`ShopifyApp::AfterAuthenticateJob`](/lib/generators/shopify_app/add_after_authenticate_job/templates/after_authenticate_job.rb).
+
+If your app needs to perform specific actions after the user is authenticated successfully (i.e. every time a new session is created), ShopifyApp can queue or run a job of your choosing (note that we already provide support for automatically creating Webhooks and Scripttags). To configure the after authenticate job, update your initializer as follows:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.after_authenticate_job = { job: "Shopify::AfterAuthenticateJob" }
+end
+```
+
+The job can be configured as either a class or a class name string.
+
+If you need the job to run synchronously add the `inline` flag:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.after_authenticate_job = { job: Shopify::AfterAuthenticateJob, inline: true }
+end
+```
+
+We've also provided a generator which creates a skeleton job and updates the initializer for you:
+
+```
+bin/rails g shopify_app:add_after_authenticate_job
+```
+
+If you want to perform that action only once, e.g. send a welcome email to the user when they install the app, you should make sure that this action is idempotent, meaning that it won't have an impact if run multiple times.
+
+## Rotate API credentials
+
+If your Shopify secret key is leaked, you can use the RotateShopifyTokenJob to perform [API Credential Rotation](https://help.shopify.com/en/api/getting-started/authentication/oauth/api-credential-rotation).
+
+Before running the job, you'll need to generate a new secret key from your Shopify Partner dashboard, and update the `/config/initializers/shopify_app.rb` to hold your new and old secret keys:
+
+```ruby
+config.secret = Rails.application.secrets.shopify_secret
+config.old_secret = Rails.application.secrets.old_shopify_secret
+```
+
+We've provided a generator which creates the job and an example rake task:
+
+```sh
+bin/rails g shopify_app:rotate_shopify_token_job
+```
+
+The generated rake task will be found at `lib/tasks/shopify/rotate_shopify_token.rake` and is provided strictly for example purposes. It might not work with your application out of the box without some configuration.
+
+```ruby
+strategy.options[:old_client_secret] = ShopifyApp.configuration.old_secret
+```
+
+> **Note:** If you are updating `shopify_app` from a version prior to 8.4.2 (and do not wish to run the default/install generator again), you will need to add [the following line](https://github.com/Shopify/shopify_app/blob/4f7e6cca2a472d8f7af44b938bd0fcafe4d8e88a/lib/generators/shopify_app/install/templates/shopify_provider.rb#L18) to `config/initializers/omniauth.rb`:
+
+## Available authentication mixins
+
+### `ShopifyApp::Authenticated`
+
+The engine provides a [`ShopifyApp::Authenticated`](/app/controllers/concerns/shopify_app/authenticated.rb) concern which should be included in any controller that is intended to be behind Shopify OAuth. It adds `before_action`s to ensure that the user is authenticated and will redirect to the Shopify login page if not. It is best practice to include this concern in a base controller inheriting from your `ApplicationController`, from which all controllers that require Shopify authentication inherit.
+
+*Example:*
+
+```rb
+class AuthenticatedController < ApplicationController
+  include ShopifyApp::Authenticated
+end
+
+class ApiController < AuthenticatedController
+  # Actions in this controller are protected
+end
+```
+
+For backwards compatibility, the engine still provides a controller called `ShopifyApp::AuthenticatedController` which includes the `ShopifyApp::Authenticated` concern. Note that it inherits directly from `ActionController::Base`, so you will not be able to share functionality between it and your application's `ApplicationController`.
+
+#### Embedded apps and `ShopifyApp::Authenticated`
+
+Embedded Shopify Admin apps can only use the `ShopifyApp::Authenticated` controller concern *if* the requests originate from App Bridge's `authenticatedFetch` method. Those who include this concern in the `HomeController` or some other embedded controller will see what looks like an OAuth redirect loop as the `ShopifyApp::Authenticated` concern will be fighting with the App Bridge. For more details on how to handle embedded sessions, refer to [the session token documentation](https://shopify.dev/apps/auth/oauth/session-tokens).
+
+### `ShopifyApp::EnsureAuthenticatedLinks`
+
+The [`ShopifyApp::EnsureAuthenticatedLinks`](/app/controllers/concerns/shopify_app/ensure_authenticated_links.rb) concern helps authenticate users that access protected pages of your app directly.
+
+Include this concern in your app's `AuthenticatedController` if your app uses session tokens with [Turbolinks](https://github.com/turbolinks/turbolinks). It adds a `before_action` filter that detects whether a session token is present or not. If a session token is not found, the user is redirected to your app's splash page path (`root_path`) along with `return_to` and `shop` parameters.
+
+*Example:*
+
+```rb
+class AuthenticatedController < ApplicationController
+  include ShopifyApp::EnsureAuthenticatedLinks
+  include ShopifyApp::Authenticated
+end
+```
+
+See [Authenticate server-side rendered embedded apps using Rails and Turbolinks](https://shopify.dev/tutorials/authenticate-server-side-rendered-embedded-apps-using-rails-and-turbolinks) for more information.

data/docs/shopify_app/content-security-policy.md

@@ -0,0 +1,10 @@
+# Content Security Policy Header
+
+Shopify App [handles Rails' configuration](https://edgeguides.rubyonrails.org/security.html#content-security-policy-header) for [Content-Security-Policy Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) when the `ShopifyApp::FrameAncestors` controller concern is included in controllers. This is tyipcally done by including the [`ShopifyApp::Authenticated`](https://github.com/Shopify/shopify_app/blob/ed41165ca9598d2c9d514487365192f22b5eb096/app/controllers/concerns/shopify_app/authenticated.rb) controller concern rather that directly including it.
+
+## Included Domains
+
+For actions that include the `ShopifyApp::FrameAncestors` controller concern, the following hosts are added to the Content-Security-Policy header as [per the store requirements](https://shopify.dev/apps/store/security/iframe-protection#embedded-apps):
+
+1. [`current_shopify_domain`](https://github.com/Shopify/shopify_app/blob/ed41165ca9598d2c9d514487365192f22b5eb096/app/controllers/concerns/shopify_app/require_known_shop.rb#L13) || `"*.myshopify.com"` if current shopify domain isn't present
+2. "https://admin.shopify.com"

data/docs/shopify_app/engine.md

@@ -0,0 +1,82 @@
+# Engine
+
+#### Table of contents
+
+[Customize the app login URL](#customize-the-app-login-url)
+
+[Mount the Shopify App engine at nested routes](#mount-the-shopify-app-engine-at-nested-routes)
+
+[Verify HTTP requests sent via an app proxy](#verify-http-requests-sent-via-an-app-proxy)
+  * [Recommended usage of `ShopifyApp::AppProxyVerification`](#recommended-usage-of-shopifyappappproxyverification)
+
+## Customize the app login URL
+
+While you can customize the login view by creating a `/app/views/shopify_app/sessions/new.html.erb` file, you may also want to customize the URL entirely. You can modify your `shopify_app.rb` initializer to provide a custom `login_url` e.g.:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.login_url = 'https://example.com/nested/login'
+end
+```
+
+## Mount the Shopify App engine at nested routes
+
+The engine may also be mounted at a nested route, for example:
+
+```ruby
+mount ShopifyApp::Engine, at: '/nested'
+```
+
+This will create the Shopify engine routes under the specified subpath. You'll also need to make some updates to your `shopify_app.rb` and `omniauth.rb` initializers. First, update the shopify_app initializer to include a custom `root_url` e.g.:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.root_url = '/nested'
+end
+```
+
+then update the omniauth initializer to include a custom `callback_path` e.g.:
+
+```ruby
+provider :shopify,
+  ShopifyApp.configuration.api_key,
+  ShopifyApp.configuration.secret,
+  scope: ShopifyApp.configuration.scope,
+  callback_path: '/nested/auth/shopify/callback'
+```
+
+You may also need to change your `config/routes.rb` to render a view for `/nested`, since this is what will be rendered in the Shopify Admin of any shops that have installed your app.  The engine itself doesn't have a view for this, so you'll need something like this:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  root :to => 'something_else#index'
+  get "/nested", to: "home#index"
+  mount ShopifyApp::Engine, at: '/nested'
+end
+```
+
+Finally, note that if you do this, to add your app to a store, you must navigate to `/nested` in order to render the `Enter your shop domain to log in or install this app.` UI.
+
+## Verify HTTP requests sent via an app proxy
+
+See [`ShopifyApp::AppProxyVerification`](/lib/shopify_app/controller_concerns/app_proxy_verification.rb).
+
+The engine provides a mixin for verifying incoming HTTP requests sent via an App Proxy. Any controller that `include`s `ShopifyApp::AppProxyVerification` will verify that each request has a valid `signature` query parameter that is calculated using the other query parameters and the app's shared secret.
+
+### Recommended usage of `ShopifyApp::AppProxyVerification`
+
+The App Proxy Controller Generator automatically adds the mixin to the generated app_proxy_controller.rb
+Additional controllers for resources within the App_Proxy namespace, will need to include the mixin like so:
+
+```ruby
+# app/controllers/app_proxy/reviews_controller.rb
+class ReviewsController < ApplicationController
+  include ShopifyApp::AppProxyVerification
+  # ...
+end
+```
+
+Create your app proxy URL in the [Shopify Partners dashboard](https://partners.shopify.com/organizations), making sure to point it to `https://example.com/app_proxy`.
+
+![Creating an App Proxy](/images/app-proxy-screenshot.png)

data/docs/shopify_app/generators.md

@@ -0,0 +1,127 @@
+# Generators
+
+> Listed below are the generators currently offered by the Shopify App gem. To learn more about how this gem creates an embedded app, start with the [default Shopify App generator](#-environment-rails-generate-shopify_app).
+
+---
+
+#### `$ [environment] rails generate shopify_app`
+
+The default generator will run the [`install`](#-rails-generate-shopify_appinstall-flags), [`shop_model`](#-rails-generate-shopify_appshop_model), [`authenticated_controller`](#-rails-generate-shopify_appauthenticated_controller), and [`home_controller`](#-rails-generate-shopify_apphome_controller-flags) generators. This is the recommended way to start a new app from scratch.
+
+##### Environment
+
+###### `SHOPIFY_APP_DISABLE_WEBPACKER`
+
+**[Optional]** Specify this environment variable if your app uses sprockets with Rails 6 or to generate a Shopify App without webpacker.
+
+*Example:*
+
+Run:
+
+```terminal
+$ SHOPIFY_APP_DISABLE_WEBPACKER=1 rails generate shopify_app
+```
+
+Add the following code to your ShopifyApp configuration block:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.disable_webpacker = true
+end
+```
+
+---
+
+#### `$ rails generate shopify_app:install [flags]`
+
+This generator adds ShopifyApp and the required initializers to the host Rails application. You can update any of these settings later.
+
+##### Flags
+
+###### `--application_name`
+
+The name of your app. The flag can be supplied with or without double-quotes.
+
+*Example:* `--application_name "My Shopify App"`
+
+###### `--scope`
+
+The [OAuth access scope(s)](https://shopify.dev/docs/admin-api/access-scopes) required by your app. Delimit multiple access scopes using a comma-space. The flag can be supplied with or without double-quotes.
+
+*Example:* `--scope read_products, write_orders`
+
+*Example:* `--scope "read_products, write_orders"`
+
+###### `--embedded`
+
+Specify whether the app is an embedded app. Apps are embedded by default.
+
+*Example:* `--embedded false`
+
+###### `--with-cookie-authentication`
+
+**[Not recommended]** Specify whether the app uses cookies to authenticate. By default, the app is configured to use [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens).
+
+*Example:* `--with-cookie-authentication true`
+
+---
+
+#### `$ rails generate shopify_app:shop_model`
+
+This generator creates a `Shop` model and a migration to store shop installation records. See [*Shop-based token strategy*](/docs/shopify_app/session-repository.md#shop-based-token-storage) to learn more.
+
+---
+
+#### `$ rails generate shopify_app:user_model`
+
+This generator creates a `User` model and a migration to store user records. See [*User-based token strategy*](/docs/shopify_app/session-repository.md#user-based-token-storage) to learn more.
+
+---
+
+#### `$ rails generate shopify_app:authenticated_controller`
+
+This generator creates a sample authenticated controller. By default, inheriting from this controller protects your app controllers using session tokens. See [*Authentication*](/docs/shopify_app/authentication.md) to learn more.
+
+---
+
+#### `$ rails generate shopify_app:home_controller [flags]`
+
+This generator creates a sample home controller with a view that displays a shop's products. This generator also runs the [`products_controller`](#-rails-generate-shopify_appproducts_controller) generator.
+
+##### Flags
+
+###### `--with-cookie-authentication`
+
+**[Not recommended]**  This flag generates an authenticated home controller. Use this flag only if your app uses cookies to authenticate. By default, the home controller is unauthenticated.
+
+---
+
+#### `$ rails generate shopify_app:products_controller`
+
+This generator creates a sample products API controller to fetch products using the Shopify REST API.
+
+---
+
+#### `$ rails generate shopify_app:add_after_authenticate_job`
+
+**[Optional]** This generator creates a skeleton job that runs after the OAuth authorization flow. See [*Run jobs after the OAuth flow*](/docs/shopify_app/authentication.md#run-jobs-after-the-oauth-flow) for more information.
+
+---
+
+#### `$ rails generate shopify_app:app_proxy_controller`
+
+**[Optional]** This generator creates the app proxy controller to handle proxy requests to the app from your shop storefront. It also modifies 'config/routes.rb' with a namespace route and creates a sample view that displays current shop information using the LiquidAPI. See [*Verify HTTP requests sent via an app proxy*](/docs/shopify_app/engine.md#verify-http-requests-sent-via-an-app-proxy) for more information.
+
+---
+
+#### `$ rails generate shopify_app:marketing_activity_extension`
+
+**[Optional]** This generator creates a controller with the endpoints required to build a [marketing activities extension](https://shopify.dev/docs/marketing-activities). The extension is generated with the base URL `/marketing_activities`. This URL would need to be configured in the Shopify Partners dashboard.
+
+---
+
+#### `$ rails generate shopify_app:controllers`
+
+**[Optional]** This generator is for your convenience. Run this generator if you would like to override code that is part of the Shopify App Rails engine.
+
+*Example:* The Shopify App Rails engine provides a sample [`SessionsController`](/app/controllers/shopify_app/sessions_controller.rb). Running this generator copies this controller to your app so you can begin extending it. Routes and views follow the same pattern.

data/docs/shopify_app/handling-access-scopes-changes.md

@@ -0,0 +1,24 @@
+# Handling changes in access scopes
+## Updating the list of scopes the app requests
+
+Your app specifies the [access scopes](https://shopify.dev/api/usage/access-scopes) it requires in the Shopify App initializer, located at`config/initializers/shopify_app.rb`. To modify this list, update the comma-delimited configuration option:
+
+```ruby
+config.scope = "read_products,write_discounts"
+```
+
+## Requesting new scopes from merchants
+
+The Shopify App gem will automatically request new scopes from merchants for both shop/offline and user/online tokens. To enable your app to reauth via OAuth on scope changes, you can set the following configuration flag in your `config/initializers/shopify_app.rb`:
+```ruby
+config.reauth_on_access_scope_changes = true
+```
+
+## ShopAccessScopesVerification
+The `ShopifyApp::ShopAccessScopesVerification` concern helps merchants grant new access scopes requested by the app. The concern compares the current access scopes granted by the shop and compares them with the scopes requested by the app. If there is a mismatch in configuration, the merchant is redirected to login via OAuth and grant the net new scopes.
+
+To activate the `ShopAccessScopesVerification` for a controller add `include ShopifyApp::ShopAccessScopesVerification`:
+```ruby
+class HomeController < AuthenticatedController
+  include ShopifyApp::ShopAccessScopesVerification
+```

data/docs/shopify_app/script-tags.md

@@ -0,0 +1,28 @@
+# ScriptTags
+
+#### Table of contents
+
+[Manage ScriptTags using the Shopify App initializer](#manage-scripttags-using-the-shopify-app-initializer)
+
+## Manage ScriptTags using the Shopify App initializer
+
+As with webhooks, ShopifyApp can manage your app's [ScriptTags](https://shopify-dev-staging.shopifycloud.com/docs/admin-api/graphql/reference/online-store/scripttag) for you by setting which scripttags you require in the initializer:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.scripttags = [
+    {event:'onload', src: 'https://example.com/fancy.js'},
+    {event:'onload', src: ->(domain) { dynamic_tag_url(domain) } }
+  ]
+end
+```
+
+You also need to have write_script_tags permission in the config scope in order to add script tags automatically:
+
+```ruby
+ config.scope = '... , write_script_tags'
+```
+
+Scripttags are created in the same way as the [Webhooks](/docs/shopify_app/webhooks.md), with a background job which will create the required scripttags.
+
+If `src` responds to `call` its return value will be used as the scripttag's source. It will be called on scripttag creation and deletion.