shopify_app 13.0.0 → 17.1.0

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/Upgrading.md

@@ -0,0 +1,110 @@
+# 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 `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 `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

data/docs/shopify_app/authentication.md

@@ -0,0 +1,124 @@
+# 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`.
+
+### `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/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://my.domain.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://your_app_website.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.