mbuzz 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03aa54a68ab1b6e6313d69c910c88aec7241e19d65b72b9cee37a6e187454692
-  data.tar.gz: 3ddce95a2f8795635278785f403daf6a41e15bc31fc01c3990989c20911ebc21
+  metadata.gz: ff302e119aa981ced654677a020929b3b2065055961e253b08e106b52750fed4
+  data.tar.gz: ed21ef016dcbac2bb9918a07f03efcce264b9f01046a1ada510e526a107c7ed1
 SHA512:
-  metadata.gz: 4ba8606ecbeec460a9145937b8d123c93c455476d92795e9ddf2b291082e57cdce4818cd709a427ed28d125e0ee6766110f0425039c43bfba75328f5da6f756f
-  data.tar.gz: 8d9233587278aaccb19fd5f124e486e1385b626b2eb4db3d7125ab0e64d6b1500117a33fe89e1fad84c846e6a292e6183760013ecb33e16d44082036d2c5a299
+  metadata.gz: 6f9e1ff36c152c2eaa085892b41f7e18e995f7de122413d6d42cc4d44d2199f6e8fa3096ce2e06be4b87a6b2a8daaebcaf80d037e11e85df9298d9b3a33f7e27
+  data.tar.gz: 1a18bdf46411b450c247396d595e094404d6b8f7ef487560c8af697c65317f2f6efcf1969a0a86b3a9b349a95f89fd0dce5b546a4d9d5307dd99cf0a3b9d3f85

data/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.11.0] - 2026-10-14
+
+### Added
+
+- **Meta's `_fbp` is forwarded on the session call.** The SDK reads the `_fbp` cookie the customer's
+  Meta Pixel already set and sends it as `fbp` on the session payload, on both paths (the session
+  endpoint and the tracking middleware). Meta merges a server event with the browser Pixel's event on
+  `event_name` + `fbp` when the event IDs differ, so without it every server `Lead` counted as a
+  second one. Accepts Meta's `fb.<n>.<ts>.<random>` and the optional appendix its server-side
+  Parameter Builder adds (`...AQECAQIB`); anything else is dropped. Never written, never invented.
+  The key is omitted, not null, when the cookie is absent or malformed. No install change needed.
+
+### Fixed
+
+- **A session call made outside Rack/Rails failed silently.** `SessionRequest` called
+  `Time#iso8601` without `require "time"`; Rack and Rails load it, a plain script did not, and the
+  `NoMethodError` was rescued to `false`.
+
+## [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

data/lib/mbuzz/client/session_request.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Time#iso8601 lives here, not in core. Rack and Rails load it; a plain script
+# did not, and the session call then failed silently (rescued to false).
+require "time"
+
 module Mbuzz
   class Client
     class SessionRequest
@@ -12,7 +16,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, fbp: nil)
         @visitor_id = visitor_id
         @session_id = session_id
         @url = url
@@ -20,6 +25,8 @@ module Mbuzz
         @device_fingerprint = device_fingerprint
         @user_agent = user_agent
         @started_at = started_at
+        @ip = ip
+        @fbp = fbp
       end
 
       def call
@@ -32,7 +39,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, :fbp
 
       def valid?
         present?(visitor_id) && present?(session_id) && present?(url)
@@ -42,6 +50,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 +63,10 @@ module Mbuzz
           referrer: referrer,
           device_fingerprint: device_fingerprint,
           user_agent: user_agent,
+          ip: ip,
+          # Meta's browser id, already format-checked by Mbuzz::Fbp. Dropped by
+          # .compact when absent: omitted, not null.
+          fbp: fbp,
           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, fbp: nil)
       SessionRequest.new(
         visitor_id: visitor_id,
         session_id: session_id,
@@ -40,7 +41,9 @@ module Mbuzz
         referrer: referrer,
         device_fingerprint: device_fingerprint,
         user_agent: user_agent,
-        started_at: started_at
+        started_at: started_at,
+        ip: ip,
+        fbp: fbp
       ).call
     end
   end

data/lib/mbuzz/fbp.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  # Meta's browser id, written client-side by the customer's Meta Pixel. Read
+  # only, never set: forwarded on the session call so Meta can merge mbuzz's
+  # server event with the Pixel's browser event.
+  module Fbp
+    # Meta's documented shape, fb.<subdomainIndex>.<creationTime>.<random>, plus
+    # the optional appendix Meta's server-side Parameter Builder adds
+    # (fb.1.<ts>.<random>.AQECAQIB). Both are valid to Meta. \A…\z, not ^…$:
+    # `$` matches before a trailing newline.
+    FORMAT = /\Afb\.\d+\.\d+\.\d+(?:\.[A-Za-z0-9_-]+)?\z/
+
+    # The Pixel's _fbp, or nil when absent or not in Meta's format. mbuzz never
+    # invents one and never rewrites what it forwards.
+    def self.read(value)
+      value if value.is_a?(String) && FORMAT.match?(value)
+    end
+  end
+end

data/lib/mbuzz/middleware/session_endpoint.rb

@@ -67,6 +67,7 @@ module Mbuzz
           referrer: payload["referrer"],
           ip: ip,
           user_agent: user_agent,
+          fbp: Fbp.read(request.cookies[FBP_COOKIE_NAME]),
           device_fingerprint: Digest::SHA256.hexdigest("#{ip}|#{user_agent}")[0, 32]
         }.freeze
       end
@@ -93,7 +94,9 @@ 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],
+            fbp: context[:fbp]
           )
         rescue StandardError => e
           log_error("Session creation failed: #{e.message}") if Mbuzz.config.debug

data/lib/mbuzz/middleware/tracking.rb

@@ -102,6 +102,7 @@ module Mbuzz
           referrer: request.referer,
           ip: ip,
           user_agent: user_agent,
+          fbp: Fbp.read(request.cookies[FBP_COOKIE_NAME]),
           device_fingerprint: Digest::SHA256.hexdigest("#{ip}|#{user_agent}")[0, 32]
         }.freeze
       end
@@ -133,7 +134,9 @@ 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],
+          fbp: context[:fbp]
         )
       end
 

data/lib/mbuzz/version.rb

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

data/lib/mbuzz.rb

@@ -4,6 +4,7 @@ require_relative "mbuzz/version"
 require_relative "mbuzz/configuration"
 require_relative "mbuzz/dropped_call"
 require_relative "mbuzz/visitor/identifier"
+require_relative "mbuzz/fbp"
 require_relative "mbuzz/request_context"
 require_relative "mbuzz/api"
 require_relative "mbuzz/client"
@@ -29,6 +30,9 @@ module Mbuzz
   VISITOR_COOKIE_PATH = "/"
   VISITOR_COOKIE_SAME_SITE = "Lax"
 
+  # Meta Pixel's browser id. Read only; see Mbuzz::Fbp.
+  FBP_COOKIE_NAME = "_fbp"
+
   # The one request a cached page always sends to the app. Kept off /api and
   # /assets so host-app routing and cache rules don't shadow it.
   SESSION_ENDPOINT_PATH = "/_mbuzz/session"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mbuzz
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - mbuzz team
@@ -47,6 +47,7 @@ files:
 - lib/mbuzz/controller_helpers.rb
 - lib/mbuzz/current.rb
 - lib/mbuzz/dropped_call.rb
+- lib/mbuzz/fbp.rb
 - lib/mbuzz/middleware/session_endpoint.rb
 - lib/mbuzz/middleware/tracking.rb
 - lib/mbuzz/railtie.rb