track_relay 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaa3f984be840d9f657d23e543aae04eccac6c45da4877fcdaad30e8f3dc7f7a
-  data.tar.gz: ed659de0a4cd9e7a63d50d8d6ddeb32c962c667471e4c9b56f143fcf16f0b26b
+  metadata.gz: 4d71fbb5a7101c3f407ba9fc7c05bf032a5718447a7cacd341647b9b794c47b2
+  data.tar.gz: b36598739beda0519f71b98cf906159b3857234dd9510d7aff35d1f33ecd9808
 SHA512:
-  metadata.gz: 19dd615e0a99f54df3bedaf1eb01b61ace7a338fa04d4d77373cbb43b9e786e221ade99ea3fd52e13b82a64be705a5ec2674bdc3fb69223d84e2b25157da272b
-  data.tar.gz: eabf9d5db4cb4da4643815b628cc7c065b6b93b4f4ad8345b2d4525a93c6ea982f7877db25fae2df294bef512a222cdfb3b25966988bd5f13f9e54ad58b70646
+  metadata.gz: f71946bad98b203c57850991846de8e3fb95828bc825f5d9ccb2d6b5a205d6531253087a65e77c0e4eb4981f5e95129439ecf081fc719939618daeb93b611ca0
+  data.tar.gz: 1b05f9d685e43a6c97e37f306aa6f0a970f1b7fe6ccb774a037a4a26043295d7464a22ec2d821425aad6eb9ac6e1e07461420f7fc8ce6875f3bec1919e3d95e1

data/CHANGELOG.md

@@ -7,6 +7,26 @@ 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

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.3.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.3.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