shopify_app 22.5.2 → 23.0.0

data/README.md

@@ -31,6 +31,12 @@ This gem requires that you have the following credentials:
 
 ## Usage
 
+> [!NOTE]
+> This package works best with the Shopify CLI. Learn more at https://shopify.dev/docs/apps/build/cli-for-apps
+> 
+> To get started with a Rails app already connected to the Shopify CLI, run `shopify app init --template=ruby` for a complete setup app. (Recommended)
+> Follow the instructions below to use this gem with a new or existing Rails app.
+
 1. To get started, create a new Rails app:
 
 ``` sh
@@ -43,44 +49,120 @@ rails new my_shopify_app
 bundle add shopify_app
 ```
 
-3. You will need to provide several environment variables to the app.
-There are a variety of way of doing this, but for a development environment we recommended the [`dotenv-rails`](https://github.com/bkeepers/dotenv) gem.
-Create a `.env` file in the root of your Rails app to specify the full host and Shopify API credentials:
+3. Connect the Shopify CLI to your app:
 
-```sh
-HOST=http://localhost:3000
-SHOPIFY_API_KEY=<Your Shopify API key>
-SHOPIFY_API_SECRET=<Your Shopify API secret>
+### Setting up Shopify CLI
+
+For a more detailed guide on how to set up Shopify CLI, see the [Shopify CLI documentation](https://shopify.dev/docs/apps/build/cli-for-apps/app-structure).
+
+To use your Rails app with Shopify CLI, you'll need to create the required configuration files and set up your project structure:
+
+1. Create a `package.json` file in your app's root directory:
+
+```json
+{
+  "name": "my-shopify-app",
+  "version": "1.0.0",
+  "description": "Shopify app built with Rails",
+  "scripts": {},
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
 ```
+This is required for the Shopify CLI to work. It will be used if you add extension like Checkout UI [extensions](https://shopify.dev/docs/api/checkout-extensions) to your app.
 
-4. Run the default Shopify App generator to create an app that can be embedded in the Shopify Admin:
+2. Create a `shopify.app.toml` configuration file in your app's root:
 
-```sh
-rails generate shopify_app
+```toml
+# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration
+
+client_id = ""
+name = "My Shopify App"
+handle = "my-shopify-app"
+application_url = "https://localhost:3000"
+embedded = true
+
+[access_scopes]
+# Learn more at https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes
+scopes = "write_products"
+
+[auth]
+redirect_urls = [
+  "https://localhost:3000/api/auth",
+  "https://localhost:3000/api/auth/callback",
+  "https://localhost:3000/auth/callback",
+  "https://localhost:3000/auth/shopify/callback"
+]
+
+[webhooks]
+api_version = "2024-10"
+
+[[webhooks.subscriptions]]
+topics = ["app/uninstalled"]
+uri = "/api/webhooks"
+
+[pos]
+embedded = false
+
+[build]
+automatically_update_urls_on_dev = true
+dev_store_url = "YOUR-DEV-STORE.myshopify.com"
 ```
 
-5. Run a migration to create the necessary tables in your database:
+3. Create a `shopify.web.toml` file to configure how Shopify CLI runs your Rails app:
 
-```sh
-rails db:migrate
+```toml
+# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration
+
+[commands]
+dev = "bin/rails server -b 0.0.0.0 -e development"
+build = "RAILS_ENV=production bin/rails assets:precompile"
 ```
 
-6. Run the app:
+4. (Optional) Update your Rails development configuration to allow Shopify's tunnel hosts. In `config/environments/development.rb`, add:
 
-```sh
-rails server
+```ruby
+Rails.application.configure do
+  # Allow ngrok tunnels for secure Shopify OAuth redirects
+  config.hosts = (config.hosts rescue []) << /[-\w]+\.ngrok\.io/
+  # Allow Cloudflare tunnels for secure Shopify OAuth redirects
+  config.hosts = (config.hosts rescue []) << /[-\w]+\.trycloudflare\.com/
+  
+  # Or to allow all hosts in development (less secure):
+  # config.hosts.clear
+  
+  # ... rest of your configuration
+end
 ```
+With the Shopify CLI you can use [localhost development](https://shopify.dev/docs/apps/build/cli-for-apps/development) to run your app.
 
-7. Within [Shopify Partners](https://www.shopify.com/partners), navigate to your App, then App Setup, and configure the URLs, e.g.:
+5. Generate your API credentials
+```
+shopify app config link
+> create a new app
+```
 
-  * App URL: http://localhost:3000/
-  * Allowed redirection URL(s): http://localhost:3000/auth/shopify/callback
+6. Run the default Shopify App generator to create an app that can be embedded in the Shopify Admin:
 
-8. Install the app by visiting the server's URL (e.g. http://localhost:3000) and specifying the subdomain of the shop where you want it to be installed to.
+```sh
+rails generate shopify_app
+```
+
+7. Run a migration to create the necessary tables in your database:
+
+```sh
+rails db:migrate
+```
 
-9. After the app is installed, you're redirected to the embedded app.
+8. Start the dev server and install the app
+```
+shopify app dev
+```
+Clink on the Preview URL to install the app and view it in the Shopify Admin
 
-This app implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) with Shopify to authenticate requests made to Shopify APIs. By default, this app is configured to use [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens) to authenticate merchants when embedded in the Shopify Admin.
+This app implements [OAuth 2.0 Token Exchange](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/token-exchange) with Shopify to authenticate requests made to Shopify APIs. By default, this app is configured to use [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens) to authenticate merchants when embedded in the Shopify Admin.
 
 See [*Generators*](/docs/shopify_app/generators.md) for a complete list of generators available to Shopify App.
 
@@ -107,7 +189,6 @@ You can find documentation on gem usage, concepts, mixins, installation, and mor
   * [Controller Concerns](/docs/shopify_app/controller-concerns.md)
   * [Generators](/docs/shopify_app/generators.md)
   * [Sessions](/docs/shopify_app/sessions.md)
-  * [Handling changes in access scopes](/docs/shopify_app/handling-access-scopes-changes.md)
   * [Testing](/docs/shopify_app/testing.md)
   * [Webhooks](/docs/shopify_app/webhooks.md)
   * [Content Security Policy](/docs/shopify_app/content-security-policy.md)
@@ -161,8 +242,7 @@ ShopifyApp.configure do |config|
   config.embedded_app = true
   config.new_embedded_auth_strategy = true
 
-  # If your app is configured to use online sessions, you can enable session expiry date check so a new access token
-  # is fetched automatically when the session expires.
+  # You can enable session expiry date check so a new access token is fetched automatically when the session expires.
   # See expiry date check docs: https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md#expiry-date
   config.check_session_expiry_date = true
   ...

data/Rakefile

@@ -6,3 +6,16 @@ require "rake/testtask"
 require File.expand_path("../test/dummy/config/application", __FILE__)
 
 Rails.application.load_tasks
+
+# Clear Rails' test task which expects bin/rails to exist.
+# This gem uses a dummy Rails app for testing but doesn't have bin/rails
+# since it's a gem, not a standalone Rails application.
+Rake::Task["test"].clear if Rake::Task.task_defined?("test")
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end
+
+task default: :test

data/app/controllers/shopify_app/callback_controller.rb

@@ -23,16 +23,8 @@ module ShopifyApp
 
       return respond_with_user_token_flow if start_user_token_flow?(api_session)
 
-      if ShopifyApp::VERSION < "23.0"
-        # deprecated in 23.0
-        if ShopifyApp.configuration.custom_post_authenticate_tasks.present?
-          ShopifyApp.configuration.post_authenticate_tasks.perform(api_session)
-        else
-          perform_post_authenticate_jobs(api_session)
-        end
-      else
-        ShopifyApp.configuration.post_authenticate_tasks.perform(api_session)
-      end
+      ShopifyApp.configuration.post_authenticate_tasks.perform(api_session)
+
       redirect_to_app if check_billing(api_session)
     end
 
@@ -145,35 +137,5 @@ module ShopifyApp
     def user_access_scopes_strategy
       ShopifyApp.configuration.user_access_scopes_strategy
     end
-
-    def perform_post_authenticate_jobs(session)
-      # Ensure we use the shop session to install webhooks
-      session_for_shop = session.online? ? shop_session : session
-
-      install_webhooks(session_for_shop)
-
-      perform_after_authenticate_job(session)
-    end
-
-    def install_webhooks(session)
-      return unless ShopifyApp.configuration.has_webhooks?
-
-      WebhooksManager.queue(session.shop, session.access_token)
-    end
-
-    def perform_after_authenticate_job(session)
-      config = ShopifyApp.configuration.after_authenticate_job
-
-      return unless config && config[:job].present?
-
-      job = config[:job]
-      job = job.constantize if job.is_a?(String)
-
-      if config[:inline] == true
-        job.perform_now(shop_domain: session.shop)
-      else
-        job.perform_later(shop_domain: session.shop)
-      end
-    end
   end
 end

data/app/controllers/shopify_app/extension_verification_controller.rb

@@ -9,7 +9,7 @@ module ShopifyApp
     private
 
     def verify_request
-      unless hmac_valid?(request.body.read)
+      unless hmac_valid?(request.raw_post)
         head(:unauthorized)
         ShopifyApp::Logger.debug("Extension verification failed due to invalid HMAC")
       end

data/app/jobs/shopify_app/script_tags_manager_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ShopifyApp
+  class ScriptTagsManagerJob < ActiveJob::Base
+    queue_as do
+      ShopifyApp.configuration.script_tags_manager_queue_name
+    end
+
+    def perform(shop_domain:, shop_token:, script_tags:)
+      ShopifyAPI::Auth::Session.temp(shop: shop_domain, access_token: shop_token) do |session|
+        manager = ScriptTagsManager.new(script_tags, shop_domain)
+        manager.create_script_tags(session: session)
+      end
+    end
+  end
+end

data/docs/Releasing.md

@@ -1,21 +1,115 @@
 # Releasing ShopifyApp
 
-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 origin vX.Y.Z
-    ```
-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
-cache in Shipit settings
+## Prerequisites
+
+Before starting a release, ensure you have:
+
+- Merged all code change PRs into main/master
+- Access to publish the gem via Shipit
+
+## Release Process
+
+### Step 1: Prepare the Release Branch
+
+1. **Ensure all feature changes are merged**
+
+   ```bash
+   git checkout main
+   git pull origin main
+   ```
+
+   Verify: Latest commits should match GitHub's main branch.
+
+2. **Review changes to determine version bump**
+   - Apply [semantic versioning](https://semver.org/):
+     - PATCH (X.Y.Z+1): Bug fixes only
+     - MINOR (X.Y+1.0): New features, backward compatible
+     - MAJOR (X+1.0.0): Breaking changes
+
+### Step 2: Create Release Pull Request
+
+1. **Create a new branch**
+
+   ```bash
+   git checkout -b vX.Y.Z
+   ```
+
+2. **Update version numbers**
+   
+   Edit `lib/shopify_app/version.rb`:
+   ```ruby
+   module ShopifyApp
+     VERSION = "X.Y.Z"  # Replace with your version
+   end
+   ```
+   
+   Edit `package.json`:
+   ```json
+   {
+     "version": "X.Y.Z"  // Replace with your version
+   }
+   ```
+
+3. **Update dependencies**
+
+   ```bash
+   bundle install
+   ```
+
+   Expected: Gemfile.lock updates with new version.
+
+4. **Update CHANGELOG**
+   - Add entry with the new version and date:
+
+     ```markdown
+     ## X.Y.Z (YYYY-MM-DD)
+     
+     - [#PR_NUMBER](https://github.com/Shopify/shopify_app/pull/PR_NUMBER) Description of change
+     - List all changes since last release
+     ```
+
+5. **Create and push PR**
+
+   ```bash
+   git add -A
+   git commit -m "Packaging for release vX.Y.Z"
+   git push origin release-vX.Y.Z
+   ```
+
+   - Title PR: "Packaging for release X.Y.Z"
+   - Add release notes to PR description
+
+### Step 3: Tag and Publish
+
+1. **After PR is merged, update local main**
+
+   ```bash
+   git checkout main
+   git pull origin main
+   ```
+
+   Verify: `git log -1` shows your merge commit.
+
+2. **Create and push tag**
+
+   ```bash
+   git tag -f vX.Y.Z && git push origin vX.Y.Z
+   ```
+
+   Verify: Tag appears at https://github.com/Shopify/shopify_app/tags
+
+3. **Check Create Release workflow**
+
+   Monitor the GitHub Actions workflow to ensure it completes successfully.
+
+4. **Publish via Shipit**
+
+   Use Shipit to build and push the gem to RubyGems.
+   
+   Note: If you see an error like 'You need to create the vX.Y.X tag first', clear git cache in Shipit settings.
+
+5. **Verify gem publication**
+
+   Check the gem on https://rubygems.org/gems/shopify_app
+   
+   Expected: Shows your new version (may take 5-10 minutes).

data/docs/Upgrading.md

@@ -8,6 +8,8 @@ This file documents important changes needed to upgrade your app's Shopify App v
 
 [Unreleased](#unreleased)
 
+[Upgrading to `v23.0.0`](#upgrading-to-v2300)
+
 [Upgrading to `v22.2.0`](#upgrading-to-v2220)
 
 [Upgrading to `v22.0.0`](#upgrading-to-v2200)
@@ -44,6 +46,76 @@ If you do run into issues, we recommend looking at our [debugging tips.](https:/
 
 ## Unreleased
 
+#### (v23.0.0) Minimum Ruby 3.2 and Rails 7.1 required, Jobs moved to app/jobs/
+
+The minimum supported versions have been updated:
+- **Ruby**: 3.1 → 3.2
+- **Rails**: 5.2.1 → 7.1
+
+Additionally, ActiveJob classes have been moved from `lib/shopify_app/jobs/` to `app/jobs/shopify_app/` to fix loading issues with modern Rails versions and follow Rails conventions.
+
+##### Why this change was made
+
+Rails 7.1+'s improved autoloading behavior (via Zeitwerk) properly handles jobs in the `app/jobs/` directory, loading them lazily when needed rather than eagerly during initialization.
+
+##### Migration steps
+
+**For most apps**: No changes needed. The jobs are internal to the gem and will be autoloaded correctly by Rails.
+
+**If your app has custom ActiveJob serializers that reference these jobs**:
+1. Ensure you're on Rails 7.1+ before upgrading. [Rails 7.1 Upgrade Guide](https://guides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-7-0-to-rails-7-1)
+2. Coordinate deployment timing with apps that have custom serializers
+3. Custom serializers will now register before jobs are loaded (correct timing)
+
+**If your app directly requires or references job file paths** (rare):
+```ruby
+# ❌ Old path (will break)
+require 'shopify_app/jobs/webhooks_manager_job'
+
+# ✅ No require needed - Rails autoloads from app/jobs/
+# Jobs are available as ShopifyApp::WebhooksManagerJob
+```
+
+##### Additional dependency changes
+
+- **sprockets-rails**: Now a required runtime dependency. Most Rails apps already include this, but if your app uses an alternative asset pipeline (e.g., Propshaft), you may need to add `sprockets-rails` to your Gemfile.
+
+#### (v23.0.0) - ShopSessionStorageWithScopes and UserSessionStorageWithScopes are deprecated
+
+`ShopSessionStorageWithScopes` and `UserSessionStorageWithScopes` are now marked as deprecated and will be removed in v24.0.0 in favor of `ShopSessionStorage` and `UserSessionStorage`, which handle all session attributes automatically (including `access_scopes`, `expires_at`, `refresh_token`, and `refresh_token_expires_at` for shops).
+
+**Migration:**
+
+1. Update your Shop model to use `ShopSessionStorage`:
+```ruby
+# Before
+class Shop < ActiveRecord::Base
+  include ShopifyApp::ShopSessionStorageWithScopes
+end
+
+# After
+class Shop < ActiveRecord::Base
+  include ShopifyApp::ShopSessionStorage
+end
+```
+
+2. Update your User model to use `UserSessionStorage`:
+```ruby
+# Before
+class User < ActiveRecord::Base
+  include ShopifyApp::UserSessionStorageWithScopes
+end
+
+# After
+class User < ActiveRecord::Base
+  include ShopifyApp::UserSessionStorage
+end
+```
+
+3. **Optional:** You can now opt-in to using expiring offline access tokens with automatic refresh. See the [Sessions documentation](/docs/shopify_app/sessions.md#offline-access-tokens) for setup instructions.
+
+**Note:** If you had custom `access_scopes=` or `access_scopes` methods in your models, these are no longer needed. The base concerns now handle these attributes automatically.
+
 #### (v23.0.0) - Deprecated methods in CallbackController
 The following methods from `ShopifyApp::CallbackController` have been deprecated in `v23.0.0`
 - `perform_after_authenticate_job`

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

@@ -1,10 +1,57 @@
 # 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.
+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 typically done by including the [`ShopifyApp::Authenticated`](https://github.com/Shopify/shopify_app/blob/ed41165ca9598d2c9d514487365192f22b5eb096/app/controllers/concerns/shopify_app/authenticated.rb) controller concern rather than directly including it.
 
-## Included Domains
+## Frame Ancestors
 
-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):
+For actions that include the `ShopifyApp::FrameAncestors` controller concern, the following hosts are added to the `frame-ancestors` directive 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"
+
+## Strict Content Security Policy
+
+If you enable a strict Content Security Policy in your application, you'll need to explicitly allow Shopify's App Bridge script. The gem provides a helper method to make this easy.
+
+### Without Strict CSP (Default)
+
+By default, Shopify app templates have CSP **disabled** (commented out in `config/initializers/content_security_policy.rb`). In this configuration:
+- Inline scripts work (including Vite HMR for development)
+- App Bridge loads without any configuration
+- No `script-src` directive is set
+
+### With Strict CSP
+
+If you enable a strict CSP by uncommenting and configuring `content_security_policy.rb`, you must:
+
+1. **Handle inline scripts** - Strict CSP blocks inline scripts. You can:
+   - Use `unsafe-inline` in development (for Vite HMR)
+   - Use nonces or hashes in production
+   - Move inline scripts to external files
+
+2. **Allow App Bridge script** - Add the App Bridge script source using the provided helper:
+
+```ruby
+# config/initializers/content_security_policy.rb
+Rails.application.configure do
+  config.content_security_policy do |policy|
+    policy.default_src :self, :https
+
+    # For development: allow inline scripts for Vite HMR
+    if Rails.env.development?
+      policy.script_src :self, :unsafe_inline
+    else
+      policy.script_src :self
+    end
+
+    # Add Shopify App Bridge script source
+    ShopifyApp.add_csp_directives(policy)
+  end
+end
+```
+
+The `ShopifyApp.add_csp_directives(policy)` helper method:
+- Adds `https://cdn.shopify.com/shopifycloud/app-bridge.js` to your `script-src` directive
+- Preserves your existing `script-src` configuration
+- Prevents duplicate URLs if called multiple times
+- Is a no-op if you don't configure CSP

data/docs/shopify_app/controller-concerns.md

@@ -64,6 +64,26 @@ Implements Rails' [protect_from_forgery](https://api.rubyonrails.org/classes/Act
 #### EmbeddedApp
 If your ShopifyApp configuration has the `embedded_app` config set to true, [P3P header](https://www.w3.org/P3P/) and [content security policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) are handled for you.
 
+##### Content Security Policy (CSP) Directives:
+
+The EmbeddedApp concern automatically configures the following CSP directives to ensure your embedded app works correctly within Shopify Admin:
+
+1. **frame-ancestors**: Allows the app to be embedded in iframes from:
+   - The current shop domain (e.g., `https://example.myshopify.com`)
+   - Shopify's unified admin domain (e.g., `https://admin.shopify.com`)
+
+2. **script-src**: Allows JavaScript execution from:
+   - `'self'` - Scripts from your app's own domain
+   - `https://cdn.shopify.com/shopifycloud/app-bridge.js` - Required for App Bridge functionality
+   - Any other script sources you explicitly add in your controller
+
+These CSP settings ensure that:
+- Your app can be properly embedded within Shopify Admin
+- App Bridge can load and function correctly
+- Your app maintains security while allowing necessary Shopify integrations
+
+##### Layout
+
 By default, the `EmbeddedApp` concern also sets the layout file to be `app/views/layouts/embedded_app.html.erb`.
 
 Sometimes one wants to run an embedded app in non-embedded mode. For example:

data/docs/shopify_app/script-tags.md

@@ -0,0 +1,52 @@
+# Script Tags
+
+ShopifyApp can manage your app's [Script Tags](https://shopify.dev/docs/admin-api/graphql/reference/online-store/scripttag) for you by setting which script tags you require in the initializer.
+> [!NOTE]
+> Script tags should only be used for vintage themes that do not support app blocks.
+
+## Configuration
+
+```ruby
+ShopifyApp.configure do |config|
+  config.script_tags = [
+    # Basic script tag
+    {cache: true, src: 'https://example.com/fancy.js'},
+    
+    # Script tag with template_types for app block detection
+    {
+      cache: true, 
+      src: 'https://example.com/product-script.js',
+      template_types: ['product', 'collection']
+    }
+  ]
+end
+```
+
+## Required Scopes
+Both the `write_script_tags` and `read_themes` scopes are required.
+
+For apps created with the Shopify CLI, set these scopes in your `shopify.app.toml` file:
+
+```toml
+[access_scopes]
+# Learn more at https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes
+scopes = "write_products,write_script_tags,read_themes"
+```
+
+For older apps, you can set the scopes in the initializer:
+
+```ruby
+config.scope = 'write_products,write_script_tags,read_themes'
+```
+
+## How It Works
+
+### Script Tag Creation
+
+Script tags are created in the same way as [Webhooks](/docs/shopify_app/webhooks.md), with a background job which will create the required scripttags.
+
+### App Block Detection
+
+When you specify `template_types` for a script tag, ShopifyApp will check if the store's active theme supports app blocks for those template types. If any template type doesn't support app blocks, the script tags will be created as a fallback
+
+This allows your app to automatically adapt to the store's theme capabilities, using app blocks when available and falling back to script tags when necessary.