Ruby on Rails Integration

This guide covers how to install Userplane in a Ruby on Rails application.

Adding the script

Add these two tags to the <head> of your application layout:

<!-- app/views/layouts/application.html.erb -->
<!DOCTYPE html>
<html>
<head>
  <!-- Sets workspace ID for screen recording -->
  <meta name="userplane:workspace" content="YOUR_WORKSPACE_ID" />

  <!-- Loads Userplane screen recording script -->
  <script type="module" src="https://cdn.userplane.io/embed/script.js"></script>

  <%= csrf_meta_tags %>
  <%= csp_meta_tag %>
  <%= stylesheet_link_tag "application" %>
  <%= yield(:head) %>
</head>
<body>
  <%= yield %>
</body>
</html>

Replace YOUR_WORKSPACE_ID with your workspace ID. You can copy the exact snippet with your ID pre-filled from Workspace Settings > Domains in the Userplane dashboard. Place the tags as early as possible in <head>. The Userplane script can only capture console logs and network requests that occur after it initializes — placing it early gives you the most complete recording context.

Rails’ javascript_include_tag helper accepts full URLs (<%= javascript_include_tag "https://cdn.userplane.io/embed/script.js" %>), but a plain <script> tag is clearer for external CDN resources and avoids the asset pipeline.

Page-specific loading

To load Userplane only on certain pages, use the content_for / yield pattern:

<!-- app/views/layouts/application.html.erb -->
<head>
  <%= yield(:userplane) %>
</head>

<!-- app/views/dashboard/index.html.erb -->
<% content_for :userplane do %>
  <meta name="userplane:workspace" content="YOUR_WORKSPACE_ID" />
  <script type="module" src="https://cdn.userplane.io/embed/script.js"></script>
<% end %>

Turbo compatibility

Rails 7+ includes Turbo by default, which performs partial page replacements instead of full reloads. The Userplane CDN script placed in <head> loads on the initial page visit and persists across Turbo navigations — no special configuration is needed. If you initialize custom JavaScript alongside Userplane, listen for turbo:load rather than DOMContentLoaded:

document.addEventListener('turbo:load', () => {
  // Code that should run on every page navigation
});

URL parameters

When a customer opens a recording link, Userplane appends userplane-token and userplane-action to the URL. If your Rails app redirects unauthenticated users (e.g. via Devise), carry the userplane- prefixed parameters through the redirect:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :authenticate_user!

  private

  def after_sign_in_path_for(resource)
    stored_location = stored_location_for(resource) || root_path
    userplane_params = request.query_parameters.select { |k, _| k.start_with?("userplane-") }

    if userplane_params.any?
      uri = URI.parse(stored_location)
      existing = URI.decode_www_form(uri.query || "")
      uri.query = URI.encode_www_form(existing + userplane_params.to_a)
      uri.to_s
    else
      stored_location
    end
  end
end

See Installation for the full list of parameters.

Sensitive data

Add data-userplane-blur to any element you want blurred in recordings. See Sensitive Data Redaction for the full reference.

Content Security Policy

If your Rails app uses the built-in CSP DSL, add the Userplane CDN domain:

# config/initializers/content_security_policy.rb
Rails.application.configure do
  config.content_security_policy do |policy|
    policy.script_src :self, "https://cdn.userplane.io"
  end
end

See Installation for additional CSP guidance.

Example app

A complete Ruby on Rails example is available at github.com/userplanehq/userplane-sdk-examples/tree/main/examples/rails.

Variable	Description
`USERPLANE_WORKSPACE_ID`	Your Userplane workspace ID

cd examples/rails && bundle install && bin/rails server

Installation — CDN script placement, CSP, iframes, and browser support.
Domain Verification Guide — verify domain ownership after installing the script.
Sensitive Data Redaction — blur sensitive content in recordings.
Web SDK — programmatic SDK for apps with a build step.

Getting Started

AI Agents

SDK Reference

Framework Guides

Platform Guides

Privacy & Data

Adding the script

Page-specific loading

Turbo compatibility

URL parameters

Sensitive data

Content Security Policy

Example app

​Adding the script

​Page-specific loading

​Turbo compatibility

​URL parameters

​Sensitive data

​Content Security Policy

​Example app

​Related articles

Adding the script

Page-specific loading

Turbo compatibility

URL parameters

Sensitive data

Content Security Policy

Example app

Related articles