track_relay 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ef792bdf08a7044b2505ba7d864b6efd9e52300227bd90ba6d4556833ea4317
-  data.tar.gz: d5fa187c552b77560ccb373546702ae563b692708ac0e3aebee4b8ee96d9a90f
+  metadata.gz: aaa3f984be840d9f657d23e543aae04eccac6c45da4877fcdaad30e8f3dc7f7a
+  data.tar.gz: ed659de0a4cd9e7a63d50d8d6ddeb32c962c667471e4c9b56f143fcf16f0b26b
 SHA512:
-  metadata.gz: d092e315a251dd34b3d29f2b61042dd6b05deadd4bd1b99cad515b28502bdb049bc4009ca2e71a3b6c3375791dc37a81e93c451ad90756d0e846142525d2fa84
-  data.tar.gz: d9c406cdda1cf1517fc568b6f0589ce3d3655c0402c33151cc520fe2f2f054f242f4e35cd3d98b9f911919bb25da3be6dca07f80a192f084d404bab20c56542b
+  metadata.gz: 19dd615e0a99f54df3bedaf1eb01b61ace7a338fa04d4d77373cbb43b9e786e221ade99ea3fd52e13b82a64be705a5ec2674bdc3fb69223d84e2b25157da272b
+  data.tar.gz: eabf9d5db4cb4da4643815b628cc7c065b6b93b4f4ad8345b2d4525a93c6ea982f7877db25fae2df294bef512a222cdfb3b25966988bd5f13f9e54ad58b70646

data/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- `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 +204,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/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

@@ -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,12 @@ 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,
+      :signed_client_token_secret,
+      :signed_client_token_ttl
 
     # @return [Array] registered subscriber instances, in insertion order
     attr_reader :subscribers
@@ -82,6 +111,11 @@ 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
+      @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/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,47 @@ 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
+        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, token)) 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 +159,49 @@ 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, token = nil)
+        params = {page_location: request.original_url}
+        params[:page_referrer] = request.referer if request.referer && !request.referer.empty?
+
+        if (session_id = token&.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.2.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"

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: track_relay
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
-- Darrin Demchuk
+- dchuk
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -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,6 +204,7 @@ 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