Record and replay browser sessions in a self-hosted Rails Engine.
Spectator Sport uses the rrweb
library to create recordings of your website's DOM as your users interact with it. These recordings are stored in your database for replay by developers and administrators to analyze user behavior, reproduce bugs, and make building for the web more fun.
🚧 🚧 This gem is very early in its development lifecycle and will undergo significant changes on its journey to v1.0. I would love your feedback and help in co-developing it, just fyi that it's going to be so much better than it is right now.
🚧 🚧 Future Roadmap:
The Spectator Sport gem is conceptually two parts packaged together in this single gem and mounted in your application:
To install Spectator Sport in your Rails application:
spectator_sport
to your application's Gemfile and install the gem:
bundle add spectator_sport
Install Spectator Sport in your application. 🚧 This will change on the path to v1. Explore the /demo
app as live example:
Create database migrations with bin/rails g spectator_sport:install:migrations
. Apply migrations with bin/rails db:prepare
Mount the recorder API in your application's routes with mount SpectatorSport::Engine, at: "/spectator_sport, as: :spectator_sport"
Add the spectator_sport_script_tags
helper to the bottom of the <head>
of layout/application.rb
. Example:
<%# app/views/layouts/application.html.erb %>
<%# ... %>
<%= spectator_sport_script_tags %>
</head>
Add a <script>
tag to public/404.html
, public/422.html
, and public/500/html
error pages. Example:
<!-- public/404.html -->
<!-- ... -->
<script defer src="https://github.com/bensheldon/spectator_sport/raw/main/spectator_sport/events.js"></script>
</head>
You must manually install and set up authorization for the Player Dashboard. You probably shouldn't make it public. If you are using Devise, authorizing admins might look like this:
# config/routes.rb
authenticate :user, ->(user) { user.admin? } do
mount SpectatorSport::Dashboard::Engine, at: 'spectator_sport_dashboard', as: :spectator_sport_dashboard
end
Or set up Basic Auth:
# config/initializers/spectator_sport.rb
SpectatorSport::Dashboard::Engine.middleware.use(Rack::Auth::Basic) do |username, password|
ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.spectator_sport_username, username) &
ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.spectator_sport_password, password)
end
Or extend the SpectatorSport::Dashboard::ApplicationController
with your own authorization logic:
# config/initializers/good_job.rb
ActiveSupport.on_load(:spectator_sport_dashboard_application_controller) do
# context here is SpectatorSport::Dashboard::ApplicationController
before_action do
raise ActionController::RoutingError.new('Not Found') unless current_user&.admin?
end
def current_user
# load current user from session, cookies, etc.
end
end
💖 Please don't be shy about opening an issue or half-baked PR. Your ideas and suggestions are more important to discuss than a polished/complete code change.
This repository is intended to be simple and easy to run locally with a fully-featured demo application for immediately seeing the results of your proposed changes:
# 1. Clone this repository via git
# 2. Set it up locally
bundle install
# 3. Create database
bin/rails db:setup
# 4. Run the demo Rails application:
bin/rails s
# 5. Load the demo application in your browser
open http://localhost:3000
# 6. Make changes, see the result, commit and make a PR!
The gem is available as open source under the terms of the MIT License.