Motivation
After building several Shopify embedded apps, I've learned valuable lessons about what works (and what definitely doesn't) in the embedded app environment. Today, I'm sharing these insights to help you avoid common pitfalls and build better Shopify apps.
The Challenge
Building embedded apps for Shopify presents unique challenges - particularly around navigation, authentication, and user experience. One of the biggest pitfalls? Trying to use regular URL navigation in an embedded app context.
Project Setup
First, let's look at the proper configuration for a Shopify embedded app:
ShopifyApp.configure do |config|
config.embedded_app = true
config.new_embedded_auth_strategy = false
config.scope = "read_customers,write_customers"
config.api_version = "2024-10"
config.webhooks = [
{ topic: "app/uninstalled", address: "webhooks/app_uninstalled" },
{ topic: "customers/create", address: "webhooks/customers_create" }
]
end
Do's and Don'ts
✅ DO: Use App Bridge for Navigation
var AppBridge = window['app-bridge'];
var createApp = AppBridge.default;
window.app = createApp({
apiKey: data.apiKey,
host: data.host,
});
var actions = AppBridge.actions;
var TitleBar = actions.TitleBar;
TitleBar.create(app, {
title: data.page,
});
❌ DON'T: Use Regular Rails Links
Avoid using regular Rails link_to helpers without proper App Bridge handling:
<%= link_to "Settings", settings_path %>
<%= link_to "Settings", settings_path(request.query_parameters) %>
✅ DO: Handle Authentication Properly
class AuthenticatedController < ApplicationController
include ShopifyApp::EnsureHasSession
before_action :verify_embedded_app_request
private
def verify_embedded_app_request
if ShopifyAPI::Context.embedded? &&
(!params[:embedded].present? || params[:embedded] != "1")
redirect_to(ShopifyAPI::Auth.embedded_app_url(params[:host]).to_s +
request.path,
allow_other_host: true)
end
end
end
✅ DO: Implement Proper Flash Messages
module ApplicationHelper
def flash_class(type)
case type.to_sym
when :success, :notice
"bg-green-50"
when :error, :alert
"bg-red-50"
else
"bg-blue-50"
end
end
end
✅ DO: Use Proper Layout for Embedded Apps
<!DOCTYPE html>
<html lang="en">
<head>
<script src="https://unpkg.com/@shopify/app-bridge@3.7.9"></script>
<%= csrf_meta_tags %>
<%= javascript_importmap_tags %>
</head>
<body>
<div id="app">
<%= render 'shared/navbar' %>
<%= yield %>
</div>
<% if flash[:notice].present? || flash[:error].present? %>
<script>
document.addEventListener('DOMContentLoaded', function() {
var Toast = window['app-bridge'].actions.Toast;
<% if flash[:notice].present? %>
Toast.create(window.app, {
message: "<%= j flash[:notice] %>",
duration: 5000
}).dispatch(Toast.Action.SHOW);
<% end %>
});
</script>
<% end %>
</body>
</html>
❌ DON'T: Forget Query Parameters
When creating links or forms, always include the necessary query parameters:
def maintain_query_parameters
@query_parameters = request.query_parameters
end
✅ DO: Implement Proper Navigation
<nav class="bg-white border-b border-gray-200 fixed w-full z-50">
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
<div class="flex justify-between h-16">
<div class="hidden md:flex md:items-center md:space-x-6">
<%= link_to "Home",
root_path(params.except(:action, :controller).permit!.to_h),
class: "text-gray-600 hover:text-gray-900 px-3 py-2" %>
</div>
</div>
</div>
</nav>
Common Pitfalls to Avoid
- Direct URL Manipulation
```ruby
Wrong
redirect_to settings_path
Right
redirect_to settings_path(request.query_parameters)
2. **Missing CSRF Protection**
```ruby
class ApplicationController < ActionController::Base
protect_from_forgery with: :exception
skip_before_action :verify_authenticity_token, if: :valid_shopify_request?
private
def valid_shopify_request?
return true if request.headers["HTTP_AUTHORIZATION"]&.start_with?("Bearer ")
return true if params[:session].present?
false
end
end
Improper Session Handling
class Shop < ActiveRecord::Base
include ShopifyApp::ShopSessionStorageWithScopes
def api_version
ShopifyApp.configuration.api_version
end
end
Best Practices for Success
- Use App Bridge for All Navigation
- Maintain Query Parameters
- Implement Proper Error Handling
- Use Appropriate Authentication Checks
- Follow Shopify's Design Guidelines
Learning Journey
Building embedded Shopify apps has taught me the importance of proper navigation handling and session management. The biggest lesson? Never assume standard web development practices will work in an embedded context.
Results and Impact
- Smoother user experience
- Fewer authentication issues
- Better app stability
- Reduced support tickets
Next Steps
Enhanced Error Handling
- Implement better error boundaries
- Add detailed logging
Performance Optimization
- Optimize App Bridge usage
- Implement proper caching
User Experience Improvements
- Add loading states
- Enhance feedback mechanisms
Conclusion
Building embedded Shopify apps requires a different mindset from traditional web development. By following these best practices and avoiding common pitfalls, you can create robust, user-friendly applications that integrate seamlessly with the Shopify admin.
Have you encountered other challenges while building Shopify embedded apps? Share your experiences in the comments below!
Happy Coding!
