track_relay 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 918577fceae3974911227a1b988f8d17ecf636c086b7f91ad9b8e36ac6d2b9fd
-  data.tar.gz: 1dcd1c4f9bb900b0b3945a40ae0222b3205212f52477e10640baa0facc39ae40
+  metadata.gz: 4d71fbb5a7101c3f407ba9fc7c05bf032a5718447a7cacd341647b9b794c47b2
+  data.tar.gz: b36598739beda0519f71b98cf906159b3857234dd9510d7aff35d1f33ecd9808
 SHA512:
-  metadata.gz: c95d0181afcad7811afaff649155f78681f41a2d54fc3f3ebaf1057f56e4b146d5704a6954e83183d9ef78269a807b648545cc493b42e22c9b93dd53084c9fd2
-  data.tar.gz: 9d0c93c207fbdfa07237d9f25657053626711ac0eedf576fd0bb36db84203b67e716bd0f382face10074cbacb4a24842a7e56ac1c7b7adc82ac59aed66036fd3
+  metadata.gz: f71946bad98b203c57850991846de8e3fb95828bc825f5d9ccb2d6b5a205d6531253087a65e77c0e4eb4981f5e95129439ecf081fc719939618daeb93b611ca0
+  data.tar.gz: 1b05f9d685e43a6c97e37f306aa6f0a970f1b7fe6ccb774a037a4a26043295d7464a22ec2d821425aad6eb9ac6e1e07461420f7fc8ce6875f3bec1919e3d95e1

data/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-07-31
+
+### Added
+- `TrackRelay::PageViewTracking` — opt-in automatic server-side
+  `page_view` emission for hosts delivering GA4 purely via the
+  Measurement Protocol (no client gtag). `include
+  TrackRelay::PageViewTracking` + `track_page_views` emits exactly one
+  `page_view` per full HTML page render — never for JSON/non-HTML,
+  turbo-frame fetches, turbo-stream responses, redirects, non-GETs, or
+  unsuccessful responses. A host suppression hook (`track_page_views
+  if: :method_name` or a proc, instance-exec'd per request) is where
+  tracking policy (opt-out, geo, bot checks) plugs in. Events ride the
+  normal `TrackRelay.track` path, so `track_gate`, subscribers, and
+  GA4 page-context enrichment apply unchanged.
+- The builtin `page_view` event is registered directly with the
+  catalog (and therefore the manifest), deliberately bypassing the
+  DSL's GA4 reserved-name validation: that guard protects *custom*
+  events from shadowing gtag auto-collection, but the MP-standard
+  `page_view` is exactly what a server-side host must send.
+
+## [1.2.0] - 2026-07-31
+
+### Added
+- `ClientId::SignedToken` — first-party, HMAC-signed analytics token
+  (ActiveSupport::MessageVerifier, SHA256) as a cryptographic
+  proof-of-browser replacement for `_ga`-cookie sniffing. Carries
+  `client_id`, `session_id`, `session_started_at`, and `last_seen_at`;
+  `mint`/`read`/`from_request` reject tampered, forged, wrong-secret,
+  and expired (`ttl:`) values by returning `nil`.
+- `TrackRelay::HandshakeEndpoint` — routable Rack endpoint
+  (`post "/analytics/handshakes", to: TrackRelay::HandshakeEndpoint`)
+  that mints/refreshes the signed token cookie (HttpOnly,
+  SameSite=Lax, secure on SSL). Preserves an existing token's
+  client_id, rotates the session after 30 minutes of inactivity
+  (`SESSION_INACTIVITY_TIMEOUT`), and raises `ConfigurationError`
+  when `signed_client_token_secret` is unset.
+- Config: `signed_client_token_secret` (default `nil` — feature off)
+  and `signed_client_token_ttl` (default 30 days).
+- `ConfigurationError` error class.
+
+### Changed
+- `Subscribers::Ga4MeasurementProtocol#prepare` now prefers the signed
+  first-party token — for both the browser-proof client_id and
+  page-context session enrichment — falling back to the `_ga` /
+  `_ga_<stream>` cookies so hosts can migrate incrementally. Behavior
+  is unchanged for hosts that don't configure a signed-token secret.
+
 ## [1.1.0] - 2026-07-07
 
 ### Added

data/lib/track_relay/client_id/signed_token.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "active_support/message_verifier"
+
+module TrackRelay
+  module ClientId
+    # First-party, HMAC-signed client token — the spoof-proof
+    # replacement for `_ga`-cookie browser proof.
+    #
+    # The cookie value is generated and verified with
+    # {ActiveSupport::MessageVerifier} (SHA256), so any tampering,
+    # truncation, or wrong-secret forgery verifies to `nil` rather
+    # than raising.
+    class SignedToken
+      COOKIE_NAME = "_tr_cid"
+
+      # Verified token contents. `session_started_at` is a Time (UTC);
+      # `session_id`/`client_id` are strings shaped for GA4 payloads.
+      Token = Struct.new(:client_id, :session_id, :session_started_at, :last_seen_at, keyword_init: true)
+
+      # Generate a signed cookie value embedding the client_id and
+      # optional session fields.
+      #
+      # @param secret [String] HMAC signing secret
+      # @param client_id [String] GA4-shaped client id to embed
+      # @param session_id [String, nil] GA4 session id
+      # @param session_started_at [Time, nil] start of the embedded session
+      # @param ttl [ActiveSupport::Duration, nil] validity window;
+      #   `nil` mints a non-expiring token
+      # @return [String] opaque signed cookie value
+      def self.mint(secret:, client_id:, session_id: nil, session_started_at: nil, last_seen_at: nil, ttl: nil)
+        payload = {
+          "cid" => client_id,
+          "sid" => session_id,
+          "sst" => session_started_at&.to_i,
+          "lsa" => last_seen_at&.to_i
+        }.compact
+        verifier(secret).generate(payload, expires_in: ttl)
+      end
+
+      # Read and verify the signed cookie into a {Token}.
+      #
+      # @param request [#cookies, nil] any object exposing
+      #   `request.cookies[COOKIE_NAME]`
+      # @param secret [String] HMAC signing secret
+      # @return [Token, nil] verified token contents, or `nil` when the
+      #   cookie is missing or unverifiable.
+      def self.read(request, secret:)
+        value = request&.cookies&.[](COOKIE_NAME)
+        return nil if value.nil? || value.empty?
+
+        payload = verifier(secret).verified(value)
+        return nil unless payload
+
+        Token.new(
+          client_id: payload["cid"],
+          session_id: payload["sid"],
+          session_started_at: payload["sst"] && Time.at(payload["sst"]).utc,
+          last_seen_at: payload["lsa"] && Time.at(payload["lsa"]).utc
+        )
+      end
+
+      # Convenience for gate/client-id use: just the verified client_id.
+      #
+      # @param request [#cookies, nil] any object exposing
+      #   `request.cookies[COOKIE_NAME]`
+      # @param secret [String] HMAC signing secret
+      # @return [String, nil] the embedded client_id, or `nil` when the
+      #   cookie is missing or unverifiable.
+      def self.from_request(request, secret:)
+        read(request, secret: secret)&.client_id
+      end
+
+      def self.verifier(secret)
+        ActiveSupport::MessageVerifier.new(secret, digest: "SHA256", serializer: JSON)
+      end
+      private_class_method :verifier
+    end
+  end
+end

data/lib/track_relay/configuration.rb

@@ -85,7 +85,9 @@ module TrackRelay
       :ga4_use_eu_endpoint,
       :ga4_require_browser_client_id,
       :ga4_enrich_page_context,
-      :track_gate
+      :track_gate,
+      :signed_client_token_secret,
+      :signed_client_token_ttl
 
     # @return [Array] registered subscriber instances, in insertion order
     attr_reader :subscribers
@@ -112,6 +114,8 @@ module TrackRelay
       @ga4_require_browser_client_id = false
       @ga4_enrich_page_context = false
       @track_gate = nil
+      @signed_client_token_secret = nil
+      @signed_client_token_ttl = 30.days
     end
 
     # Append a subscriber to the registry.

data/lib/track_relay/errors.rb

@@ -32,6 +32,11 @@ module TrackRelay
   # the catalog and untyped events are disabled.
   class UnknownEventError < Error; end
 
+  # Raised when a feature is used without its required configuration —
+  # e.g. mounting {HandshakeEndpoint} without setting
+  # `config.signed_client_token_secret`.
+  class ConfigurationError < Error; end
+
   # Raised by a subscriber's `#deliver` to signal a *transient* failure
   # that the {DeliveryJob} should retry via ActiveJob's `retry_on`.
   # Examples: HTTP 5xx response, `Net::OpenTimeout`, `Errno::ECONNREFUSED`,

data/lib/track_relay/handshake_endpoint.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TrackRelay
+  # Routable Rack endpoint that mints the first-party signed analytics
+  # token ({ClientId::SignedToken}). Hosts mount it directly:
+  #
+  #   post "/analytics/handshakes", to: TrackRelay::HandshakeEndpoint
+  #
+  # A small host-side JS module calls it from the browser; because only
+  # JS-executing clients ever do, possession of a valid token is
+  # proof-of-browser for the host's `track_gate`.
+  class HandshakeEndpoint
+    # GA4 semantics: a session ends after this much inactivity, however
+    # long it has been running. Activity = any handshake call.
+    SESSION_INACTIVITY_TIMEOUT = 30 * 60
+
+    def self.call(env)
+      new.call(env)
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      config = TrackRelay.config
+      now = Time.now.utc
+
+      if config.signed_client_token_secret.nil? || config.signed_client_token_secret.empty?
+        raise ConfigurationError,
+          "TrackRelay::HandshakeEndpoint requires config.signed_client_token_secret to be set"
+      end
+
+      existing = ClientId::SignedToken.read(request, secret: config.signed_client_token_secret)
+      session_alive = existing && !session_stale?(existing, now)
+
+      cookie_value = ClientId::SignedToken.mint(
+        secret: config.signed_client_token_secret,
+        client_id: existing&.client_id || fresh_client_id(now),
+        session_id: session_alive ? existing.session_id : now.to_i.to_s,
+        session_started_at: session_alive ? existing.session_started_at : now,
+        last_seen_at: now,
+        ttl: config.signed_client_token_ttl
+      )
+
+      [204, {"set-cookie" => set_cookie(cookie_value, request, now, config)}, []]
+    end
+
+    private
+
+    # A session with no recorded activity falls back to its start time,
+    # so pre-`last_seen_at` tokens still rotate sensibly.
+    def session_stale?(token, now)
+      reference = token.last_seen_at || token.session_started_at
+      reference.nil? || (now - reference) > SESSION_INACTIVITY_TIMEOUT
+    end
+
+    # GA4-shaped client_id: `<random_int31>.<unix_ts>`.
+    def fresh_client_id(now)
+      "#{SecureRandom.random_number(0x7FFFFFFF)}.#{now.to_i}"
+    end
+
+    def set_cookie(value, request, now, config)
+      attributes = {
+        value: value,
+        path: "/",
+        httponly: true,
+        same_site: :lax,
+        secure: request.ssl?
+      }
+      attributes[:expires] = now + config.signed_client_token_ttl if config.signed_client_token_ttl
+
+      Rack::Utils.set_cookie_header(ClientId::SignedToken::COOKIE_NAME, attributes)
+    end
+  end
+end

data/lib/track_relay/page_view_tracking.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module TrackRelay
+  # Opt-in automatic server-side `page_view` emission.
+  #
+  # Hosts that deliver GA4 purely via the Measurement Protocol (no
+  # client-side gtag) still need standard `page_view` events for GA4's
+  # page and engagement reports. Include this concern and call the
+  # macro:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include TrackRelay::PageViewTracking
+  #     track_page_views
+  #   end
+  #
+  # Events go through the normal {TrackRelay.track} path, so the host's
+  # `track_gate`, subscribers, and GA4 page-context enrichment apply
+  # unchanged.
+  #
+  # ## The builtin `page_view` catalog entry
+  #
+  # `page_view` sits in {TrackRelay::GA4_RESERVED_NAMES}, which guards
+  # *custom* catalog events from shadowing gtag's auto-collected ones.
+  # A server-side host has no auto-collection — the MP-standard
+  # `page_view` is exactly what it must send — so the concern registers
+  # the definition directly with the catalog, bypassing the DSL's
+  # reserved-name validation on purpose.
+  module PageViewTracking
+    extend ActiveSupport::Concern
+
+    include ControllerTracking
+
+    # Register the builtin `page_view` {EventDefinition} (no params —
+    # page context is attached by GA4 enrichment at delivery time).
+    # Idempotent so it can be re-run after test-suite `Catalog.clear!`.
+    #
+    # @return [void]
+    def self.register_builtin_event!
+      return if Catalog.defined?(:page_view)
+
+      Catalog.register(EventDefinition.new(name: :page_view))
+    end
+
+    included do
+      class_attribute :_track_relay_page_view_condition,
+        instance_accessor: false, instance_predicate: false, default: nil
+    end
+
+    class_methods do
+      # Enable automatic page_view emission for this controller (and
+      # subclasses).
+      #
+      # @param if [Symbol, Proc, nil] host-side suppression hook —
+      #   a method name or proc evaluated in the controller instance
+      #   per request; a falsy result suppresses the page_view.
+      #   Tracking *policy* (opt-out, geo, bot checks) belongs to the
+      #   host; this is where it plugs in.
+      # @return [void]
+      def track_page_views(if: nil)
+        self._track_relay_page_view_condition = binding.local_variable_get(:if)
+        PageViewTracking.register_builtin_event!
+        after_action :_track_relay_emit_page_view
+      end
+    end
+
+    private
+
+    def _track_relay_emit_page_view
+      return unless _track_relay_page_view_response?
+      return unless _track_relay_page_view_allowed?
+
+      PageViewTracking.register_builtin_event!
+      track(:page_view)
+    end
+
+    def _track_relay_page_view_allowed?
+      condition = self.class._track_relay_page_view_condition
+      case condition
+      when nil then true
+      when Symbol then !!send(condition)
+      else !!instance_exec(&condition)
+      end
+    end
+
+    # Exactly one page_view per full HTML page render:
+    #
+    # - GET only (a POST that re-renders a form is not a page view)
+    # - successful (2xx) only — redirects land on a page that fires its
+    #   own page_view; error pages are noise
+    # - `text/html` only (excludes JSON and turbo-stream's
+    #   `text/vnd.turbo-stream.html`)
+    # - not a turbo-frame fetch (partial navigation within a page)
+    def _track_relay_page_view_response?
+      request.get? &&
+        response.successful? &&
+        response.media_type == "text/html" &&
+        request.headers["Turbo-Frame"].nil?
+    end
+  end
+end

data/lib/track_relay/subscribers/ga4_measurement_protocol.rb

@@ -121,12 +121,13 @@ module TrackRelay
         return payload unless config.ga4_require_browser_client_id || config.ga4_enrich_page_context
 
         request = Current.request
-        client_id = ClientId::Ga.from_request(request)
+        token = signed_token(request, config)
+        client_id = token&.client_id || ClientId::Ga.from_request(request)
         return nil if config.ga4_require_browser_client_id && client_id.nil?
         return payload if request.nil?
 
         hash = payload.to_h
-        hash[:params] = hash[:params].merge(page_params(request)) if config.ga4_enrich_page_context
+        hash[:params] = hash[:params].merge(page_params(request, token)) if config.ga4_enrich_page_context
         hash[:context] = hash[:context].merge(client_id: client_id) if client_id
         EventPayload.from_h(hash)
       end
@@ -158,13 +159,25 @@ module TrackRelay
 
       private
 
+      # Verified first-party token, when the host has configured a
+      # signed-token secret. The token is the preferred (cryptographic)
+      # source for both client_id and session_id; the `_ga`/`_ga_<stream>`
+      # cookies remain as fallbacks so hosts can migrate incrementally.
+      #
+      # @return [ClientId::SignedToken::Token, nil]
+      def signed_token(request, config)
+        return nil unless config.signed_client_token_secret
+
+        ClientId::SignedToken.read(request, secret: config.signed_client_token_secret)
+      end
+
       # Page-context params captured from the live request (only when
       # `config.ga4_enrich_page_context` is enabled).
-      def page_params(request)
+      def page_params(request, token = nil)
         params = {page_location: request.original_url}
         params[:page_referrer] = request.referer if request.referer && !request.referer.empty?
 
-        if (session_id = ga_session_id(request))
+        if (session_id = token&.session_id || ga_session_id(request))
           params[:session_id] = session_id
           params[:engagement_time_msec] = ENGAGEMENT_TIME_MSEC
         end

data/lib/track_relay/version.rb

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

data/lib/track_relay.rb

@@ -12,6 +12,8 @@ require "track_relay/current"
 require "track_relay/client_id/ga"
 require "track_relay/client_id/ahoy_visitor"
 require "track_relay/client_id/session"
+require "track_relay/client_id/signed_token"
+require "track_relay/handshake_endpoint"
 require "track_relay/configuration"
 require "track_relay/instrumenter"
 require "track_relay/subscribers/base"
@@ -22,6 +24,7 @@ require "track_relay/subscribers/ahoy"
 require "track_relay/delivery_job"
 require "track_relay/dispatcher"
 require "track_relay/controller_tracking"
+require "track_relay/page_view_tracking"
 require "track_relay/job_tracking"
 require "track_relay/linter"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: track_relay
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - dchuk
@@ -193,6 +193,7 @@ files:
 - lib/track_relay/client_id/ahoy_visitor.rb
 - lib/track_relay/client_id/ga.rb
 - lib/track_relay/client_id/session.rb
+- lib/track_relay/client_id/signed_token.rb
 - lib/track_relay/configuration.rb
 - lib/track_relay/controller_tracking.rb
 - lib/track_relay/current.rb
@@ -203,10 +204,12 @@ files:
 - lib/track_relay/errors.rb
 - lib/track_relay/event_definition.rb
 - lib/track_relay/event_payload.rb
+- lib/track_relay/handshake_endpoint.rb
 - lib/track_relay/instrumenter.rb
 - lib/track_relay/job_tracking.rb
 - lib/track_relay/linter.rb
 - lib/track_relay/manifest.rb
+- lib/track_relay/page_view_tracking.rb
 - lib/track_relay/railtie.rb
 - lib/track_relay/subscribers/ahoy.rb
 - lib/track_relay/subscribers/base.rb