# Install StepsKit in a Rails app > Add StepsKit to a Rails app from application.html.erb with javascript_include_tag. Covers Turbo Drive navigation, CSP nonces, why importmap is the wrong place, and identifying current_user. *Source: https://stepskit.com/docs/install/rails* For Rails 7 and 8. Rails is a multi-page app, which changes how you identify users — see step 2 — and it ships Turbo, which changes how navigation works. ## Prerequisites - Your project API key, from the **Integrations** page in the [dashboard](/app). - Rails 7 or newer. Older versions work; only the Turbo notes won't apply. ## Which install you need Rails ships two different JavaScript setups, and they take different installs: - **jsbundling-rails** (esbuild, rollup, or webpack — you have a `package.json` and run `yarn build`): install the [npm package](/docs/install.md). - **importmap-rails** (the Rails 7+ default, no bundler): use the layout tag below. ### Not `config/importmap.rb` On importmap-rails the instinct is to pin StepsKit there. Don't: importmaps map **ES module specifiers** to browser-loadable URLs, and the CDN loader is a classic script, not a module. Pinning it does nothing useful. There's also no node_modules for an importmap to resolve `stepskit` out of, so the package isn't an option on this path either — it belongs in the layout. ## 1a. With jsbundling — install the package ```bash npm install stepskit ``` Then call `init()` at the top of `app/javascript/application.js`: ```js import stepskit from "stepskit"; stepskit.init("YOUR_API_KEY"); ``` Skip to [step 2](#2-identify-the-user) — but read the Turbo notes below, they apply either way. ## 1b. With importmap — add the loader to your layout Add this to `app/views/layouts/application.html.erb`, inside ``: ```erb <%= javascript_include_tag "https://cdn.stepskit.com/stepskit.latest.js", async: true, data: { api_key: "YOUR_API_KEY" } %> ``` Rails converts the `data:` hash into dashed attributes, so this renders `data-api-key="YOUR_API_KEY"` — no string-building needed. **`` rather than before ``, and this matters on Rails.** Turbo Drive replaces `` on every visit and re-executes the scripts it finds there, but it *merges* `` and leaves tags that are already present alone. In `` the loader runs once per hard page load; in `` it would re-run on every Turbo navigation and start a fresh SDK instance each time. `async` means it still doesn't block rendering. Put the API key in credentials rather than the template once you're past trying it out: ```erb <%= javascript_include_tag "https://cdn.stepskit.com/stepskit.latest.js", async: true, data: { api_key: Rails.application.credentials.stepskit_api_key } %> ``` Because this form has no inline queue stub, guard any JavaScript calls you write later with `window.stepskit?.`. ## 2. Identify the user **This is half the install, not a nice-to-have.** Without an `id`, show-once capping degrades to a per-tab check and any tour with a "filtered" audience is hidden outright. **In a multi-page app, user attributes do not survive a page load.** Identifying on sign-in alone does nothing for the pages that follow. The simplest correct answer is to render the values as data attributes on the same tag, so they're present on every request: ```erb <%= javascript_include_tag "https://cdn.stepskit.com/stepskit.latest.js", async: true, data: { api_key: Rails.application.credentials.stepskit_api_key, **(current_user ? { user_id: current_user.id, user_email: current_user.email, user_plan: current_user.plan } : {}) } %> ``` That renders `data-user-id`, `data-user-email` and `data-user-plan`, which StepsKit reads on load. ERB escapes attribute values, so this is safe with user-supplied data. **Prefer the data-attribute form above.** StepsKit reads those attributes off the tag during its own startup, so there is no ordering to get wrong. If you'd rather call the API explicitly, `tag.script` with `nonce: true` keeps it CSP-clean — but put it at the end of ``, and note that `window.stepskit` doesn't exist until the async SDK has downloaded, so an early call is silently dropped: ```erb <% if current_user %> <%= tag.script nonce: true do %> window.stepskit?.identify(<%= { id: current_user.id.to_s, email: current_user.email, plan: current_user.plan }.to_json.html_safe %>); <% end %> <% end %> ``` `to_json` on a Hash is the safe way to get a value into a script block — don't interpolate fields individually. Pass whatever your user model already carries; every key becomes targetable and there's no fixed schema to conform to. ## 3. Verify it worked Load any page of your app, then: 1. **Dashboard** — the project's Integrations page flips to **Connected**. 2. **Console, on a signed-in page** — run `window.stepskit.validateEnvironment()`. You want a non-null `visitorId` and a populated `userAttributes`. A null `visitorId` means step 2 never ran. 3. **Network** — `cdn.stepskit.com/stepskit.latest.js` returns `200`. `validateEnvironment()` also returns a `toursFiltered` table that says exactly why any given tour isn't showing. ## Rails notes ### Turbo Drive Rails 7+ ships Turbo Drive, which intercepts link clicks and replaces `` rather than doing a full page load. Two consequences: **Navigation is client-side.** StepsKit handles this already — it patches `history.pushState` and `replaceState` and listens for `popstate`, so it sees Turbo navigation and re-evaluates which tours apply. You don't need to hook `turbo:load` for StepsKit's sake. **Your `` gets replaced.** An element a tour step is anchored to can be swapped out from under an open tour. Anchor steps to elements that persist across the pages a tour spans, or keep each step's target on the page that step belongs to. **Don't move the loader into ``.** Turbo re-executes body scripts on every visit, and each evaluation constructs a fresh SDK instance that replaces the previous one — duplicated listeners and a redundant fetch per navigation. Keep the loader in ``, where Turbo's head merge leaves it alone. Because the SDK survives Turbo navigation, user attributes set once do persist across Turbo visits. They still don't survive a hard reload, which is why step 2 renders them on every request. ### Content Security Policy Rails has the cleanest nonce story of any stack here. In `config/initializers/content_security_policy.rb`: ```ruby Rails.application.configure do config.content_security_policy do |policy| policy.script_src :self, "https://cdn.stepskit.com" policy.connect_src :self, "https://stepskit.com" policy.style_src :self, :unsafe_inline policy.img_src :self, :data, "https://*.supabase.co" end config.content_security_policy_nonce_generator = ->(request) { request.session.id.to_s } config.content_security_policy_nonce_directives = %w[script-src] end ``` `style_src :unsafe_inline` is **required**, not cosmetic: the embed injects its entire stylesheet as a `