privatus-analytics-rails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fce613e4182efd36c3b231cdae877639724e6ae9b786f09cd11adaddf05182d5
-  data.tar.gz: c0a616f3c617a40484b81ebb855dab2e6ce9d042b5d5864fde8095900e469031
+  metadata.gz: 2184204c6532f24f22ae1c68f92000f5f0cc72f8c0ad580809dfa293a60e281d
+  data.tar.gz: 217a4fb72fabe001ce49e1bdbe206b652c5c77db4bbf22f18e820705c7f4e73a
 SHA512:
-  metadata.gz: efe3c7d6d58028ecbb100cd663b34dfae9daca77fe045c9c19b7346223fa7d18d351f1edc91068ccd490f1aef3b19953fef2b762298fd9bf91745dc6bfa13b31
-  data.tar.gz: 3d03ce8f72e0d0a755f9118f5fd3dc68caffab80c00bc5deebc60bec453f4b751cb0b6df3726f8ffbb660e17c19061c072cd4aeb7c7cc5256cf098ccf5f9a891
+  metadata.gz: 025e03b5bf68d3b5bc2dbbccfdbb42c0575e49d9fde7a119d11f087e962a64b143d436f765a543f3309663941c3f30680660bb94ac10494d2b31f7451a20f4c5
+  data.tar.gz: 561662158e22edfda33a9d08c2fc1cceac485fbca706c957d736b3259c5868808ddbfb1c3d9de03e6edbbaaf16a51dafa20e6781156342727743354eab0770fc

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.1.0 - 2026-10-26
+
+- README: a new intro that starts with the problem Privatus Analytics solves.
+- Changed: with `queue_stub` on, a tag that is off (development, `enabled: false` or no site id) now prints the
+  queue stub and nothing else, so `privatus.track(...)` calls in your own JavaScript never fail. Before, it
+  printed nothing. With `queue_stub` off it still prints nothing.
+- Fixed: `privatus_analytics_tag(enabled: false)` and other per call `enabled`, `site_id`, `script_host` and
+  `extra_attributes` were ignored, so a page could not turn the tag off for itself. Found by the
+  conformance tests.
+- `privatus_event_attrs` and `privatus_event_data` for custom events on buttons, links and forms.
+- `privatus_click_attr` and `privatus_click_data` for click map names.
+- Page props: `config.privatus_analytics.props` (a hash, or a lambda that gets the request) and
+  `privatus_analytics_tag(props: ...)`. They print the `privatusPageProps` script and `data-props`.
+- `queue_stub` setting, so `privatus.track` calls made before the tracker loads are kept.
+- The middleware now passes your props lambda a `Rack::Request` and adds the Rails CSP nonce when there is one.
+- `run-docker.sh` now stops at the first failing step.
+
 ## 1.0.0 - 2026-10-20
 
 - Initial release.

data/README.md

@@ -1,16 +1,39 @@
 # 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.
+**Real visitor numbers for your Rails app. No cookies, no cookie pop-up, no bots.**
 
-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.
+You want to know if people use your Rails app. But Google Analytics uses
+cookies, so in many countries you must show a cookie pop-up first (the box that
+asks visitors to say yes to cookies). Many people click no, so they never show
+up in your numbers. Bots add fake visits on top.
 
-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.
+This gem adds the Privatus Analytics script to your Rails app with a view
+helper, or a Rack middleware that puts it in the page head for you. The script
+sets no cookies and keeps no IP addresses. Bots are filtered out before they are
+counted.
+
+So you see how many real people came, which pages they looked at and where they
+came from, on one simple dashboard. A report comes to your inbox each week, and
+you can set alerts for when traffic jumps or drops. And you don't need a cookie
+pop-up for your analytics.
+
+**Free plan, no card:** 10,000 events a month (an event is a page view or an action you track) on up to 3 sites. [Start free at privatusanalytics.com](https://privatusanalytics.com).
+
+- **No cookies.** No cookies and no hidden IDs on your visitors' devices, and no IP
+  addresses are kept. Laws differ by country, so check your own legal advice.
+- **Real people, not bots.** Known bots, data centers and spam visits are left
+  out on every plan.
+- **Small and fast.** The script is about 3 KB when compressed.
+
+## What this package does
+
+- Adds the tracking script to your Rails app with a view helper.
+- An optional Rack middleware can put the script in the `<head>` for you.
+- 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 your reports, and there is a
+free plan. [Sign up at privatusanalytics.com](https://privatusanalytics.com).
 
 ## Requirements
 
@@ -61,7 +84,8 @@ In production it prints:
 ```
 
 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
+production environment (see below). The one exception is the queue stub: when
+you turn it on, it still prints. If your app uses a Content Security Policy
 nonce, the helper adds it for you.
 
 ### Or let the gem add it
@@ -74,9 +98,10 @@ 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
+already have the tag. Responses that have 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.
+`Rack::Deflater` or use the helper instead. The middleware also adds the
+Rails Content Security Policy nonce when your app has one.
 
 ## Configuration
 
@@ -95,6 +120,8 @@ Rails.application.configure do
   config.privatus_analytics.auto_inject    = false
   config.privatus_analytics.enabled_environments = %w[production]
   config.privatus_analytics.extra_attributes = { "data-mask" => "/orders/*->/orders/:id" }
+  config.privatus_analytics.props          = ->(request) { { plan: Current.account&.plan } }
+  config.privatus_analytics.queue_stub     = false
 end
 ```
 
@@ -111,6 +138,8 @@ end
 | `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 |
+| `props` | `{}` | Page props sent with every pageview and event. A hash, or a lambda that gets the request. See below |
+| `queue_stub` | `false` | Prints a small script first, so `privatus.track` calls made before the tracker loads are kept and sent later. It still prints when the tag is off, so those calls never fail |
 
 Each tracker attribute is explained in the [script attributes
 reference](https://privatusanalytics.com/docs/tracker/attributes), and the
@@ -143,22 +172,168 @@ signed-in staff, render the helper conditionally:
 <%= privatus_analytics_tag unless current_user&.admin? %>
 ```
 
-## Track your own events
+## Product analytics: see which features people use
+
+Privatus Analytics can show which buttons, forms and features people really use. You
+add a few attributes to your HTML. The tracker reads them in the browser and
+sends the events. Your server still sends nothing.
+
+### Name events well
 
-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):
+Use a short "Noun verb" name, like `Report exported` or `Invite sent`. Put the
+details in props, not in the name. So write `Report exported` with
+`format: "csv"`, not `Report exported as CSV`. Then all exports add up in one
+place, and you can split them by format.
+
+### Events on buttons, links and forms
+
+`privatus_event_attrs` prints the attributes inside a tag you write yourself:
 
 ```erb
-<button data-privatus-event="Newsletter signup" data-privatus-prop-list="weekly">Subscribe</button>
+<button <%= privatus_event_attrs("Report exported", format: "csv", source: "toolbar") %>>Export</button>
+```
+
+It prints:
+
+```html
+<button data-privatus-event="Report exported" data-privatus-prop-format="csv" data-privatus-prop-source="toolbar">Export</button>
 ```
 
+With the Rails tag helpers, use `privatus_event_data`. It returns a hash with
+the full attribute names, so you spread it into the options:
+
+```erb
+<%= tag.button "Export", **privatus_event_data("Report exported", format: "csv"), class: "btn" %>
+<%= button_tag "Export", privatus_event_data("Report exported", format: "csv") %>
+<%= link_to "Read the guide", guide_path, **privatus_event_data("Guide opened") %>
+```
+
+On a form, the event is sent when the form is submitted. `form_with` needs
+the hash under `html:`:
+
+```erb
+<%= form_with url: newsletter_path, html: privatus_event_data("Newsletter joined", list: "weekly") do |f| %>
+```
+
+The rules:
+
+* The name is trimmed and cut to 120 characters. An empty name prints nothing.
+* Prop keys are made lowercase. Anything that is not a letter, a digit or `_`
+  becomes `_`, so `"Report Type"` becomes `report_type`. Keys are cut to 64
+  characters.
+* At most 30 props. Values become text: `true`, `false`, numbers as written,
+  lists joined with commas. `nil` values are left out. Values are cut to 500
+  characters.
+* Everything is escaped for HTML.
+* The attributes print in every environment, even when the tag is off. They do
+  nothing without the tracker, so your pages look the same in development and
+  production.
+
+### Click maps
+
+A click map shows where people click on a page. Give the important parts a
+name so they stay easy to find, even when the page changes:
+
+```erb
+<a href="/pricing" <%= privatus_click_attr("pricing.cta") %>>See plans</a>
+<%= link_to "See plans", pricing_path, **privatus_click_data("pricing.cta") %>
+```
+
+A name may use letters, digits and `_ . : -`, up to 100 characters. Anything
+else prints nothing, and in development the gem writes a warning to the Rails
+log.
+
+### Page props: plan, role and other groups
+
+Page props are sent with every pageview and event on the page. Use them to
+split your reports by plan, role, app version, feature flag or account tier.
+
+Set them for every page with a lambda. It runs on each request and gets the
+request:
+
+```ruby
+config.privatus_analytics.props = lambda do |request|
+  { plan: Current.account&.plan, role: Current.user&.role, app_version: "2.4" }
+end
+```
+
+A plain hash works too. You can also set or change props for one page. They
+are merged over the configured ones, and `nil` removes one:
+
+```erb
+<%= privatus_analytics_tag(props: { section: "billing", role: nil }) %>
+```
+
+The tag then prints a small script before the tracker, with your Content
+Security Policy nonce when you have one, and points the tracker at it:
+
+```html
+<script nonce="...">window.privatusPageProps=function(){return {"plan":"pro","role":"admin"}}</script>
+<script defer src="https://privatusstats.com/js/pa.js" data-site="pa_YOURSITEID" data-props="privatusPageProps"></script>
+```
+
+Keys follow the same rules as event props. Numbers and true or false stay as
+they are, and lists stay lists (up to 30 items). The props are escaped so they
+are safe inside a script. The middleware uses the same setting. There it calls
+your lambda with a `Rack::Request`, so only use what both kinds of request
+have, like `path`, `params`, `session` and `env`.
+
+**Never put names, emails, user ids or anything that points to one person in
+props.** Privatus Analytics counts visitors without any id. Put groups (like the plan or
+the role), not people. The server also removes emails and long ids it finds.
+
+### Track from your own JavaScript
+
+For things that are not a click or a submit, call the tracker from your
+JavaScript, as the [JavaScript API
+docs](https://privatusanalytics.com/docs/tracker/javascript-api) explain:
+
+```js
+privatus.track("Feature used", { feature: "export" })
+```
+
+If your code may run before the tracker has loaded, switch on the queue stub.
+It prints a tiny script before the tracker that keeps your calls in a list and
+sends them once the tracker is ready:
+
+```ruby
+config.privatus_analytics.queue_stub = true
+```
+
+or for one layout: `<%= privatus_analytics_tag(queue_stub: true) %>`. The stub
+prints even where the tag is off (in development, or with `enabled: false`).
+Then only the stub prints: no tracker and no page props. So you can always call
+`privatus.track(...)`. In development the calls just wait in the queue and are
+never sent.
+
+### See the results
+
+* [Funnels](https://privatusanalytics.com/docs/features/funnels): how many
+  people go from one step to the next.
+* [Click maps](https://privatusanalytics.com/docs/features/click-maps): where
+  people click.
+* [Goals](https://privatusanalytics.com/docs/features/goals): turn an event
+  into a goal to count conversions.
+* [Events](https://privatusanalytics.com/docs/events): every custom event and
+  its props.
+
 ## Privacy
 
-The script sets no cookies and stores nothing in the browser. See the
+The script sets no cookies and stores nothing in the browser. The event, click
+and props helpers only print HTML attributes and a small script. Keep people
+out of your props and event props: no names, emails or user ids. See the
 [privacy documentation](https://privatusanalytics.com/docs/privacy) for what is
 collected.
 
+If you have a privacy policy, it should say which tools handle your visitors' data. You can paste this:
+
+> This website uses [Privatus Analytics](https://privatusanalytics.com/privacy-analytics) to count visits. It
+> does not use cookies and does not follow you from one website to another. Your IP address is used for a moment
+> to count visits and is never stored.
+
+Change it to fit your site. The [privacy policy generator](https://privatusanalytics.com/tools/privacy-policy-generator)
+makes a longer version with your site's name in it.
+
 ## Development
 
 The tests run in Docker so your local Ruby does not matter:

data/lib/privatus_analytics/attributes.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module PrivatusAnalytics
+  # Builds the data attributes the tracker reads for custom events and click maps.
+  # Plain Ruby, no Rails needed. The view helpers wrap these methods.
+  module Attributes
+    MAX_NAME = 120
+    MAX_KEY = 64
+    MAX_PROPS = 30
+    MAX_VALUE = 500
+    CLICK_NAME = /\A[A-Za-z0-9_.:-]{1,100}\z/
+
+    module_function
+
+    # { "data-privatus-event" => name, "data-privatus-prop-<key>" => value, ... }, or {} for an empty name.
+    def event(name, props = {})
+      name = name.to_s.strip[0, MAX_NAME].to_s.strip
+      return {} if name.empty?
+
+      attrs = { "data-privatus-event" => name }
+      normalize(props).each { |key, value| attrs["data-privatus-prop-#{key}"] = string_value(value) }
+      attrs
+    end
+
+    # { "data-privatus-click" => name }, or {} when the name is not valid.
+    def click(name)
+      name.to_s.match?(CLICK_NAME) ? { "data-privatus-click" => name.to_s } : {}
+    end
+
+    # Whether a click map name is valid: letters, digits, _ . : - and at most 100 characters.
+    def valid_click?(name)
+      name.to_s.match?(CLICK_NAME)
+    end
+
+    # Turns an attribute hash into HTML, with every value escaped.
+    def to_html(attrs)
+      attrs.map { |name, value| %(#{name}="#{CGI.escapeHTML(value.to_s)}") }.join(" ")
+    end
+
+    # Lowercases keys, swaps anything outside a-z 0-9 _ for _, cuts them to 64 characters,
+    # drops nil values and keeps the first 30 props.
+    def normalize(props)
+      clean = {}
+      (props || {}).to_h.each do |key, value|
+        key = normalize_key(key)
+        clean[key] = value unless key.empty? || value.nil?
+      end
+      clean.first(MAX_PROPS).to_h
+    end
+
+    def normalize_key(key)
+      key.to_s.downcase.gsub(/[^a-z0-9_]/, "_")[0, MAX_KEY]
+    end
+
+    def string_value(value)
+      text = value.is_a?(Array) ? value.compact.join(",") : value.to_s
+      text[0, MAX_VALUE]
+    end
+  end
+end

data/lib/privatus_analytics/configuration.rb

@@ -31,6 +31,12 @@ module PrivatusAnalytics
     attr_accessor :auto_inject
     # Extra data- attributes as a hash, for example { "data-mask" => "/orders/*->/orders/:id" }.
     attr_accessor :extra_attributes
+    # Page props sent with every pageview and event, for example { plan: "pro", role: "admin" }.
+    # A hash, or a lambda called on each request: ->(request) { { plan: Current.account&.plan } }.
+    # Never put names, emails, user ids or anything else that points to one person here.
+    attr_accessor :props
+    # true prints the tracker's queue stub first, so privatus.track works before pa.js loads.
+    attr_accessor :queue_stub
 
     def initialize
       @site_id = nil
@@ -44,6 +50,8 @@ module PrivatusAnalytics
       @enabled = nil
       @auto_inject = false
       @extra_attributes = {}
+      @props = {}
+      @queue_stub = false
     end
 
     def site_id
@@ -66,6 +74,16 @@ module PrivatusAnalytics
       Array(enabled_environments).map(&:to_s).include?(environment.to_s)
     end
 
+    # The configured props for one request. Calls the lambda when props is one.
+    # The request is an ActionDispatch::Request in views and a Rack::Request in the middleware.
+    def page_props(request = nil)
+      value = props
+      if value.respond_to?(:call)
+        value = value.respond_to?(:arity) && value.arity.zero? ? value.call : value.call(request)
+      end
+      value.respond_to?(:to_h) ? value.to_h : {}
+    end
+
     private
 
     def current_environment

data/lib/privatus_analytics/helper.rb

@@ -1,19 +1,71 @@
 # frozen_string_literal: true
 
 module PrivatusAnalytics
-  # View helper. Included into ActionView by the Railtie.
+  # View helpers. 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]) %>
+    #   <%= privatus_analytics_tag(props: { plan: "pro" }, queue_stub: true) %>
     #
     # Prints nothing without a site id, or outside the enabled environments.
+    # The one exception: with queue_stub on, the queue stub still prints (alone),
+    # so privatus.track calls in your own JavaScript never fail in development.
     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
+      options[:request] ||= request if respond_to?(:request)
+      privatus_safe(Tag.new(PrivatusAnalytics.configuration, options).to_s)
+    end
+
+    # Data attributes for a custom event, as safe HTML to put inside a tag:
+    #
+    #   <button <%= privatus_event_attrs("Export CSV", format: "csv") %>>Export</button>
+    #
+    # On a <form> the event is sent when the form is submitted.
+    def privatus_event_attrs(name, props = nil, **more_props)
+      privatus_safe(Attributes.to_html(privatus_event_data(name, props, **more_props)))
+    end
+
+    # The same attributes as a hash with full attribute names, for the Rails tag helpers:
+    #
+    #   <%= tag.button "Export", **privatus_event_data("Export CSV", format: "csv"), class: "btn" %>
+    #   <%= button_tag "Export", privatus_event_data("Export CSV") %>
+    #   <%= form_with url: signup_path, html: privatus_event_data("Newsletter signup") do |f| %>
+    #
+    # Returns {} for an empty name.
+    def privatus_event_data(name, props = nil, **more_props)
+      Attributes.event(name, (props || {}).to_h.merge(more_props))
+    end
+
+    # The click map name attribute, as safe HTML: <a <%= privatus_click_attr("pricing.cta") %>>
+    # Prints nothing when the name is not valid.
+    def privatus_click_attr(name)
+      privatus_safe(Attributes.to_html(privatus_click_data(name)))
+    end
+
+    # The click map name as a hash for the tag helpers:
+    #
+    #   <%= link_to "Pricing", pricing_path, **privatus_click_data("pricing.cta") %>
+    def privatus_click_data(name)
+      data = Attributes.click(name)
+      privatus_warn_invalid_click(name) if data.empty?
+      data
+    end
+
+    private
+
+    def privatus_safe(html)
       html.respond_to?(:html_safe) ? html.html_safe : html
     end
+
+    def privatus_warn_invalid_click(name)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+      return if Rails.respond_to?(:env) && Rails.env.production?
+
+      Rails.logger.warn("[privatus-analytics] click map name #{name.inspect} is not valid. Use letters, " \
+                        "digits and _ . : - only, at most 100 characters. Nothing was printed.")
+    end
   end
 end

data/lib/privatus_analytics/middleware.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require "rack/request"
+
 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"
+    NONCE_KEY = "action_dispatch.content_security_policy_nonce"
 
     def initialize(app, configuration = nil)
       @app = app
@@ -16,7 +19,7 @@ module PrivatusAnalytics
       status, headers, body = @app.call(env)
       return [status, headers, body] unless inject?(status, headers, env)
 
-      inject(status, headers, body)
+      inject(status, headers, body, env)
     end
 
     private
@@ -33,6 +36,14 @@ module PrivatusAnalytics
       Tag.new(configuration).render?
     end
 
+    # The Rails CSP nonce for this request, so the inline props and stub scripts are allowed.
+    def nonce(env)
+      return env[NONCE_KEY] if env[NONCE_KEY]
+      return unless defined?(ActionDispatch::Request)
+
+      ActionDispatch::Request.new(env).content_security_policy_nonce
+    end
+
     def encoded?(headers)
       !(headers["content-encoding"] || headers["Content-Encoding"]).nil?
     end
@@ -42,13 +53,13 @@ module PrivatusAnalytics
       type.to_s.downcase.start_with?("text/html")
     end
 
-    def inject(status, headers, body)
+    def inject(status, headers, body, env)
       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
+        tag = Tag.new(configuration, request: Rack::Request.new(env), nonce: nonce(env)).to_s
         html = html.sub(HEAD_CLOSE) { "#{tag}\n</head>" }
       end
 

data/lib/privatus_analytics/page_props.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PrivatusAnalytics
+  # Turns page props (plan, role and so on) into JSON that is safe inside a <script>.
+  # Keys follow the same rules as event props. Numbers, booleans and lists keep their JSON types.
+  module PageProps
+    MAX_ITEMS = 30
+    UNSAFE = /[<>&\u2028\u2029]/
+
+    module_function
+
+    # A JSON object string, or nil when there are no props to send.
+    def json(props)
+      clean = Attributes.normalize(props).filter_map do |key, value|
+        value = json_value(value)
+        [key, value] unless value.nil?
+      end
+      return nil if clean.empty?
+
+      JSON.generate(clean.to_h).gsub(UNSAFE) { |char| format("\\u%04x", char.ord) }
+    end
+
+    def json_value(value)
+      return value.compact.first(MAX_ITEMS).filter_map { |item| scalar(item) } if value.is_a?(Array)
+
+      scalar(value)
+    end
+
+    def scalar(value)
+      case value
+      when nil then nil
+      when true, false, Integer then value
+      when Float then value.finite? ? value : nil
+      else value.to_s.scrub[0, Attributes::MAX_VALUE]
+      end
+    end
+  end
+end

data/lib/privatus_analytics/tag.rb

@@ -4,36 +4,93 @@ require "cgi"
 
 module PrivatusAnalytics
   # Builds the script tag. Returns an empty string when no tag should print.
+  #
+  # Before the tracker tag it can also print the queue stub (queue_stub) and the
+  # page props script (props), each with the CSP nonce when there is one.
+  #
+  # When the tag is off (disabled, or no site id) and queue_stub is on, it prints
+  # the queue stub alone, so privatus.track calls in your own JavaScript do not
+  # fail in development. With queue_stub off it prints nothing.
   class Tag
     LIST_OPTIONS = { modules: "data-modules", excluded_paths: "data-exclude", domains: "data-domains" }.freeze
+    PROPS_FUNCTION = "privatusPageProps"
+    QUEUE_STUB = "window.privatus=window.privatus||{q:[]};['track','pageview','props','optOut','optIn','ready']" \
+                 ".forEach(function(m){window.privatus[m]=window.privatus[m]||function(){window.privatus.q.push(" \
+                 "[m,Array.prototype.slice.call(arguments)])}})"
 
+    # overrides: any setting (site_id, script_host, enabled and the rest), plus nonce:,
+    # request: (passed to a props lambda) and props: (merged over the configured props;
+    # a nil value removes one).
     def initialize(configuration = PrivatusAnalytics.configuration, overrides = {})
       @configuration = configuration
       @overrides = overrides.transform_keys(&:to_sym)
     end
 
     def render?
-      !@configuration.site_id.nil? && @configuration.enabled?
+      !site_id.nil? && enabled?
     end
 
     def to_s
-      return "" unless render?
+      html = []
+      html << inline_script(QUEUE_STUB) if option(:queue_stub) == true
+      return html.join("\n") unless render?
 
-      parts = attributes.map { |name, value| value == true ? name : %(#{name}="#{CGI.escapeHTML(value.to_s)}") }
-      "<script #{parts.join(' ')}></script>"
+      props_json = PageProps.json(page_props)
+      html << inline_script("window.#{PROPS_FUNCTION}=function(){return #{props_json}}") if props_json
+      html << script_tag(props_json ? { "data-props" => PROPS_FUNCTION } : {})
+      html.join("\n")
     end
 
     def attributes
-      attrs = { "defer" => true, "src" => "#{@configuration.script_host}/js/pa.js",
-                "data-site" => @configuration.site_id }
+      attrs = { "defer" => true, "src" => "#{script_host}/js/pa.js", "data-site" => site_id }
       add_options(attrs)
-      @configuration.extra_attributes.each { |name, value| attrs[name.to_s] = value unless value.nil? }
+      (option(:extra_attributes) || {}).each { |name, value| attrs[name.to_s] = value unless value.nil? }
       attrs["nonce"] = @overrides[:nonce] if @overrides[:nonce]
       attrs
     end
 
+    # Configured props for this request with the per call props merged on top.
+    def page_props
+      props = keyed(@configuration.page_props(@overrides[:request]))
+      props.merge(keyed(@overrides[:props]))
+    end
+
     private
 
+    # A per call site_id, script_host or enabled wins over the configuration.
+    def site_id
+      value = @overrides[:site_id].to_s.strip
+      value.empty? ? @configuration.site_id : value
+    end
+
+    def script_host
+      value = @overrides[:script_host].to_s.strip
+      value.empty? ? @configuration.script_host : value.chomp("/")
+    end
+
+    def enabled?
+      return @overrides[:enabled] ? true : false unless @overrides[:enabled].nil?
+
+      @configuration.enabled?
+    end
+
+    def script_tag(more)
+      parts = attributes.merge(more).map do |name, value|
+        value == true ? name : %(#{name}="#{CGI.escapeHTML(value.to_s)}")
+      end
+      "<script #{parts.join(' ')}></script>"
+    end
+
+    def inline_script(code)
+      nonce = @overrides[:nonce]
+      opening = nonce ? %(<script nonce="#{CGI.escapeHTML(nonce.to_s)}">) : "<script>"
+      "#{opening}#{code}</script>"
+    end
+
+    def keyed(props)
+      (props || {}).to_h.transform_keys { |key| Attributes.normalize_key(key) }
+    end
+
     def add_options(attrs)
       LIST_OPTIONS.each do |name, attribute|
         values = list(option(name))

data/lib/privatus_analytics/version.rb

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

data/lib/privatus_analytics.rb

@@ -2,6 +2,8 @@
 
 require "privatus_analytics/version"
 require "privatus_analytics/configuration"
+require "privatus_analytics/attributes"
+require "privatus_analytics/page_props"
 require "privatus_analytics/tag"
 require "privatus_analytics/middleware"
 require "privatus_analytics/helper"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: privatus-analytics-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Two Phase LLC
@@ -63,9 +63,11 @@ files:
 - README.md
 - lib/privatus-analytics-rails.rb
 - lib/privatus_analytics.rb
+- lib/privatus_analytics/attributes.rb
 - lib/privatus_analytics/configuration.rb
 - lib/privatus_analytics/helper.rb
 - lib/privatus_analytics/middleware.rb
+- lib/privatus_analytics/page_props.rb
 - lib/privatus_analytics/railtie.rb
 - lib/privatus_analytics/tag.rb
 - lib/privatus_analytics/version.rb