privatus-analytics-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fce613e4182efd36c3b231cdae877639724e6ae9b786f09cd11adaddf05182d5
+  data.tar.gz: c0a616f3c617a40484b81ebb855dab2e6ce9d042b5d5864fde8095900e469031
+SHA512:
+  metadata.gz: efe3c7d6d58028ecbb100cd663b34dfae9daca77fe045c9c19b7346223fa7d18d351f1edc91068ccd490f1aef3b19953fef2b762298fd9bf91745dc6bfa13b31
+  data.tar.gz: 3d03ce8f72e0d0a755f9118f5fd3dc68caffab80c00bc5deebc60bec453f4b751cb0b6df3726f8ffbb660e17c19061c072cd4aeb7c7cc5256cf098ccf5f9a891

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 - 2026-10-20
+
+- Initial release.
+- `privatus_analytics_tag` view helper.
+- Optional Rack middleware that adds the tag to the head of HTML responses (off by default).
+- Settings for site id, script host, modules, excluded paths, single-page app mode and more.
+- Skips every environment except production by default.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Two Phase LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,181 @@
+# Privatus Analytics for Rails
+
+Adds the cookieless [Privatus Analytics](https://privatusanalytics.com)
+tracking script to your Rails app with a view helper, or with an optional Rack
+middleware that puts it in the `<head>` for you.
+
+Privatus Analytics counts visits, sources, pages and conversions without
+cookies, local storage or fingerprinting, so analytics does not need a consent
+banner by itself. Check with your own counsel for your country.
+
+The gem only prints the browser script. It never sends events from your server
+and sets no cookies. You need a Privatus Analytics account to see reports, and
+there is a free plan. Sign up at https://privatusanalytics.com.
+
+## Requirements
+
+* Ruby 3.2 or later.
+* Rails 6.1 to 8.x.
+* A Privatus Analytics site id (it starts with `pa_`). You find it under
+  Site settings, Tracking.
+
+## Install
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "privatus-analytics-rails"
+```
+
+Then run `bundle install`. For the full setup guide and every tracker option,
+see the [Privatus Analytics docs](https://privatusanalytics.com/docs).
+
+Set your site id with an environment variable:
+
+```sh
+PRIVATUS_SITE_ID=pa_YOURSITEID
+```
+
+or in `config/environments/production.rb` (or `config/application.rb`):
+
+```ruby
+config.privatus_analytics.site_id = "pa_YOURSITEID"
+```
+
+## Add the tag
+
+Put the helper in the `<head>` of your layout, for example
+`app/views/layouts/application.html.erb`:
+
+```erb
+<head>
+  <title>My app</title>
+  <%= privatus_analytics_tag %>
+</head>
+```
+
+In production it prints:
+
+```html
+<script defer src="https://privatusstats.com/js/pa.js" data-site="pa_YOURSITEID"></script>
+```
+
+The tag prints nothing when there is no site id, and nothing outside the
+production environment (see below). If your app uses a Content Security Policy
+nonce, the helper adds it for you.
+
+### Or let the gem add it
+
+If you would rather not touch your layouts, switch on the middleware:
+
+```ruby
+config.privatus_analytics.auto_inject = true
+```
+
+It adds the tag just before `</head>` in uncompressed `text/html` responses with
+status 200. It skips Ajax requests, pages without a `<head>`, and pages that
+already have the tag. Responses that carry a `Content-Encoding` header are left
+alone, so if you compress inside the Rack stack, add the middleware above
+`Rack::Deflater` or use the helper instead.
+
+## Configuration
+
+Every setting is optional except the site id.
+
+```ruby
+# config/environments/production.rb
+Rails.application.configure do
+  config.privatus_analytics.site_id        = "pa_YOURSITEID"      # or ENV["PRIVATUS_SITE_ID"]
+  config.privatus_analytics.script_host    = "https://privatusstats.com" # or ENV["PRIVATUS_SCRIPT_HOST"]
+  config.privatus_analytics.modules        = %w[engage auto vitals clicks ask]
+  config.privatus_analytics.excluded_paths = %w[/admin/* /preview/*]
+  config.privatus_analytics.domains        = %w[example.com www.example.com]
+  config.privatus_analytics.spa            = "auto"   # auto, history, hash or off
+  config.privatus_analytics.manual         = false    # true turns off the automatic pageview
+  config.privatus_analytics.auto_inject    = false
+  config.privatus_analytics.enabled_environments = %w[production]
+  config.privatus_analytics.extra_attributes = { "data-mask" => "/orders/*->/orders/:id" }
+end
+```
+
+| Setting | Default | What it does |
+|---|---|---|
+| `site_id` | `ENV["PRIVATUS_SITE_ID"]` | The `data-site` attribute. Nothing prints without it |
+| `script_host` | `https://privatusstats.com` | Where `/js/pa.js` is served. Change it only if you host your own copy |
+| `modules` | tracker default (`engage`) | The `data-modules` attribute. Setting it replaces the default, so keep `engage` for time on page and scroll depth. `[]` loads none |
+| `excluded_paths` | none | The `data-exclude` attribute. Path globs the tracker never counts |
+| `domains` | all hosts | The `data-domains` attribute. Count only these hostnames |
+| `spa` | `auto` | The `data-spa` attribute |
+| `manual` | `false` | The `data-manual` attribute |
+| `enabled_environments` | `["production"]` | Rails environments that get the tag |
+| `enabled` | `nil` | `true` or `false` forces the tag on or off in every environment |
+| `auto_inject` | `false` | Adds the tag with a Rack middleware |
+| `extra_attributes` | `{}` | Any other `data-*` attribute |
+
+Each tracker attribute is explained in the [script attributes
+reference](https://privatusanalytics.com/docs/tracker/attributes), and the
+modules in [Modules](https://privatusanalytics.com/docs/tracker/modules).
+
+You can also override a setting for one page:
+
+```erb
+<%= privatus_analytics_tag(modules: %w[engage auto], excluded_paths: ["/preview/*"]) %>
+```
+
+### Development and test
+
+Development, test and staging requests are not counted by default, so your own
+clicking around never reaches your reports. To see the tag while you build, set
+`config.privatus_analytics.enabled = true`. The tracker also ignores `localhost`
+unless you pass `data-allow-local` or `data-debug` (see [Debug
+mode](https://privatusanalytics.com/docs/tracker/debug)):
+
+```ruby
+config.privatus_analytics.extra_attributes = { "data-debug" => "true" }
+```
+
+### Leaving people out
+
+Use `data-exclude` through `excluded_paths` for admin areas. To leave out
+signed-in staff, render the helper conditionally:
+
+```erb
+<%= privatus_analytics_tag unless current_user&.admin? %>
+```
+
+## Track your own events
+
+The gem only loads the tracker. Track custom events from the browser, as
+described in the [JavaScript API
+docs](https://privatusanalytics.com/docs/tracker/javascript-api):
+
+```erb
+<button data-privatus-event="Newsletter signup" data-privatus-prop-list="weekly">Subscribe</button>
+```
+
+## Privacy
+
+The script sets no cookies and stores nothing in the browser. See the
+[privacy documentation](https://privatusanalytics.com/docs/privacy) for what is
+collected.
+
+## Development
+
+The tests run in Docker so your local Ruby does not matter:
+
+```sh
+./run-docker.sh
+```
+
+It runs the Minitest suite against a small dummy Rails app, RuboCop, and
+`gem build`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+https://github.com/Privatus-Analytics/rails.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt). Privatus Analytics is a product of Two
+Phase LLC, Wyoming, USA.

data/lib/privatus-analytics-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "privatus_analytics"

data/lib/privatus_analytics/configuration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PrivatusAnalytics
+  # Settings for the tracking script. Set them with
+  # `config.privatus_analytics.<name> = value` in a Rails environment file,
+  # or with `PrivatusAnalytics.configure`.
+  class Configuration
+    DEFAULT_HOST = "https://privatusstats.com"
+    MODULES = %w[engage auto vitals clicks ask].freeze
+    SPA_MODES = %w[auto history hash off].freeze
+
+    # The site id (starts with pa_). Falls back to ENV["PRIVATUS_SITE_ID"].
+    attr_writer :site_id
+    # Origin that serves /js/pa.js. Falls back to ENV["PRIVATUS_SCRIPT_HOST"].
+    attr_writer :script_host
+    # Tracker modules to load, for example %w[engage auto]. nil keeps the tracker default.
+    attr_accessor :modules
+    # Path globs the tracker never counts, for example %w[/admin/* /preview/*].
+    attr_accessor :excluded_paths
+    # Hostnames to count. nil counts every host.
+    attr_accessor :domains
+    # One of auto, history, hash, off. nil keeps the tracker default.
+    attr_accessor :spa
+    # true turns off the automatic pageview. See the manual mode docs.
+    attr_accessor :manual
+    # Rails environments that get the tag. Used when `enabled` is nil.
+    attr_accessor :enabled_environments
+    # true or false forces the tag on or off whatever the environment. nil uses enabled_environments.
+    attr_accessor :enabled
+    # true adds the tag to the head of HTML responses with a Rack middleware.
+    attr_accessor :auto_inject
+    # Extra data- attributes as a hash, for example { "data-mask" => "/orders/*->/orders/:id" }.
+    attr_accessor :extra_attributes
+
+    def initialize
+      @site_id = nil
+      @script_host = nil
+      @modules = nil
+      @excluded_paths = []
+      @domains = nil
+      @spa = nil
+      @manual = false
+      @enabled_environments = %w[production]
+      @enabled = nil
+      @auto_inject = false
+      @extra_attributes = {}
+    end
+
+    def site_id
+      value = @site_id.to_s.strip
+      value = ENV.fetch("PRIVATUS_SITE_ID", "").strip if value.empty?
+      value.empty? ? nil : value
+    end
+
+    def script_host
+      value = @script_host.to_s.strip
+      value = ENV.fetch("PRIVATUS_SCRIPT_HOST", "").strip if value.empty?
+      value = DEFAULT_HOST if value.empty?
+      value.chomp("/")
+    end
+
+    # Whether the current Rails environment should get the tag.
+    def enabled?(environment = current_environment)
+      return @enabled ? true : false unless @enabled.nil?
+
+      Array(enabled_environments).map(&:to_s).include?(environment.to_s)
+    end
+
+    private
+
+    def current_environment
+      defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.to_s : ENV.fetch("RAILS_ENV", "development")
+    end
+  end
+end

data/lib/privatus_analytics/helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PrivatusAnalytics
+  # View helper. Included into ActionView by the Railtie.
+  module Helper
+    # Prints the Privatus Analytics script tag. Put it in the head of your layout.
+    #
+    #   <%= privatus_analytics_tag %>
+    #   <%= privatus_analytics_tag(modules: %w[engage auto]) %>
+    #
+    # Prints nothing without a site id, or outside the enabled environments.
+    def privatus_analytics_tag(options = {})
+      options = options.dup
+      options[:nonce] ||= content_security_policy_nonce if respond_to?(:content_security_policy_nonce)
+      html = Tag.new(PrivatusAnalytics.configuration, options).to_s
+      html.respond_to?(:html_safe) ? html.html_safe : html
+    end
+  end
+end

data/lib/privatus_analytics/middleware.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PrivatusAnalytics
+  # Adds the script tag just before </head> in HTML responses.
+  # Off unless `config.privatus_analytics.auto_inject = true`.
+  class Middleware
+    HEAD_CLOSE = %r{</head>}i
+    MARKER = "/js/pa.js"
+
+    def initialize(app, configuration = nil)
+      @app = app
+      @configuration = configuration
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      return [status, headers, body] unless inject?(status, headers, env)
+
+      inject(status, headers, body)
+    end
+
+    private
+
+    def configuration
+      @configuration || PrivatusAnalytics.configuration
+    end
+
+    def inject?(status, headers, env)
+      return false unless configuration.auto_inject
+      return false unless status == 200 && html?(headers) && !encoded?(headers)
+      return false if env["HTTP_X_REQUESTED_WITH"].to_s.casecmp?("XMLHttpRequest")
+
+      Tag.new(configuration).render?
+    end
+
+    def encoded?(headers)
+      !(headers["content-encoding"] || headers["Content-Encoding"]).nil?
+    end
+
+    def html?(headers)
+      type = headers["content-type"] || headers["Content-Type"]
+      type.to_s.downcase.start_with?("text/html")
+    end
+
+    def inject(status, headers, body)
+      html = +""
+      body.each { |part| html << part.to_s }
+      body.close if body.respond_to?(:close)
+
+      unless html.include?(MARKER) || !html.match?(HEAD_CLOSE)
+        tag = Tag.new(configuration).to_s
+        html = html.sub(HEAD_CLOSE) { "#{tag}\n</head>" }
+      end
+
+      headers = headers.dup
+      headers.delete("content-length")
+      headers.delete("Content-Length")
+      headers["content-length"] = html.bytesize.to_s
+      [status, headers, [html]]
+    end
+  end
+end

data/lib/privatus_analytics/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module PrivatusAnalytics
+  # Wires the settings, the view helper and the optional middleware into Rails.
+  class Railtie < Rails::Railtie
+    config.privatus_analytics = PrivatusAnalytics.configuration
+
+    initializer "privatus_analytics.helper" do
+      ActiveSupport.on_load(:action_view) { include PrivatusAnalytics::Helper }
+    end
+
+    initializer "privatus_analytics.middleware" do |app|
+      app.middleware.use PrivatusAnalytics::Middleware
+    end
+  end
+end

data/lib/privatus_analytics/tag.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module PrivatusAnalytics
+  # Builds the script tag. Returns an empty string when no tag should print.
+  class Tag
+    LIST_OPTIONS = { modules: "data-modules", excluded_paths: "data-exclude", domains: "data-domains" }.freeze
+
+    def initialize(configuration = PrivatusAnalytics.configuration, overrides = {})
+      @configuration = configuration
+      @overrides = overrides.transform_keys(&:to_sym)
+    end
+
+    def render?
+      !@configuration.site_id.nil? && @configuration.enabled?
+    end
+
+    def to_s
+      return "" unless render?
+
+      parts = attributes.map { |name, value| value == true ? name : %(#{name}="#{CGI.escapeHTML(value.to_s)}") }
+      "<script #{parts.join(' ')}></script>"
+    end
+
+    def attributes
+      attrs = { "defer" => true, "src" => "#{@configuration.script_host}/js/pa.js",
+                "data-site" => @configuration.site_id }
+      add_options(attrs)
+      @configuration.extra_attributes.each { |name, value| attrs[name.to_s] = value unless value.nil? }
+      attrs["nonce"] = @overrides[:nonce] if @overrides[:nonce]
+      attrs
+    end
+
+    private
+
+    def add_options(attrs)
+      LIST_OPTIONS.each do |name, attribute|
+        values = list(option(name))
+        # nil keeps the tracker default. An empty modules list loads none.
+        attrs[attribute] = values.join(",") if values && (name == :modules || !values.empty?)
+      end
+      spa = option(:spa).to_s
+      attrs["data-spa"] = spa if Configuration::SPA_MODES.include?(spa) && spa != "auto"
+      attrs["data-manual"] = "true" if option(:manual) == true
+    end
+
+    def option(name)
+      @overrides.key?(name) ? @overrides[name] : @configuration.public_send(name)
+    end
+
+    # nil stays nil. Anything else becomes a clean array of strings.
+    def list(value)
+      return nil if value.nil?
+
+      Array(value).flat_map { |item| item.to_s.split(",") }.map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/privatus_analytics/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PrivatusAnalytics
+  VERSION = "1.0.0"
+end

data/lib/privatus_analytics.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "privatus_analytics/version"
+require "privatus_analytics/configuration"
+require "privatus_analytics/tag"
+require "privatus_analytics/middleware"
+require "privatus_analytics/helper"
+# Adds the cookieless Privatus Analytics tracking script to Rails apps.
+#
+# The gem only prints the browser script. It never sends events from the server.
+module PrivatusAnalytics
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    # Puts every setting back to its default. Handy in tests.
+    def reset_configuration!
+      configuration.send(:initialize)
+    end
+  end
+end
+
+require "privatus_analytics/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: privatus-analytics-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Two Phase LLC
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Adds the Privatus Analytics tracking script to your Rails views with
+  a helper or an optional Rack middleware. The script sets no cookies, so analytics
+  does not need a consent banner by itself.
+email:
+- james@privatusanalytics.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/privatus-analytics-rails.rb
+- lib/privatus_analytics.rb
+- lib/privatus_analytics/configuration.rb
+- lib/privatus_analytics/helper.rb
+- lib/privatus_analytics/middleware.rb
+- lib/privatus_analytics/railtie.rb
+- lib/privatus_analytics/tag.rb
+- lib/privatus_analytics/version.rb
+homepage: https://privatusanalytics.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://privatusanalytics.com
+  source_code_uri: https://github.com/Privatus-Analytics/rails
+  changelog_uri: https://github.com/Privatus-Analytics/rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Privatus-Analytics/rails/issues
+  documentation_uri: https://privatusanalytics.com/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Cookieless Privatus Analytics tracking script for Rails.
+test_files: []