austra / shopify_app_gem

A Rails Engine for building Shopify Apps

Shopify App

This gem builds Rails applications that can be embedded in the Shopify Admin.

Introduction | Requirements | Usage | Documentation | Contributing | License

Introduction

This gem includes a Rails engine, generators, modules, and mixins that help create Rails applications that work with Shopify APIs. The Shopify App Rails engine provides all the code required to implement OAuth with Shopify. The default Shopify App generator builds an app that can be embedded in the Shopify Admin and secures it with session tokens.

Requirements

To become a Shopify app developer, you will need a Shopify Partners account. Explore the Shopify dev docs to learn more about building Shopify apps.

This gem requires that you have the following credentials:

• Shopify API key: The API key app credential specified in your Shopify Partners dashboard.
• Shopify API secret: The API secret key app credential specified in your Shopify Partners dashboard.

Usage

1. To get started, create a new Rails app:

rails new my_shopify_app

2. Add the Shopify App gem to the app's Gemfile:

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 gem. Create a .env file in the root of your Rails app to specify the full host and Shopify API credentials:

HOST=http://localhost:3000
SHOPIFY_API_KEY=<Your Shopify API key>
SHOPIFY_API_SECRET=<Your Shopify API secret>

Optionally, use built-in Rails secret store:

Open the secret store by running:

EDITOR="vi" rails credentials:edit --environment=development

Add the following to the file:

shopify:
  host: http://localhost:3000
  api_key: <Your Shopify API key>
  api_secret: <Your Shopify API secret>

4. Run the default Shopify App generator to create an app that can be embedded in the Shopify Admin:

rails generate shopify_app

5. Run a migration to create the necessary tables in your database:

rails db:migrate

6. Run the app:

rails server

7. Within Shopify Partners, navigate to your App, then App Setup, and configure the URLs, e.g.:

• App URL: http://locahost:3000/
• Allowed redirection URL(s): http://localhost:3000/auth/shopify/callback

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.

9. After the app is installed, you're redirected to the embedded app.

This app implements OAuth 2.0 with Shopify to authenticate requests made to Shopify APIs. By default, this app is configured to use session tokens to authenticate merchants when embedded in the Shopify Admin.

See Generators for a complete list of generators available to Shopify App.

Documentation

You can find documentation on gem usage, concepts, mixins, installation, and more in /docs.

• Start with the Generators document to learn more about the generators this gem offers.
• Check out the Changelog for notes on the latest gem releases.
• See Troubleshooting for tips on common issues.
• If you are looking to upgrade your Shopify App version to a new major release, see Upgrading for important notes on breaking changes.

Overview

Quickstart

Troubleshooting

Upgrading

Shopify App

• Authentication
• Engine
• Controller Concerns
• Generators
• ScriptTags
• Session repository
• Handling changes in access scopes
• Testing
• Webhooks
• Content Security Policy
• Logging

Engine

Mounting the Shopify App Rails Engine provides the following routes. These routes are configured to help install your application on shops and implement OAuth.

Verb	Route	Action
GET	/login	Login
POST	/login	Login
GET	/auth/shopify/callback	OAuth redirect URI
GET	/logout	Logout
POST	/webhooks/:type	Webhook callback

These routes are configurable. See the more detailed Engine documentation to learn how you can customize the login URL or mount the Shopify App Rails engine at nested routes.

To learn more about how this gem authenticates with Shopify, see Authentication.

API Versioning

Shopify's API is versioned. With Shopify App v1.11.0, the included Shopify API gem allows developers to specify and update the Shopify API version they want their app or service to use. The Shopify API gem also surfaces warnings to Rails apps about deprecated endpoints, GraphQL fields and more.

See the Shopify API gem README for more information.