Turbolinks is a JavaScript library that makes your app behave as if it were a single-page app.

If you have a multi-page server-side rendered (SSR) app and you want to use session token-based authentication, then you can still use session tokens by converting your app to use Turbolinks. You can do this even if you're unsure or not yet ready to convert your app to a single-page app.

This guide illustrates how to convert your multi-page SSR app to use session token-based authentication with Turbolinks. The sections below describe a step-by-step implementation of the conversion pattern described in Authenticate your app using session tokens.

Requirements

Your app must meet the following requirements to complete this tutorial:

• Your app has the Shopify App gem installed.
• Your app is enabled to use JSON Web Token (JWT) authentication and session tokens.

You can create a JWT-enabled app using the Shopify App version 14.0.0 gem and running the following generator:

$ rails generate shopify_app --with-session-token

The --with-session-token flag creates an embedded app that is configured to use App Bridge authentication immediately.

Enable Turbolinks on your app

Use the following steps to enable Turbolinks on your app.

Steps

1. Add the turbolinks gem to your Gemfile:

   Copy

   gem 'turbolinks', '~> 5'

2. Run bundle install.

3. Add the turbolinks package to your application.

   Copy

   $ yarn add turbolinks

4. If your app uses webpack to manage its manifest files, then add the following line to app/javascript/packs/application.js:

   Copy

   require("turbolinks").start();

Create a splash page

Your splash page is used to indicate that your app has begun to fetch a session token. When your app has the token, it should navigate the user to the main view. The main view might contain protected or authenticated resources.

Steps

1. Create a SplashPageController along with a default index action and view:

   Copy

   $ rails generate controller splash_page index

2. Make splash_page#index the default root route for your app. Update the following code in your routes.rb file:

   Copy

   Rails.application.routes.draw do
     root to: 'splash_page#index'
     ...
   end

3. Indicate a loading status in your splash page index view. Update app/views/splash_page/index.html.erb to match the following code:

   Copy

   <p>Loading...</p>

4. Make the SplashPageController behave as the default embedded app HomeController by updating app/controllers/splash_page_controller.rb to match the following code:

   Copy

   class SplashPageController < ApplicationController
     include ShopifyApp::EmbeddedApp
     include ShopifyApp::RequireKnownShop
   
     def index
       @shop_origin = current_shopify_domain
     end
   end

5. Protect the default HomeController by inheriting AuthenticatedController. Update home_controller.rb to match the following code:

   Copy

   class HomeController < AuthenticatedController
     def index
     end
   end

Fetch and store session tokens

When users visit the app for the first time, you can use Javascript to complete the following tasks on the splash page:

• Create an App Bridge instance.

• Fetch a session token and cache it.

• Install event listeners on the turbolinks:request-start and turbolinks:render events to add an Authorization request header.

• Install event listeners to add an Authorization request header on the following events:

  • turbolinks:request-start
  • turbolinks:render

• Use Turbolinks to navigate to the HomeController.

Steps

1. Add the following load_path parameter to app/views/layouts/embedded_app.html.erb. This parameter is used by Turbolinks to navigate back to this app to when a session token has been fetched. In this app, you are navigating to home_path by default.

   Copy

   ...
       <%= content_tag(:div, nil, id: 'shopify-app-init', data: {
         api_key: ShopifyApp.configuration.api_key,
         shop_origin: @shop_origin || (@current_shopify_session.domain if @current_shopify_session),
         load_path: params[:return_to] || home_path,
         ...
       } ) %>
   ...

2. Import the library method getSessionToken from app-bridge-utils in app/javascript/shopify_app/shopify_app.js:

   Copy

   import { getSessionToken } from "@shopify/app-bridge-utils";

3. In shopify_app.js, include the following methods that fetch and store a session token every 50 seconds.

   Copy

   async function retrieveToken(app) {
     window.sessionToken = await getSessionToken(app);
   }
   
   function keepRetrievingToken(app) {
     setInterval(() => {
       retrieveToken(app);
     }, 50000);
   }

4. In shopify_app.js, add event listeners to the turbolinks:request-start and turbolinks:render events. Set an "Authorization": "Bearer <session token>" header during these events:

   Copy

   document.addEventListener("turbolinks:request-start", function (event) {
     var xhr = event.data.xhr;
     xhr.setRequestHeader("Authorization", "Bearer " + window.sessionToken);
   });
   
   document.addEventListener("turbolinks:render", function () {
     $("form, a[data-method=delete]").on("ajax:beforeSend", function (event) {
       const xhr = event.detail[0];
       xhr.setRequestHeader("Authorization", "Bearer " + window.sessionToken);
     });
   });

5. In shopify_app.js, edit the DOMContentLoaded event listener to add the following instructions:

   Copy

   document.addEventListener("DOMContentLoaded", async () => {
     var data = document.getElementById("shopify-app-init").dataset;
     var AppBridge = window["app-bridge"];
     var createApp = AppBridge.default;
     window.app = createApp({
       apiKey: data.apiKey,
       shopOrigin: data.shopOrigin,
     });
   
     var actions = AppBridge.actions;
     var TitleBar = actions.TitleBar;
     TitleBar.create(app, {
       title: data.page,
     });
   
     // Wait for a session token before trying to load an authenticated page
     await retrieveToken(app);
   
     // Redirect to the requested page
     Turbolinks.visit(data.loadPath);
   
     // Keep retrieving a session token periodically
     keepRetrievingToken(app);
   });

   After a session token is retrieved, Turbolinks.visit(data.loadPath) visits the load_path param defined in embedded_app.html.erb.

   Your app continues to retrieve session tokens every 50 seconds or so.

Request authenticated resources

When a user visits your app, they should now briefly see a loading screen before they're taken to the Home view of your app. The Home view is authenticated by the HomeController.

For demo purposes, we have created two additional authenticated controllers: ProductsController and WidgetsController. The following steps describe how to create the ProductsController and add a navigation link to the Home view.

Steps

1. Generate a ProductsController using the Rails generator:

   Copy

   $ rails generate controller products index

2. Add authentication to the ProductsController by inheriting AuthenticatedController:

   Copy

   class ProductsController < AuthenticatedController
     def index
       @products = ShopifyAPI::Product.find(:all, params: { limit: 10 })
     end
   end

3. Create a view for the ProductsController. Update app/views/products/index.html.erb to match the following code:

   Copy

   <%= link_to 'Back', home_path %>
   
   <h2>Products</h2>
   
   <ul>
     <% @products.each do |product| %>
       <li><%= link_to product.title, "https://#{@current_shopify_session.domain}/admin/products/#{product.id}", target: "_top" %></li>
     <% end %>
   </ul>

4. Optional. If pages of your app are deep-linked, then add the ShopifyApp::EnsureAuthenticatedLinks concern to AuthenticatedController. The concern is available in Shopify App version 16.1.0:

   Copy

   class AuthenticatedController < ApplicationController
     include ShopifyApp::EnsureAuthenticatedLinks
     include ShopifyApp::Authenticated
   end

5. Optional. To satisfy the ShopifyApp::RequireKnownShop concern, add the following method to the before_action filter in AuthenticatedController:

   Copy

   class AuthenticatedController < ApplicationController
     include ShopifyApp::Authenticated
   
     before_action :shop_origin
   
     def shop_origin
       @shop_origin = current_shopify_domain
     end
   end

6. Update app/views/home/index.html.erb to include a link to the product index view:

   Copy

   <%= link_to 'Products', products_path %>

   Your app can now access the authenticated ProductsController from the HomeController using session tokens.

Resources

Sample server-side rendered Rails app converted using Turbolinks