mbuzz 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81970794a962b276527d5aa05efb59703e1e3507598218c66f3eb3c238a96b6a
-  data.tar.gz: 391e3993a7aa60f3ad5fe50dfeff1394c9f3282538d3074de12f7a7a284d8e15
+  metadata.gz: 71d8b00de3facb7fd1290c03f1493edf09586333ad6ea44e1de03ebba375805f
+  data.tar.gz: 69eac0945b4b2630038753770fd398154cc1d407e15e9e8ff0d1770fb53bf95d
 SHA512:
-  metadata.gz: 2187c1959502e1dcc183e6f3fd2d77b46b90e87427bb79078c04cac35715891ec89cf274514cf8e8f327de2d8176e0d381875c961b9f61b37fee18f313c8ff9e
-  data.tar.gz: eb34d5989f34c7e83d5315c57000dff733af12a26494255817a414002d0448a1d8ee8f71143a94348f1b5118df743acf97cdeffd2347584e0cbe561b73b396e3
+  metadata.gz: 5f0a99184a1860342c7088c1642495d11db115ecbd7571bfffd6f29ea8fc770d6d0ea3d473f1ae7a6681eadb19d8b387ce86968df369d5e785301a1f157b2ad3
+  data.tar.gz: 3ba3d4419fa579e5840a46e398202637f4d7f5b119fbc2815b1cac5db1504f4d0f69a5d68481ad1075bb875d42e0121aa9f06696bf9cc9a254accb9c7a1a0aab

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.1] - 2026-09-17
+
+### Fixed — the visitor's IP now reaches mbuzz on session create
+
+- **`POST /api/v1/sessions` now carries `ip`.** The middleware already extracted the visitor's
+  address — it is half of `device_fingerprint = SHA256(ip|user_agent)` — and then dropped it at
+  three points on the way out: `Client.session` had no `ip:` keyword, `SessionRequest#payload`
+  omitted it, and `Middleware::Tracking`'s own call site omitted it too. Events and conversions have
+  always sent one; only sessions did not.
+- **Why it matters.** mbuzz sends Meta's Conversions API `client_ip_address`, which Meta documents
+  as **required** for website events, and a session with no address means the events resolved
+  through it carry none either. Upgrading improves Event Match Quality for anyone using conversion
+  feedback; it changes nothing else.
+- **No API change.** `ip:` is an optional keyword on `Client.session` and both middlewares fill it
+  automatically. Existing callers need no edit.
+
+Found by the SDK integration harness rather than by unit tests: every layer was correct on its own,
+and only a real request through a real app could tell the visitor's address from the app server's.
+
+## [0.10.0] - 2026-09-08
+
+### BREAKING — the page snippet is now required
+
+- **A page response no longer sets the visitor cookie.** Only `POST /_mbuzz/session` mints, and the inline snippet in the README's "Full-page caching" section is what calls it. **Upgrading without adding that snippet stops tracking entirely** — no cookie is ever minted, so no visitor exists and every event is dropped.
+
+### Fixed
+
+- **A cached page no longer hands every visitor the same id.** The page response carried a `Set-Cookie`, and a full-page cache stored it and replayed it to everyone — so unrelated people merged into a single journey. Corruption rather than loss: every row still exists, each attributed to the wrong person, and nothing looks missing. The page path now uses only the cookie the browser already holds; the uncached session endpoint is the sole place a visitor is minted.
+
+  Found by the cache harness at `sdk_integration_tests/scenarios/page_cache_test.rb`, and it could not have been found any other way: in isolation "reuse the cookie the browser presents" is correct — it is what lets a returning visitor keep their id. The bug exists only once a cache has handed one cookie to many people. The WordPress plugin reached the same conclusion first (`CookieBootstrap::CONTEXT_PAGE`).
+
 ## [0.9.0] - 2026-09-02
 
 ### Added

data/README.md

@@ -193,16 +193,22 @@ use Mbuzz::Middleware::Tracking
 run MyApp
 ```
 
-## Full-page caching
+## Full-page caching — the snippet below is REQUIRED
 
-If pages are served from a full-page cache (Cloudflare, Varnish, nginx, Rack::Cache, a CDN),
-the cache answers the request **without entering the Rack stack**, so the tracking middleware
-never runs, no visitor cookie is set, and every later event is dropped for having no one to
-attribute it to. The page renders perfectly and nothing is logged — the failure is silent.
+**Add this to your layout or nothing is tracked.** Since 0.10.0 a page response never sets the
+visitor cookie: only `POST /_mbuzz/session` mints, and the snippet is what calls it.
 
-`Mbuzz::Middleware::SessionEndpoint` fixes this. It answers `POST /_mbuzz/session`, a path
-caches don't store, and the **server** sets the cookie on that response. Rails mounts it for
-you; Rack and Sinatra apps add it ahead of `Tracking` as shown above.
+A page response can be stored by a full-page cache (Cloudflare, Varnish, nginx, Rack::Cache, a
+CDN) and replayed to every visitor. A `Set-Cookie` sitting in that cache hands everyone the
+*first* visitor's id, so unrelated people merge into one journey — corruption rather than loss,
+since every row exists and is simply attributed to the wrong person. Minting only on a response
+no cache stores is the only way to prevent it.
+
+The same endpoint solves the original problem too: a cached page never enters the Rack stack,
+so the tracking middleware cannot run — but this one request always reaches it.
+
+`Mbuzz::Middleware::SessionEndpoint` answers `POST /_mbuzz/session`. Rails mounts it for you;
+Rack and Sinatra apps add it ahead of `Tracking` as shown above.
 
 Then call it once per page, from your layout:
 

data/lib/mbuzz/client/session_request.rb

@@ -12,7 +12,8 @@ module Mbuzz
       # Response values
       ACCEPTED_STATUS = "accepted"
 
-      def initialize(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil, user_agent: nil, started_at: nil)
+      def initialize(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil,
+                     user_agent: nil, started_at: nil, ip: nil)
         @visitor_id = visitor_id
         @session_id = session_id
         @url = url
@@ -20,6 +21,7 @@ module Mbuzz
         @device_fingerprint = device_fingerprint
         @user_agent = user_agent
         @started_at = started_at
+        @ip = ip
       end
 
       def call
@@ -32,7 +34,8 @@ module Mbuzz
 
       private
 
-      attr_reader :visitor_id, :session_id, :url, :referrer, :device_fingerprint, :user_agent, :started_at
+      attr_reader :visitor_id, :session_id, :url, :referrer, :device_fingerprint, :user_agent,
+        :started_at, :ip
 
       def valid?
         present?(visitor_id) && present?(session_id) && present?(url)
@@ -42,6 +45,11 @@ module Mbuzz
         @response ||= Api.post_with_response(SESSIONS_PATH, { session: payload })
       end
 
+      # `ip` is the visitor's address, which the middleware already extracted to
+      # compute `device_fingerprint` (SHA256(ip|user_agent)). It was computed
+      # and then dropped here until 2026-09-17: mbuzz needs it for Meta's
+      # `client_ip_address`, which Meta documents as required for website
+      # events, and the events/conversions payloads have always carried it.
       def payload
         {
           visitor_id: visitor_id,
@@ -50,6 +58,7 @@ module Mbuzz
           referrer: referrer,
           device_fingerprint: device_fingerprint,
           user_agent: user_agent,
+          ip: ip,
           started_at: started_at || Time.now.utc.iso8601
         }.compact
       end

data/lib/mbuzz/client.rb

@@ -32,7 +32,8 @@ module Mbuzz
       ).call
     end
 
-    def self.session(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil, user_agent: nil, started_at: nil)
+    def self.session(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil,
+                     user_agent: nil, started_at: nil, ip: nil)
       SessionRequest.new(
         visitor_id: visitor_id,
         session_id: session_id,
@@ -40,7 +41,8 @@ module Mbuzz
         referrer: referrer,
         device_fingerprint: device_fingerprint,
         user_agent: user_agent,
-        started_at: started_at
+        started_at: started_at,
+        ip: ip
       ).call
     end
   end

data/lib/mbuzz/middleware/session_endpoint.rb

@@ -93,7 +93,8 @@ module Mbuzz
             url: context[:url],
             referrer: context[:referrer],
             device_fingerprint: context[:device_fingerprint],
-            user_agent: context[:user_agent]
+            user_agent: context[:user_agent],
+            ip: context[:ip]
           )
         rescue StandardError => e
           log_error("Session creation failed: #{e.message}") if Mbuzz.config.debug

data/lib/mbuzz/middleware/tracking.rb

@@ -15,6 +15,16 @@ module Mbuzz
         return @app.call(env) if skip_request?(env)
 
         request = Rack::Request.new(env)
+
+        # Only a visitor the browser already holds. This response may be stored
+        # by a full-page cache and replayed to everyone, so minting here would
+        # put a Set-Cookie in that cache and hand every later visitor the same
+        # id — unrelated people merged into one journey. Corruption, not loss:
+        # every row still exists, each attributed to the wrong person, and
+        # nothing looks missing. A first-time visitor is established a moment
+        # later by Middleware::SessionEndpoint, whose POST no cache stores.
+        return @app.call(env) unless visitor_id_from_cookie(request)
+
         context = build_request_context(request)
 
         env[ENV_VISITOR_ID_KEY] = context[:visitor_id]
@@ -26,9 +36,7 @@ module Mbuzz
         create_session_async(context, request) if should_create_session?(env)
 
         RequestContext.with_context(request: request) do
-          status, headers, body = @app.call(env)
-          set_visitor_cookie(headers, context, request)
-          [status, headers, body]
+          @app.call(env)
         ensure
           reset_current_attributes
         end
@@ -87,7 +95,7 @@ module Mbuzz
         user_agent = request.user_agent.to_s
 
         {
-          visitor_id: resolve_visitor_id(request),
+          visitor_id: visitor_id_from_cookie(request),
           session_id: SecureRandom.uuid,
           user_id: user_id_from_session(request),
           url: request.url,
@@ -98,10 +106,6 @@ module Mbuzz
         }.freeze
       end
 
-      def resolve_visitor_id(request)
-        visitor_id_from_cookie(request) || Visitor::Identifier.generate
-      end
-
       def visitor_id_from_cookie(request)
         request.cookies[VISITOR_COOKIE_NAME]
       end
@@ -129,7 +133,8 @@ module Mbuzz
           url: context[:url],
           referrer: context[:referrer],
           device_fingerprint: context[:device_fingerprint],
-          user_agent: context[:user_agent]
+          user_agent: context[:user_agent],
+          ip: context[:ip]
         )
       end
 
@@ -139,33 +144,6 @@ module Mbuzz
         Rails.logger.error("[Mbuzz] #{message}")
       end
 
-      # Cookie setting - visitor identity only (sessions are server-side)
-
-      def set_visitor_cookie(headers, context, request)
-        Rack::Utils.set_cookie_header!(
-          headers,
-          VISITOR_COOKIE_NAME,
-          visitor_cookie_options(context, request)
-        )
-      end
-
-      def visitor_cookie_options(context, request)
-        base_cookie_options(request).merge(
-          value: context[:visitor_id],
-          max_age: VISITOR_COOKIE_MAX_AGE
-        )
-      end
-
-      def base_cookie_options(request)
-        options = {
-          path: VISITOR_COOKIE_PATH,
-          httponly: true,
-          same_site: VISITOR_COOKIE_SAME_SITE
-        }
-        options[:secure] = true if request.ssl?
-        options
-      end
-
       # Store context in CurrentAttributes for background job propagation
       def store_in_current_attributes(context, request)
         return unless defined?(Mbuzz::Current)

data/lib/mbuzz/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mbuzz
-  VERSION = "0.9.0"
+  VERSION = "0.10.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mbuzz
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.1
 platform: ruby
 authors:
 - mbuzz team