track_relay 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaa3f984be840d9f657d23e543aae04eccac6c45da4877fcdaad30e8f3dc7f7a
-  data.tar.gz: ed659de0a4cd9e7a63d50d8d6ddeb32c962c667471e4c9b56f143fcf16f0b26b
+  metadata.gz: d7fca8b3efc2716f3ba667aecdadd66bf58f2cbbd18a76f28dd04784a521ffdf
+  data.tar.gz: 01103c51038bf8fbefd95e63b513223ea93407e6583f4925ed3756805209a670
 SHA512:
-  metadata.gz: 19dd615e0a99f54df3bedaf1eb01b61ace7a338fa04d4d77373cbb43b9e786e221ade99ea3fd52e13b82a64be705a5ec2674bdc3fb69223d84e2b25157da272b
-  data.tar.gz: eabf9d5db4cb4da4643815b628cc7c065b6b93b4f4ad8345b2d4525a93c6ea982f7877db25fae2df294bef512a222cdfb3b25966988bd5f13f9e54ad58b70646
+  metadata.gz: a36d9e2d83ea2215798bc5ed963b0e618aa29436c83ad6e0d72ee0f46472435300fcfe0ae4fb9eecc29e491c25ca258e5f7cc6b85110f17f959cd6e9af3c4cc1
+  data.tar.gz: 0b855b5604793c877501ee2892a1f0d374384b257391b27f5cc1f453f8064a885acb5b874b5df8de97340dab64deb4ac808c625d749ed3961f8d213db8afc68d

data/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-07-31
+
+### Added
+- `config.manifest_path` — hosts can relocate the generated event-schema
+  manifest outside the public web root (the on-disk catalog discloses
+  internal event names/params when served world-readable). Defaults to
+  `nil`, preserving the existing `public/track_relay_catalog.json`
+  behavior. The `track_relay:manifest` rake task, the development
+  catalog hot-reload regeneration, and the `assets:precompile` chaining
+  all honor it, since every default-path write flows through
+  `TrackRelay::Manifest.write!`.
+
+## [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

data/lib/tasks/track_relay.rake

@@ -64,7 +64,7 @@ namespace :track_relay do
     exit(clean ? 0 : 1)
   end
 
-  desc "Generate public/track_relay_catalog.json from the loaded catalog"
+  desc "Generate the catalog manifest (config.manifest_path, default public/track_relay_catalog.json)"
   task manifest: :environment do
     # Footgun guard (RISK-04): an empty manifest tells the JS client
     # "no schema, accept everything" — silently. Abort loudly so the

data/lib/track_relay/configuration.rb

@@ -87,7 +87,8 @@ module TrackRelay
       :ga4_enrich_page_context,
       :track_gate,
       :signed_client_token_secret,
-      :signed_client_token_ttl
+      :signed_client_token_ttl,
+      :manifest_path
 
     # @return [Array] registered subscriber instances, in insertion order
     attr_reader :subscribers
@@ -116,6 +117,7 @@ module TrackRelay
       @track_gate = nil
       @signed_client_token_secret = nil
       @signed_client_token_ttl = 30.days
+      @manifest_path = nil
     end
 
     # Append a subscriber to the registry.

data/lib/track_relay/manifest.rb

@@ -74,6 +74,15 @@ module TrackRelay
       private
 
       def default_path
+        # `config.manifest_path` lets hosts keep the event schema out of
+        # the public web root; the rake task, dev reload, and
+        # assets:precompile chaining all resolve through here. The
+        # respond_to? guard keeps this file loadable standalone (the
+        # rake file require_relative's it without the umbrella require).
+        if TrackRelay.respond_to?(:config) && (configured = TrackRelay.config.manifest_path)
+          return configured
+        end
+
         unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
           raise ArgumentError,
             "TrackRelay::Manifest.write! requires a `path:` argument when Rails.root is unavailable"

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/version.rb

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

data/lib/track_relay.rb

@@ -24,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.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - dchuk
@@ -209,6 +209,7 @@ files:
 - 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