mbuzz 0.6.7 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28da4faa3b1b26c01e8a1762b5c9f24352d656304eb7802c71e0e00057171702
-  data.tar.gz: 126f8ddaf74ffb112c0e6e09efa63019563c37edf551b4493676f2977d5ce025
+  metadata.gz: 0fa7c025330829c88ab9a75a22ca286d14adc1df7872295c5519df4c89536db9
+  data.tar.gz: 62d6675e5ffe9504e2262f84551c286366acc2ad42b6ca6d224367902d9ec3fb
 SHA512:
-  metadata.gz: 574d624c96d1a50c87ca31d4f3528676826cd6f0d5b37956858825d0338fd60468d87ff72a0791de167a5f18f5644148ef45f74f52ae9c2945765ad7d5c3c9ff
-  data.tar.gz: 7139e7f2911fee98640f181f868213f739e4104fd76708082fdc26d27ac679fd56859573a034d9883ba27d069c4569159cabcadcc1900c15c7140f1a5f0da3f8
+  metadata.gz: eb90968b0d4c17bdc7c5019fa0058c257233bc00e1921f0b70a3dbf885fd8aecd1f9d80ab125d31ab535be5e55a44ecc2e0d46e9cb9c51fef4b9305634241b2f
+  data.tar.gz: cef7cbbc7817a6d7c4eca635594ac9e3b9661d81b33cc7d956376cb9fd763a6d216651e6ec499146e31dca042f024216f3c85c08c6d83f4f31dfb1fff64e8b56

data/CHANGELOG.md

@@ -5,6 +5,54 @@ 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.7.0] - 2026-01-09
+
+### Breaking Changes
+
+- **Session cookie removed** - SDK no longer sets or reads `_mbuzz_sid` cookie
+- **Session ID generation removed** - Server handles all session resolution
+- **`Mbuzz.session_id` removed** - Use server-side session resolution instead
+- **`Mbuzz::Client.session()` removed** - Sessions are created server-side
+- **`session_id` parameter removed from `Client.track()`** - Not needed with server-side resolution
+
+### Added
+
+- **Cross-device identity resolution** - New `identifier` parameter for linking sessions across devices
+  - `Mbuzz.event("page_view", identifier: { email: "user@example.com" })`
+  - `Mbuzz.conversion("purchase", identifier: { email: "user@example.com" })`
+- **Conversion fingerprint fallback** - `ip` and `user_agent` parameters on `Client.conversion()`
+  - When visitor_id is not found, server can find visitor via recent session with same fingerprint
+
+### Changed
+
+- **Simplified middleware** - Only manages visitor cookie (`_mbuzz_vid`), no session handling
+- **Server-side session resolution** - All session creation and resolution happens on the API server
+  - Enables true 30-minute sliding windows (vs fixed time buckets)
+  - Eliminates duplicate visitor problem from concurrent Turbo/Hotwire requests
+  - Better cross-device tracking with identity resolution
+
+### Migration Guide
+
+1. Remove any code that reads `Mbuzz.session_id` or `_mbuzz_sid` cookie
+2. Remove any calls to `Mbuzz::Client.session()`
+3. Ensure `ip` and `user_agent` are passed to track/conversion calls (handled automatically if using middleware)
+4. Optionally add `identifier` parameter for cross-device tracking
+
+## [0.6.8] - 2025-12-30
+
+### Added
+
+- **Server-side session resolution support** - SDK now forwards `ip` and `user_agent` to the API for server-side session identification
+- `ip` and `user_agent` parameters on `Mbuzz::Client.track()`
+- `RequestContext#ip` method with proxy header support (X-Forwarded-For, X-Real-IP)
+- `Mbuzz.event` automatically extracts and forwards ip/user_agent from request context
+
+### Technical Details
+
+- IP extraction priority: `X-Forwarded-For` (first IP) > `X-Real-IP` > direct IP
+- Enables accurate session tracking without client-side cookies
+- Backwards compatible - ip/user_agent are optional parameters
+
 ## [0.6.0] - 2025-12-05
 
 ### Added

data/lib/mbuzz/client/conversion_request.rb

@@ -3,7 +3,7 @@
 module Mbuzz
   class Client
     class ConversionRequest
-      def initialize(event_id:, visitor_id:, user_id:, conversion_type:, revenue:, currency:, is_acquisition:, inherit_acquisition:, properties:)
+      def initialize(event_id:, visitor_id:, user_id:, conversion_type:, revenue:, currency:, is_acquisition:, inherit_acquisition:, properties:, ip: nil, user_agent: nil, identifier: nil)
         @event_id = event_id
         @visitor_id = visitor_id
         @user_id = user_id
@@ -13,6 +13,9 @@ module Mbuzz
         @is_acquisition = is_acquisition
         @inherit_acquisition = inherit_acquisition
         @properties = properties
+        @ip = ip
+        @user_agent = user_agent
+        @identifier = identifier
       end
 
       def call
@@ -51,6 +54,7 @@ module Mbuzz
         base_payload
           .merge(optional_identifiers)
           .merge(optional_acquisition_fields)
+          .merge(fingerprint_fields)
       end
 
       def base_payload
@@ -78,6 +82,14 @@ module Mbuzz
         end
       end
 
+      def fingerprint_fields
+        {}.tap do |h|
+          h[:ip] = @ip if @ip
+          h[:user_agent] = @user_agent if @user_agent
+          h[:identifier] = @identifier if @identifier
+        end
+      end
+
       def present?(value) = value && !value.to_s.strip.empty?
       def hash?(value) = value.is_a?(Hash)
     end

data/lib/mbuzz/client/track_request.rb

@@ -3,12 +3,14 @@
 module Mbuzz
   class Client
     class TrackRequest
-      def initialize(user_id, visitor_id, session_id, event_type, properties)
+      def initialize(user_id, visitor_id, event_type, properties, ip = nil, user_agent = nil, identifier = nil)
         @user_id = user_id
         @visitor_id = visitor_id
-        @session_id = session_id
         @event_type = event_type
         @properties = properties
+        @ip = ip
+        @user_agent = user_agent
+        @identifier = identifier
       end
 
       def call
@@ -36,9 +38,11 @@ module Mbuzz
         {
           user_id: @user_id,
           visitor_id: @visitor_id,
-          session_id: @session_id,
           event_type: @event_type,
           properties: @properties,
+          ip: @ip,
+          user_agent: @user_agent,
+          identifier: @identifier,
           timestamp: Time.now.utc.iso8601
         }.compact
       end

data/lib/mbuzz/client.rb

@@ -3,19 +3,18 @@
 require_relative "client/track_request"
 require_relative "client/identify_request"
 require_relative "client/conversion_request"
-require_relative "client/session_request"
 
 module Mbuzz
   class Client
-    def self.track(user_id: nil, visitor_id: nil, session_id: nil, event_type:, properties: {})
-      TrackRequest.new(user_id, visitor_id, session_id, event_type, properties).call
+    def self.track(user_id: nil, visitor_id: nil, event_type:, properties: {}, ip: nil, user_agent: nil, identifier: nil)
+      TrackRequest.new(user_id, visitor_id, event_type, properties, ip, user_agent, identifier).call
     end
 
     def self.identify(user_id:, visitor_id: nil, traits: {})
       IdentifyRequest.new(user_id, visitor_id, traits).call
     end
 
-    def self.conversion(event_id: nil, visitor_id: nil, user_id: nil, conversion_type:, revenue: nil, currency: "USD", is_acquisition: false, inherit_acquisition: false, properties: {})
+    def self.conversion(event_id: nil, visitor_id: nil, user_id: nil, conversion_type:, revenue: nil, currency: "USD", is_acquisition: false, inherit_acquisition: false, properties: {}, ip: nil, user_agent: nil, identifier: nil)
       ConversionRequest.new(
         event_id: event_id,
         visitor_id: visitor_id,
@@ -25,12 +24,11 @@ module Mbuzz
         currency: currency,
         is_acquisition: is_acquisition,
         inherit_acquisition: inherit_acquisition,
-        properties: properties
+        properties: properties,
+        ip: ip,
+        user_agent: user_agent,
+        identifier: identifier
       ).call
     end
-
-    def self.session(visitor_id:, session_id:, url:, referrer: nil, started_at: nil)
-      SessionRequest.new(visitor_id, session_id, url, referrer, started_at).call
-    end
   end
 end

data/lib/mbuzz/controller_helpers.rb

@@ -26,9 +26,5 @@ module Mbuzz
     def mbuzz_visitor_id
       request.env[ENV_VISITOR_ID_KEY]
     end
-
-    def mbuzz_session_id
-      request.env[ENV_SESSION_ID_KEY]
-    end
   end
 end

data/lib/mbuzz/middleware/tracking.rb

@@ -17,13 +17,10 @@ module Mbuzz
 
         env[ENV_VISITOR_ID_KEY] = context[:visitor_id]
         env[ENV_USER_ID_KEY] = context[:user_id]
-        env[ENV_SESSION_ID_KEY] = context[:session_id]
 
         RequestContext.with_context(request: request) do
-          create_session_if_new(context, request)
-
           status, headers, body = @app.call(env)
-          set_cookies(headers, context, request)
+          set_visitor_cookie(headers, context, request)
           [status, headers, body]
         end
       end
@@ -51,9 +48,7 @@ module Mbuzz
       def build_request_context(request)
         {
           visitor_id: resolve_visitor_id(request),
-          session_id: resolve_session_id(request),
-          user_id: user_id_from_session(request),
-          new_session: new_session?(request)
+          user_id: user_id_from_session(request)
         }.freeze
       end
 
@@ -61,91 +56,15 @@ module Mbuzz
         visitor_id_from_cookie(request) || Visitor::Identifier.generate
       end
 
-      def resolve_session_id(request)
-        session_id_from_cookie(request) || generate_session_id(request)
-      end
-
       def visitor_id_from_cookie(request)
         request.cookies[VISITOR_COOKIE_NAME]
       end
 
-      def session_id_from_cookie(request)
-        request.cookies[SESSION_COOKIE_NAME]
-      end
-
       def user_id_from_session(request)
         request.session[SESSION_USER_ID_KEY] if request.session
       end
 
-      def new_session?(request)
-        session_id_from_cookie(request).nil?
-      end
-
-      def generate_session_id(request)
-        existing_visitor_id = visitor_id_from_cookie(request)
-
-        if existing_visitor_id
-          Session::IdGenerator.generate_deterministic(visitor_id: existing_visitor_id)
-        else
-          Session::IdGenerator.generate_from_fingerprint(
-            client_ip: client_ip(request),
-            user_agent: user_agent(request)
-          )
-        end
-      end
-
-      def client_ip(request)
-        request.env["HTTP_X_FORWARDED_FOR"]&.split(",")&.first&.strip ||
-          request.env["HTTP_X_REAL_IP"] ||
-          request.ip ||
-          "unknown"
-      end
-
-      def user_agent(request)
-        request.user_agent || "unknown"
-      end
-
-      # Session creation
-
-      def create_session_if_new(context, request)
-        return unless context[:new_session]
-
-        create_session_async(context, request)
-      end
-
-      def create_session_async(context, request)
-        # Capture values in local variables for thread safety
-        visitor_id = context[:visitor_id]
-        session_id = context[:session_id]
-        url = request.url
-        referrer = request.referer
-
-        Thread.new do
-          create_session(visitor_id, session_id, url, referrer)
-        end
-      end
-
-      def create_session(visitor_id, session_id, url, referrer)
-        Client.session(
-          visitor_id: visitor_id,
-          session_id: session_id,
-          url: url,
-          referrer: referrer
-        )
-      rescue => e
-        log_session_error(e)
-      end
-
-      def log_session_error(error)
-        Mbuzz.config.logger&.error("Session creation failed: #{error.message}")
-      end
-
-      # Cookie setting
-
-      def set_cookies(headers, context, request)
-        set_visitor_cookie(headers, context, request)
-        set_session_cookie(headers, context, request)
-      end
+      # Cookie setting - only visitor cookie (sessions are server-side)
 
       def set_visitor_cookie(headers, context, request)
         Rack::Utils.set_cookie_header!(
@@ -155,14 +74,6 @@ module Mbuzz
         )
       end
 
-      def set_session_cookie(headers, context, request)
-        Rack::Utils.set_cookie_header!(
-          headers,
-          SESSION_COOKIE_NAME,
-          session_cookie_options(context, request)
-        )
-      end
-
       def visitor_cookie_options(context, request)
         base_cookie_options(request).merge(
           value: context[:visitor_id],
@@ -170,13 +81,6 @@ module Mbuzz
         )
       end
 
-      def session_cookie_options(context, request)
-        base_cookie_options(request).merge(
-          value: context[:session_id],
-          max_age: SESSION_COOKIE_MAX_AGE
-        )
-      end
-
       def base_cookie_options(request)
         options = {
           path: VISITOR_COOKIE_PATH,

data/lib/mbuzz/request_context.rb

@@ -33,6 +33,12 @@ module Mbuzz
       @request.user_agent
     end
 
+    def ip
+      @request.env["HTTP_X_FORWARDED_FOR"]&.split(",")&.first&.strip ||
+        @request.env["HTTP_X_REAL_IP"] ||
+        @request.ip
+    end
+
     def enriched_properties(custom = {})
       { url: url, referrer: referrer }.compact.merge(custom)
     end

data/lib/mbuzz/version.rb

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

data/lib/mbuzz.rb

@@ -3,7 +3,6 @@
 require_relative "mbuzz/version"
 require_relative "mbuzz/configuration"
 require_relative "mbuzz/visitor/identifier"
-require_relative "mbuzz/session/id_generator"
 require_relative "mbuzz/request_context"
 require_relative "mbuzz/api"
 require_relative "mbuzz/client"
@@ -18,20 +17,15 @@ module Mbuzz
   EVENTS_PATH = "/events"
   IDENTIFY_PATH = "/identify"
   CONVERSIONS_PATH = "/conversions"
-  SESSIONS_PATH = "/sessions"
 
   VISITOR_COOKIE_NAME = "_mbuzz_vid"
   VISITOR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2 # 2 years
   VISITOR_COOKIE_PATH = "/"
   VISITOR_COOKIE_SAME_SITE = "Lax"
 
-  SESSION_COOKIE_NAME = "_mbuzz_sid"
-  SESSION_COOKIE_MAX_AGE = 30 * 60 # 30 minutes
-
   SESSION_USER_ID_KEY = "user_id"
   ENV_USER_ID_KEY = "mbuzz.user_id"
   ENV_VISITOR_ID_KEY = "mbuzz.visitor_id"
-  ENV_SESSION_ID_KEY = "mbuzz.session_id"
 
   # ============================================================================
   # Configuration
@@ -81,10 +75,6 @@ module Mbuzz
     RequestContext.current&.request&.env&.dig(ENV_USER_ID_KEY)
   end
 
-  def self.session_id
-    RequestContext.current&.request&.env&.dig(ENV_SESSION_ID_KEY)
-  end
-
   # ============================================================================
   # 4-Call Model API
   # ============================================================================
@@ -93,18 +83,24 @@ module Mbuzz
   #
   # @param event_type [String] The name of the event
   # @param properties [Hash] Custom event properties (url, referrer auto-added)
+  # @param identifier [Hash, nil] Optional identifier for cross-device identity resolution
   # @return [Hash, false] Result hash on success, false on failure
   #
   # @example
   #   Mbuzz.event("add_to_cart", product_id: "SKU-123", price: 49.99)
   #
-  def self.event(event_type, **properties)
+  # @example With identifier for cross-device tracking
+  #   Mbuzz.event("page_view", identifier: { email: "user@example.com" })
+  #
+  def self.event(event_type, identifier: nil, **properties)
     Client.track(
       visitor_id: visitor_id,
-      session_id: session_id,
       user_id: user_id,
       event_type: event_type,
-      properties: enriched_properties(properties)
+      properties: enriched_properties(properties),
+      ip: current_ip,
+      user_agent: current_user_agent,
+      identifier: identifier
     )
   end
 
@@ -121,6 +117,7 @@ module Mbuzz
   # @param user_id [String, nil] User ID for acquisition-linked conversions
   # @param is_acquisition [Boolean] Mark this as the acquisition conversion for this user
   # @param inherit_acquisition [Boolean] Inherit attribution from user's acquisition conversion
+  # @param identifier [Hash, nil] Optional identifier for cross-device identity resolution
   # @param properties [Hash] Custom properties
   # @return [Hash, false] Result hash on success, false on failure
   #
@@ -133,7 +130,10 @@ module Mbuzz
   # @example Recurring revenue (inherits attribution from acquisition)
   #   Mbuzz.conversion("payment", user_id: "user_123", revenue: 49.00, inherit_acquisition: true)
   #
-  def self.conversion(conversion_type, revenue: nil, user_id: nil, is_acquisition: false, inherit_acquisition: false, **properties)
+  # @example With identifier for cross-device tracking
+  #   Mbuzz.conversion("purchase", identifier: { email: "user@example.com" })
+  #
+  def self.conversion(conversion_type, revenue: nil, user_id: nil, is_acquisition: false, inherit_acquisition: false, identifier: nil, **properties)
     Client.conversion(
       visitor_id: visitor_id,
       user_id: user_id,
@@ -141,7 +141,10 @@ module Mbuzz
       revenue: revenue,
       is_acquisition: is_acquisition,
       inherit_acquisition: inherit_acquisition,
-      properties: enriched_properties(properties)
+      properties: enriched_properties(properties),
+      ip: current_ip,
+      user_agent: current_user_agent,
+      identifier: identifier
     )
   end
 
@@ -176,4 +179,14 @@ module Mbuzz
     RequestContext.current.enriched_properties(custom_properties)
   end
   private_class_method :enriched_properties
+
+  def self.current_ip
+    RequestContext.current&.ip
+  end
+  private_class_method :current_ip
+
+  def self.current_user_agent
+    RequestContext.current&.user_agent
+  end
+  private_class_method :current_user_agent
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mbuzz
 version: !ruby/object:Gem::Version
-  version: 0.6.7
+  version: 0.7.0
 platform: ruby
 authors:
 - mbuzz team
@@ -44,14 +44,12 @@ files:
 - lib/mbuzz/client.rb
 - lib/mbuzz/client/conversion_request.rb
 - lib/mbuzz/client/identify_request.rb
-- lib/mbuzz/client/session_request.rb
 - lib/mbuzz/client/track_request.rb
 - lib/mbuzz/configuration.rb
 - lib/mbuzz/controller_helpers.rb
 - lib/mbuzz/middleware/tracking.rb
 - lib/mbuzz/railtie.rb
 - lib/mbuzz/request_context.rb
-- lib/mbuzz/session/id_generator.rb
 - lib/mbuzz/version.rb
 - lib/mbuzz/visitor/identifier.rb
 - lib/specs/old/SPECIFICATION.md

data/lib/mbuzz/client/session_request.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Mbuzz
-  class Client
-    class SessionRequest
-      def initialize(visitor_id, session_id, url, referrer, started_at)
-        @visitor_id = visitor_id
-        @session_id = session_id
-        @url = url
-        @referrer = referrer
-        @started_at = started_at || Time.now.utc.iso8601
-      end
-
-      def call
-        return false unless valid?
-
-        Api.post(SESSIONS_PATH, payload)
-      end
-
-      private
-
-      attr_reader :visitor_id, :session_id, :url, :referrer, :started_at
-
-      def valid?
-        present?(visitor_id) && present?(session_id) && present?(url)
-      end
-
-      def payload
-        {
-          session: {
-            visitor_id: visitor_id,
-            session_id: session_id,
-            url: url,
-            referrer: referrer,
-            started_at: started_at
-          }.compact
-        }
-      end
-
-      def present?(value) = value && !value.to_s.strip.empty?
-    end
-  end
-end

data/lib/mbuzz/session/id_generator.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-require "securerandom"
-
-module Mbuzz
-  module Session
-    class IdGenerator
-      SESSION_TIMEOUT_SECONDS = 1800
-      SESSION_ID_LENGTH = 64
-      FINGERPRINT_LENGTH = 32
-
-      class << self
-        def generate_deterministic(visitor_id:, timestamp: Time.now.to_i)
-          time_bucket = timestamp / SESSION_TIMEOUT_SECONDS
-          raw = "#{visitor_id}_#{time_bucket}"
-          Digest::SHA256.hexdigest(raw)[0, SESSION_ID_LENGTH]
-        end
-
-        def generate_from_fingerprint(client_ip:, user_agent:, timestamp: Time.now.to_i)
-          fingerprint = Digest::SHA256.hexdigest("#{client_ip}|#{user_agent}")[0, FINGERPRINT_LENGTH]
-          time_bucket = timestamp / SESSION_TIMEOUT_SECONDS
-          raw = "#{fingerprint}_#{time_bucket}"
-          Digest::SHA256.hexdigest(raw)[0, SESSION_ID_LENGTH]
-        end
-
-        def generate_random
-          SecureRandom.hex(32)
-        end
-      end
-    end
-  end
-end