track_relay 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ef792bdf08a7044b2505ba7d864b6efd9e52300227bd90ba6d4556833ea4317
-  data.tar.gz: d5fa187c552b77560ccb373546702ae563b692708ac0e3aebee4b8ee96d9a90f
+  metadata.gz: 918577fceae3974911227a1b988f8d17ecf636c086b7f91ad9b8e36ac6d2b9fd
+  data.tar.gz: 1dcd1c4f9bb900b0b3945a40ae0222b3205212f52477e10640baa0facc39ae40
 SHA512:
-  metadata.gz: d092e315a251dd34b3d29f2b61042dd6b05deadd4bd1b99cad515b28502bdb049bc4009ca2e71a3b6c3375791dc37a81e93c451ad90756d0e846142525d2fa84
-  data.tar.gz: d9c406cdda1cf1517fc568b6f0589ce3d3655c0402c33151cc520fe2f2f054f242f4e35cd3d98b9f911919bb25da3be6dca07f80a192f084d404bab20c56542b
+  metadata.gz: c95d0181afcad7811afaff649155f78681f41a2d54fc3f3ebaf1057f56e4b146d5704a6954e83183d9ef78269a807b648545cc493b42e22c9b93dd53084c9fd2
+  data.tar.gz: 9d0c93c207fbdfa07237d9f25657053626711ac0eedf576fd0bb36db84203b67e716bd0f382face10074cbacb4a24842a7e56ac1c7b7adc82ac59aed66036fd3

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-07-07
+
+### Added
+- `config.ga4_require_browser_client_id` (default `false`) — browser-proof
+  delivery gate for `Subscribers::Ga4MeasurementProtocol`. When enabled,
+  events are delivered only when the current request carries a genuine
+  `_ga` cookie (set by gtag JS, which bots don't execute). No cookie — or a
+  malformed one with fewer than four dot-segments — enqueues no
+  `DeliveryJob` at all; the random per-event client_id fallback never
+  fires. The cookie-derived client_id rides in the delivered payload's
+  context.
+- `config.ga4_enrich_page_context` (default `false`) — notification-time
+  page/session enrichment for GA4 MP events: `page_location` (request
+  URL), `page_referrer` (when a referer exists), and `session_id` +
+  `engagement_time_msec` (nominal 100) when the gtag `_ga_<stream>`
+  session cookie is parseable. Captured while the request is in scope and
+  serialized through the payload, so async deliveries carry it. Without
+  these params GA4 files server-side events under a blank page path.
+- `config.track_gate` (default `nil`) — host-level fan-out gate. An
+  optional callable receiving `payload:` and `request:` keywords,
+  evaluated once per `TrackRelay.track` call before the event notification
+  fires; a falsy return drops the event for every subscriber. Enables
+  e.g. "only track requests that prove a real browser" across Ahoy, GA4,
+  and Logger at once.
+- `Subscribers::Base#prepare(payload)` — public notification-time hook
+  (filter → prepare → sync/async) for subclasses to gate delivery
+  (return `nil`) or swap in an enriched copy of the payload while the
+  request is still in scope.
+- `ClientId::Ga.parse` / `ClientId::Ga.from_request` — the `_ga` parse
+  rule as reusable class methods (the resolver-chain `#call` now
+  delegates to them).
+
+### Changed
+- All new options default off: an unconfigured upgrade is byte-identical
+  to 1.0.0 (the pre-existing test suite passes unmodified).
+
 ## [1.0.0] - 2026-05-07
 
 ### Added
@@ -141,6 +177,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Privacy: untyped JSONL captures param NAMES only (never VALUES) to avoid leaking PII.
 - Naming: `track_relay` availability on RubyGems will be re-validated before 1.0.
 
+[1.1.0]: https://github.com/dchuk/track_relay/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/dchuk/track_relay/compare/v0.3.0...v1.0.0
 [0.3.0]: https://github.com/dchuk/track_relay/releases/tag/v0.3.0
 [0.2.0]: https://github.com/dchuk/track_relay/releases/tag/v0.2.0

data/README.md

@@ -334,6 +334,46 @@ TrackRelay.subscribe(
 )
 ```
 
+### Browser-proof gating + page context (opt-in)
+
+Server-side GA4 events have two chronic problems: bots with browser user agents inflate user counts (the Measurement Protocol accepts any client_id, and the subscriber's fallback mints a random one per event), and events land under a blank page path because nothing sends `page_location`. Two opt-in flags fix both:
+
+```ruby
+TrackRelay.configure do |c|
+  # Deliver ONLY when the current request carries a genuine `_ga`
+  # cookie — set by gtag JS, which bots don't execute. No cookie (or a
+  # malformed one) means no DeliveryJob is enqueued at all; the random
+  # client_id fallback never fires. The cookie-derived client_id is
+  # used for the delivery.
+  c.ga4_require_browser_client_id = true
+
+  # Capture page context from the request at notification time and
+  # send it with every GA4 event: `page_location` (request URL),
+  # `page_referrer` (when a referer exists), and `session_id` +
+  # `engagement_time_msec` when the gtag `_ga_<stream>` session cookie
+  # is present.
+  c.ga4_enrich_page_context = true
+end
+```
+
+Both run inside the subscriber's notification-time `prepare` hook — the request is still in scope there, and the captured values ride through the serialized payload to the async `DeliveryJob`. Other subscribers always receive the original, unmodified payload.
+
+### Host-level track gate (opt-in)
+
+`config.track_gate` is evaluated once per `TrackRelay.track` call, before the event fans out to **any** subscriber. A falsy return drops the event everywhere (Ahoy, GA4, Logger, …). It receives `payload:` and `request:` keywords:
+
+```ruby
+TrackRelay.configure do |c|
+  # Only track requests that prove a real browser — aligns first-party
+  # analytics (e.g. Ahoy) with what GA4 sees under the browser gate.
+  c.track_gate = ->(payload:, request:) {
+    TrackRelay::ClientId::Ga.from_request(request)
+  }
+end
+```
+
+Unset (`nil`, the default) disables the gate entirely.
+
 ### `client_id` resolver chain
 
 `TrackRelay::Current.client_id` is resolved via a configurable chain of `client_id_resolvers`. The default chain checks the GA `_ga` cookie, then any Ahoy visitor token, then mints a session-stable UUID into `session[:track_relay_client_id]` so visitors without a `_ga` cookie still get a stable identifier. First non-nil wins; per-resolver exceptions are isolated so a single buggy resolver cannot block the chain.

data/lib/track_relay/client_id/ga.rb

@@ -28,6 +28,35 @@ module TrackRelay
     # and yield `nil` (callers should fall through to the next resolver
     # in the chain).
     class Ga
+      # Parse a raw `_ga` cookie value into a GA4 client_id.
+      #
+      # This is THE canonical `_ga` parse rule — the resolver chain
+      # ({#call}) and the browser-proof delivery gate
+      # ({Subscribers::Ga4MeasurementProtocol#prepare}) both delegate
+      # here so the "fewer than four segments = malformed = nil"
+      # posture is defined exactly once.
+      #
+      # @param cookie_value [String, nil] raw `_ga` cookie value
+      # @return [String, nil] the parsed GA4 client_id, or `nil` when
+      #   the value is missing/empty/malformed.
+      def self.parse(cookie_value)
+        return nil if cookie_value.nil? || cookie_value.empty?
+
+        parts = cookie_value.split(".")
+        return nil if parts.size < 4
+
+        "#{parts[-2]}.#{parts[-1]}"
+      end
+
+      # Extract and parse the `_ga` cookie from a request-like object.
+      #
+      # @param request [#cookies, nil] any object exposing
+      #   `request.cookies["_ga"]` (e.g. an `ActionDispatch::Request`).
+      # @return [String, nil]
+      def self.from_request(request)
+        parse(request&.cookies&.[]("_ga"))
+      end
+
       # @param controller [#request] any object exposing
       #   `controller.request.cookies["_ga"]`. Typically an
       #   `ActionController::Base` instance from
@@ -35,13 +64,7 @@ module TrackRelay
       # @return [String, nil] the parsed GA4 client_id, or `nil` when the
       #   cookie is missing/empty/malformed.
       def call(controller:, **)
-        ga_cookie = controller&.request&.cookies&.[]("_ga")
-        return nil if ga_cookie.nil? || ga_cookie.empty?
-
-        parts = ga_cookie.split(".")
-        return nil if parts.size < 4
-
-        "#{parts[-2]}.#{parts[-1]}"
+        self.class.from_request(controller&.request)
       end
     end
   end

data/lib/track_relay/configuration.rb

@@ -50,6 +50,30 @@ module TrackRelay
     #   When `true`, the GA4 subscriber posts to
     #   `https://region1.google-analytics.com/mp/collect` instead of
     #   the global endpoint. Defaults to `false`.
+    # @!attribute [rw] ga4_require_browser_client_id
+    #   When `true`, the GA4 subscriber delivers ONLY when the current
+    #   request carries a genuine `_ga` cookie (set by gtag JS, which
+    #   bots don't execute). No cookie — or a malformed one — means no
+    #   DeliveryJob is enqueued at all; the random client_id fallback
+    #   never fires. The cookie-derived client_id is merged into the
+    #   delivered payload's context. Defaults to `false` (deliver
+    #   everything, as before).
+    # @!attribute [rw] ga4_enrich_page_context
+    #   When `true`, the GA4 subscriber captures page context from the
+    #   current request at notification time and merges it into the
+    #   delivered event's params: `page_location` (request URL),
+    #   `page_referrer` (when a referer exists), and — when the gtag
+    #   session cookie `_ga_<stream>` is parseable — `session_id` plus
+    #   a nominal `engagement_time_msec`. Without these GA4 files
+    #   server-side events under a blank page path. Defaults to
+    #   `false`.
+    # @!attribute [rw] track_gate
+    #   Optional callable evaluated once per {TrackRelay.track} call,
+    #   BEFORE the event notification fans out to any subscriber.
+    #   Receives `payload:` (the built {EventPayload}) and `request:`
+    #   ({Current.request}, possibly `nil`) keywords; a falsy return
+    #   drops the event for every subscriber. `nil` (the default)
+    #   disables the gate entirely — current behavior.
     attr_accessor :swallow_subscriber_errors,
       :untyped_log_path,
       :untyped_events_allowed,
@@ -58,7 +82,10 @@ module TrackRelay
       :client_id_resolvers,
       :ga4_measurement_id,
       :ga4_api_secret,
-      :ga4_use_eu_endpoint
+      :ga4_use_eu_endpoint,
+      :ga4_require_browser_client_id,
+      :ga4_enrich_page_context,
+      :track_gate
 
     # @return [Array] registered subscriber instances, in insertion order
     attr_reader :subscribers
@@ -82,6 +109,9 @@ module TrackRelay
       @ga4_measurement_id = nil
       @ga4_api_secret = nil
       @ga4_use_eu_endpoint = false
+      @ga4_require_browser_client_id = false
+      @ga4_enrich_page_context = false
+      @track_gate = nil
     end
 
     # Append a subscriber to the registry.

data/lib/track_relay/instrumenter.rb

@@ -82,6 +82,7 @@ module TrackRelay
           extra_context: direct_context
         )
         return unless validate(payload)
+        return unless track_gate_allows?(payload)
         ActiveSupport::Notifications.instrument(NOTIFICATION, event: payload)
       end
     end
@@ -215,6 +216,21 @@ module TrackRelay
       }
     end
 
+    # Evaluate {Configuration#track_gate} once per track call, inside
+    # the `Current.set` scope so the gate sees the same request the
+    # subscribers would. Runs AFTER validation and BEFORE the
+    # notification fans out — a falsy return means no subscriber ever
+    # sees the event. Unset gate (`nil`) always allows.
+    #
+    # @param payload [EventPayload]
+    # @return [Boolean]
+    def track_gate_allows?(payload)
+      gate = TrackRelay.config.track_gate
+      return true if gate.nil?
+
+      !!gate.call(payload: payload, request: Current.request)
+    end
+
     # Run {EventPayload#validate!} and apply the
     # {Configuration#raise_on_validation_error} gate.
     #

data/lib/track_relay/subscribers/base.rb

@@ -109,6 +109,9 @@ module TrackRelay
       def handle(payload)
         return nil if filtered?(payload.name.to_sym)
 
+        payload = prepare(payload)
+        return nil if payload.nil?
+
         if self.class.synchronous || TrackRelay.config.force_synchronous
           safe_deliver(payload)
         else
@@ -117,6 +120,23 @@ module TrackRelay
         end
       end
 
+      # Notification-time hook, called by {#handle} after the event-name
+      # filter and BEFORE the sync/async branch — i.e. while the request
+      # ({Current.request}) is still in scope, which is gone by the time
+      # an async {DeliveryJob} runs.
+      #
+      # Subclasses override this to gate delivery (return `nil` to drop
+      # the event silently — no job, no `deliver`) or to swap in an
+      # enriched **copy** of the payload. The same payload object fans
+      # out to every subscriber, so implementations must never mutate
+      # `payload` — build a new {EventPayload} instead.
+      #
+      # @param payload [EventPayload]
+      # @return [EventPayload, nil] the payload to deliver, or `nil` to drop
+      def prepare(payload)
+        payload
+      end
+
       # Wrap {#deliver} with the per-subscriber rescue.
       #
       # Returns `nil` on success or the StandardError on failure. ALWAYS

data/lib/track_relay/subscribers/ga4_measurement_protocol.rb

@@ -35,6 +35,12 @@ module TrackRelay
     #   - `config.ga4_api_secret`     — per-stream MP secret
     #   - `config.ga4_use_eu_endpoint` — when `true`, post to
     #     `https://region1.google-analytics.com/mp/collect`
+    #   - `config.ga4_require_browser_client_id` — when `true`, deliver
+    #     only for requests carrying a genuine `_ga` cookie (see
+    #     {#prepare})
+    #   - `config.ga4_enrich_page_context` — when `true`, merge
+    #     `page_location` / `page_referrer` / `session_id` /
+    #     `engagement_time_msec` into delivered params (see {#prepare})
     #
     # When `ga4_measurement_id` or `ga4_api_secret` is `nil`, `#deliver`
     # emits a single `Rails.logger.warn` and returns without raising —
@@ -85,6 +91,46 @@ module TrackRelay
       # drops them.
       RESERVED_PARAM_PREFIXES = %w[firebase_ ga_ google_].freeze
 
+      # Nominal engagement time attached alongside `session_id` when
+      # page-context enrichment finds a gtag session cookie. GA4 needs
+      # a nonzero value for server events to count toward session
+      # activity; the number itself is nominal (Google's Measurement
+      # Protocol examples use 100).
+      ENGAGEMENT_TIME_MSEC = 100
+
+      # Browser-proof gate + page-context enrichment (issue #1), both
+      # opt-in via configuration. Runs at notification time —
+      # {Current.request} is gone by the time an async {DeliveryJob}
+      # performs, so gating and enrichment MUST happen here and ride
+      # through the serialized payload.
+      #
+      # - `config.ga4_require_browser_client_id`: deliver only when the
+      #   current request carries a genuine `_ga` cookie; the
+      #   cookie-derived client_id lands in the delivered context.
+      # - `config.ga4_enrich_page_context`: merge `page_location`,
+      #   conditional `page_referrer`, and conditional `session_id` /
+      #   `engagement_time_msec` into the delivered params.
+      #
+      # Either path swaps in a **copy** — the shared payload other
+      # subscribers receive during fan-out is never mutated.
+      #
+      # @param payload [EventPayload]
+      # @return [EventPayload, nil] `nil` drops the event (no job)
+      def prepare(payload)
+        config = TrackRelay.config
+        return payload unless config.ga4_require_browser_client_id || config.ga4_enrich_page_context
+
+        request = Current.request
+        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[:context] = hash[:context].merge(client_id: client_id) if client_id
+        EventPayload.from_h(hash)
+      end
+
       # POST `payload` to the GA4 Measurement Protocol endpoint.
       #
       # See class docs for the full configuration / error contract.
@@ -112,6 +158,37 @@ module TrackRelay
 
       private
 
+      # Page-context params captured from the live request (only when
+      # `config.ga4_enrich_page_context` is enabled).
+      def page_params(request)
+        params = {page_location: request.original_url}
+        params[:page_referrer] = request.referer if request.referer && !request.referer.empty?
+
+        if (session_id = ga_session_id(request))
+          params[:session_id] = session_id
+          params[:engagement_time_msec] = ENGAGEMENT_TIME_MSEC
+        end
+        params
+      end
+
+      # The gtag session cookie is `_ga_<stream>` (measurement id minus
+      # the "G-" prefix), shaped `GS1.1.<session_id>.<session_number>...`.
+      # The format is Google-controlled, so parse defensively — too few
+      # segments or a blank session segment yields nil and the delivery
+      # proceeds without session params.
+      def ga_session_id(request)
+        stream = TrackRelay.config.ga4_measurement_id.to_s.delete_prefix("G-")
+        return nil if stream.empty?
+
+        cookie = request.cookies["_ga_#{stream}"]
+        return nil if cookie.nil? || cookie.empty?
+
+        parts = cookie.split(".")
+        return nil if parts.size < 4 || parts[2].nil? || parts[2].empty?
+
+        parts[2]
+      end
+
       # Run call-time payload constraint checks (REQ-27 split). Returns
       # `true` when delivery should proceed, `false` when a constraint
       # was violated AND `raise_on_validation_error` is `false` (the

data/lib/track_relay/version.rb

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

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: track_relay
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
-- Darrin Demchuk
+- dchuk
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z