mbuzz 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fa7c025330829c88ab9a75a22ca286d14adc1df7872295c5519df4c89536db9
-  data.tar.gz: 62d6675e5ffe9504e2262f84551c286366acc2ad42b6ca6d224367902d9ec3fb
+  metadata.gz: 0d8514076473bbc4fa543510e84789f8cb91ccc99e916b3cef4f4928aaf6baf5
+  data.tar.gz: 159074f0dbac29eb6b721bab4288ce976e4e4361ba503caffc36f37e79cf315e
 SHA512:
-  metadata.gz: eb90968b0d4c17bdc7c5019fa0058c257233bc00e1921f0b70a3dbf885fd8aecd1f9d80ab125d31ab535be5e55a44ecc2e0d46e9cb9c51fef4b9305634241b2f
-  data.tar.gz: cef7cbbc7817a6d7c4eca635594ac9e3b9661d81b33cc7d956376cb9fd763a6d216651e6ec499146e31dca042f024216f3c85c08c6d83f4f31dfb1fff64e8b56
+  metadata.gz: 3d515f639e577a68d9daa8afe13de92dec0a5556cfad2e335ea482f7db0240ff996dd1fb6bbf3388e7f632cb8300e439028091cf1c551627c9be1c22e73ca666
+  data.tar.gz: 9fbe4999f2ce0855d83847d61b4684f30217c01c9074df4cced51e4083167cf3ca24e0e5223f2e57fd859aab6d88f60a68a0adc3074bd0a7f4356c0f9d3e5116

data/README.md

@@ -121,6 +121,63 @@ Mbuzz.user_id     # Current user ID (from session["user_id"])
 Mbuzz.session_id  # Current session ID (from cookie)
 ```
 
+## Background Jobs
+
+When tracking from background jobs (Sidekiq, GoodJob, etc.), there's no HTTP request context. Rails 7+ handles this automatically via `CurrentAttributes`.
+
+### Rails 7+ (Automatic)
+
+mbuzz uses `ActiveSupport::CurrentAttributes` which Rails automatically serializes into ActiveJob payloads:
+
+```ruby
+# In your controller - just enqueue the job
+class OrdersController < ApplicationController
+  def create
+    @order = Order.create!(order_params)
+    ProcessOrderJob.perform_later(@order.id)
+    # visitor_id is automatically captured and passed to the job
+  end
+end
+
+# In your job - mbuzz just works!
+class ProcessOrderJob < ApplicationJob
+  def perform(order_id)
+    order = Order.find(order_id)
+    # Mbuzz::Current.visitor_id was restored by Rails
+    Mbuzz.conversion("purchase", revenue: order.total)
+  end
+end
+```
+
+**How it works:**
+1. Middleware captures `visitor_id` from cookie into `Mbuzz::Current`
+2. Controller enqueues job
+3. Rails serializes `Mbuzz::Current` into job payload
+4. Job runs → Rails restores `Mbuzz::Current`
+5. `Mbuzz.conversion()` reads from `Current` - works!
+
+### Alternative: Explicit visitor_id
+
+For non-Rails apps or when you need more control:
+
+```ruby
+# Store visitor_id on your model
+class Order < ApplicationRecord
+  before_create { self.mbuzz_visitor_id = Mbuzz.visitor_id }
+end
+
+# Pass explicitly in background job
+class ProcessOrderJob
+  def perform(order_id)
+    order = Order.find(order_id)
+    Mbuzz.conversion("purchase",
+      visitor_id: order.mbuzz_visitor_id,  # Explicit
+      revenue: order.total
+    )
+  end
+end
+```
+
 ## Rack / Sinatra Integration
 
 For non-Rails apps, add the middleware manually:

data/lib/mbuzz/client/session_request.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class Client
+    class SessionRequest
+      # Response keys
+      STATUS_KEY = "status"
+      VISITOR_ID_KEY = "visitor_id"
+      SESSION_ID_KEY = "session_id"
+      CHANNEL_KEY = "channel"
+
+      # Response values
+      ACCEPTED_STATUS = "accepted"
+
+      def initialize(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil, started_at: nil)
+        @visitor_id = visitor_id
+        @session_id = session_id
+        @url = url
+        @referrer = referrer
+        @device_fingerprint = device_fingerprint
+        @started_at = started_at
+      end
+
+      def call
+        return false unless valid?
+
+        parse_response(response)
+      rescue StandardError
+        false
+      end
+
+      private
+
+      attr_reader :visitor_id, :session_id, :url, :referrer, :device_fingerprint, :started_at
+
+      def valid?
+        present?(visitor_id) && present?(session_id) && present?(url)
+      end
+
+      def response
+        @response ||= Api.post_with_response(SESSIONS_PATH, { session: payload })
+      end
+
+      def payload
+        {
+          visitor_id: visitor_id,
+          session_id: session_id,
+          url: url,
+          referrer: referrer,
+          device_fingerprint: device_fingerprint,
+          started_at: started_at || Time.now.utc.iso8601
+        }.compact
+      end
+
+      def parse_response(resp)
+        return false unless accepted?(resp)
+
+        {
+          success: true,
+          visitor_id: resp[VISITOR_ID_KEY],
+          session_id: resp[SESSION_ID_KEY],
+          channel: resp[CHANNEL_KEY]
+        }
+      end
+
+      def accepted?(resp)
+        resp && resp[STATUS_KEY] == ACCEPTED_STATUS
+      end
+
+      def present?(value)
+        value && !value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/mbuzz/client.rb

@@ -3,6 +3,7 @@
 require_relative "client/track_request"
 require_relative "client/identify_request"
 require_relative "client/conversion_request"
+require_relative "client/session_request"
 
 module Mbuzz
   class Client
@@ -30,5 +31,16 @@ module Mbuzz
         identifier: identifier
       ).call
     end
+
+    def self.session(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil, started_at: nil)
+      SessionRequest.new(
+        visitor_id: visitor_id,
+        session_id: session_id,
+        url: url,
+        referrer: referrer,
+        device_fingerprint: device_fingerprint,
+        started_at: started_at
+      ).call
+    end
   end
 end

data/lib/mbuzz/current.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  # CurrentAttributes for automatic background job context propagation.
+  #
+  # Rails automatically serializes CurrentAttributes into ActiveJob payloads
+  # and restores them when jobs execute. This means visitor_id captured during
+  # the original request is available in background jobs without any manual
+  # passing or database storage.
+  #
+  # How it works:
+  #   1. Middleware captures visitor_id from cookie
+  #   2. Stores in Mbuzz::Current.visitor_id
+  #   3. Controller enqueues background job
+  #   4. Rails serializes Current attributes into job payload
+  #   5. Job runs on different thread/process
+  #   6. Rails restores Current.visitor_id before job executes
+  #   7. Mbuzz.event/conversion reads from Current.visitor_id
+  #
+  # This is why customers don't need to store visitor_id in their database.
+  #
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :visitor_id
+    attribute :session_id
+    attribute :user_id
+    attribute :ip
+    attribute :user_agent
+  end
+end

data/lib/mbuzz/middleware/tracking.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "rack"
+require "digest"
+require "securerandom"
 
 module Mbuzz
   module Middleware
@@ -16,12 +18,20 @@ module Mbuzz
         context = build_request_context(request)
 
         env[ENV_VISITOR_ID_KEY] = context[:visitor_id]
+        env[ENV_SESSION_ID_KEY] = context[:session_id]
         env[ENV_USER_ID_KEY] = context[:user_id]
 
+        store_in_current_attributes(context, request)
+
+        create_session_async(context, request) if context[:new_session]
+
         RequestContext.with_context(request: request) do
           status, headers, body = @app.call(env)
           set_visitor_cookie(headers, context, request)
+          set_session_cookie(headers, context, request)
           [status, headers, body]
+        ensure
+          reset_current_attributes
         end
       end
 
@@ -45,10 +55,26 @@ module Mbuzz
 
       # Build all request-specific context as a frozen hash
       # This ensures thread-safety by using local variables only
+      # IMPORTANT: All values needed by async session creation must be captured here,
+      # NOT accessed from the request object in the background thread (see #create_session)
       def build_request_context(request)
+        existing_session_id = session_id_from_cookie(request)
+        new_session = existing_session_id.nil?
+        ip = extract_ip(request)
+        user_agent = request.user_agent.to_s
+
         {
           visitor_id: resolve_visitor_id(request),
-          user_id: user_id_from_session(request)
+          session_id: existing_session_id || generate_session_id,
+          user_id: user_id_from_session(request),
+          new_session: new_session,
+          # Session creation data - captured here for thread-safety
+          # Background thread must NOT read from request object
+          url: request.url,
+          referrer: request.referer,
+          ip: ip,
+          user_agent: user_agent,
+          device_fingerprint: Digest::SHA256.hexdigest("#{ip}|#{user_agent}")[0, 32]
         }.freeze
       end
 
@@ -60,11 +86,47 @@ module Mbuzz
         request.cookies[VISITOR_COOKIE_NAME]
       end
 
+      def session_id_from_cookie(request)
+        request.cookies[SESSION_COOKIE_NAME]
+      end
+
+      def generate_session_id
+        SecureRandom.uuid
+      end
+
       def user_id_from_session(request)
         request.session[SESSION_USER_ID_KEY] if request.session
       end
 
-      # Cookie setting - only visitor cookie (sessions are server-side)
+      # Session creation - async to not block request
+      # IMPORTANT: This runs in a background thread. All data must come from
+      # the context hash, NOT from the request object (which may be invalid)
+
+      def create_session_async(context, _request)
+        Thread.new do
+          create_session(context)
+        rescue StandardError => e
+          log_error("Session creation failed: #{e.message}") if Mbuzz.config.debug
+        end
+      end
+
+      def create_session(context)
+        Client.session(
+          visitor_id: context[:visitor_id],
+          session_id: context[:session_id],
+          url: context[:url],
+          referrer: context[:referrer],
+          device_fingerprint: context[:device_fingerprint]
+        )
+      end
+
+      def log_error(message)
+        return unless defined?(Rails) && Rails.logger
+
+        Rails.logger.error("[Mbuzz] #{message}")
+      end
+
+      # Cookie setting - visitor and session cookies
 
       def set_visitor_cookie(headers, context, request)
         Rack::Utils.set_cookie_header!(
@@ -74,6 +136,14 @@ 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],
@@ -81,6 +151,13 @@ 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,
@@ -90,6 +167,30 @@ module Mbuzz
         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)
+
+        Mbuzz::Current.visitor_id = context[:visitor_id]
+        Mbuzz::Current.session_id = context[:session_id]
+        Mbuzz::Current.user_id = context[:user_id]
+        Mbuzz::Current.ip = extract_ip(request)
+        Mbuzz::Current.user_agent = request.user_agent
+      end
+
+      def reset_current_attributes
+        return unless defined?(Mbuzz::Current)
+
+        Mbuzz::Current.reset
+      end
+
+      def extract_ip(request)
+        forwarded = request.env["HTTP_X_FORWARDED_FOR"]
+        return forwarded.split(",").first.strip if forwarded
+
+        request.ip
+      end
     end
   end
 end

data/lib/mbuzz/version.rb

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

data/lib/mbuzz.rb

@@ -9,6 +9,9 @@ require_relative "mbuzz/client"
 require_relative "mbuzz/middleware/tracking"
 require_relative "mbuzz/controller_helpers"
 
+# CurrentAttributes for automatic background job context propagation (Rails only)
+require_relative "mbuzz/current" if defined?(ActiveSupport::CurrentAttributes)
+
 require_relative "mbuzz/railtie" if defined?(Rails::Railtie)
 
 module Mbuzz
@@ -17,15 +20,20 @@ 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
@@ -62,18 +70,25 @@ module Mbuzz
   # Context Accessors
   # ============================================================================
 
+  # Returns visitor_id from Current (background jobs) or request context
   def self.visitor_id
-    RequestContext.current&.request&.env&.dig(ENV_VISITOR_ID_KEY) || fallback_visitor_id
+    current_visitor_id || RequestContext.current&.request&.env&.dig(ENV_VISITOR_ID_KEY)
   end
 
-  def self.fallback_visitor_id
-    @fallback_visitor_id ||= Visitor::Identifier.generate
+  def self.user_id
+    current_user_id || RequestContext.current&.request&.env&.dig(ENV_USER_ID_KEY)
   end
-  private_class_method :fallback_visitor_id
 
-  def self.user_id
-    RequestContext.current&.request&.env&.dig(ENV_USER_ID_KEY)
+  # Check Current attributes (for background job support)
+  def self.current_visitor_id
+    defined?(Current) ? Current.visitor_id : nil
+  end
+  private_class_method :current_visitor_id
+
+  def self.current_user_id
+    defined?(Current) ? Current.user_id : nil
   end
+  private_class_method :current_user_id
 
   # ============================================================================
   # 4-Call Model API
@@ -82,20 +97,30 @@ module Mbuzz
   # Track an event (journey step)
   #
   # @param event_type [String] The name of the event
+  # @param visitor_id [String, nil] Explicit visitor ID (required for background jobs)
   # @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
+  # @example Normal usage (within request context)
   #   Mbuzz.event("add_to_cart", product_id: "SKU-123", price: 49.99)
   #
+  # @example Background job (must pass explicit visitor_id)
+  #   Mbuzz.event("order_processed", visitor_id: order.mbuzz_visitor_id, order_id: order.id)
+  #
   # @example With identifier for cross-device tracking
   #   Mbuzz.event("page_view", identifier: { email: "user@example.com" })
   #
-  def self.event(event_type, identifier: nil, **properties)
+  def self.event(event_type, visitor_id: nil, identifier: nil, **properties)
+    resolved_visitor_id = visitor_id || self.visitor_id
+    resolved_user_id = user_id
+
+    # Must have at least one identifier
+    return false unless resolved_visitor_id || resolved_user_id
+
     Client.track(
-      visitor_id: visitor_id,
-      user_id: user_id,
+      visitor_id: resolved_visitor_id,
+      user_id: resolved_user_id,
       event_type: event_type,
       properties: enriched_properties(properties),
       ip: current_ip,
@@ -113,6 +138,7 @@ module Mbuzz
   # Track a conversion (revenue-generating outcome)
   #
   # @param conversion_type [String] The type of conversion
+  # @param visitor_id [String, nil] Explicit visitor ID (required for background jobs)
   # @param revenue [Numeric, nil] Revenue amount
   # @param user_id [String, nil] User ID for acquisition-linked conversions
   # @param is_acquisition [Boolean] Mark this as the acquisition conversion for this user
@@ -121,9 +147,12 @@ module Mbuzz
   # @param properties [Hash] Custom properties
   # @return [Hash, false] Result hash on success, false on failure
   #
-  # @example Basic conversion
+  # @example Basic conversion (within request context)
   #   Mbuzz.conversion("purchase", revenue: 99.99, order_id: "ORD-123")
   #
+  # @example Background job (must pass explicit visitor_id)
+  #   Mbuzz.conversion("purchase", visitor_id: order.mbuzz_visitor_id, revenue: 99.99)
+  #
   # @example Acquisition conversion (marks signup as THE acquisition moment)
   #   Mbuzz.conversion("signup", user_id: "user_123", is_acquisition: true)
   #
@@ -133,9 +162,14 @@ module Mbuzz
   # @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)
+  def self.conversion(conversion_type, visitor_id: nil, revenue: nil, user_id: nil, is_acquisition: false, inherit_acquisition: false, identifier: nil, **properties)
+    resolved_visitor_id = visitor_id || self.visitor_id
+
+    # Must have at least one identifier (visitor_id or user_id)
+    return false unless resolved_visitor_id || user_id
+
     Client.conversion(
-      visitor_id: visitor_id,
+      visitor_id: resolved_visitor_id,
       user_id: user_id,
       conversion_type: conversion_type,
       revenue: revenue,
@@ -181,12 +215,26 @@ module Mbuzz
   private_class_method :enriched_properties
 
   def self.current_ip
-    RequestContext.current&.ip
+    current_attributes_ip || RequestContext.current&.ip
   end
   private_class_method :current_ip
 
   def self.current_user_agent
-    RequestContext.current&.user_agent
+    current_attributes_user_agent || RequestContext.current&.user_agent
   end
   private_class_method :current_user_agent
+
+  def self.current_attributes_ip
+    return nil unless defined?(Current)
+
+    Current.ip
+  end
+  private_class_method :current_attributes_ip
+
+  def self.current_attributes_user_agent
+    return nil unless defined?(Current)
+
+    Current.user_agent
+  end
+  private_class_method :current_attributes_user_agent
 end

data/lib/specs/v0.7.0_deterministic_sessions.md

@@ -1,6 +1,13 @@
 # mbuzz SDK v0.7.0 - Deterministic Session IDs
 
-**Status**: Proposed
+> **⚠️ SUPERSEDED**: This spec has been replaced by server-side session resolution.
+> See: `multibuzz/lib/specs/1_visitor_session_tracking_spec.md`
+>
+> **What changed**: Instead of SDKs generating deterministic session IDs using time-buckets,
+> the server now handles all session resolution using IP + User-Agent fingerprinting with
+> a true 30-minute sliding window. SDKs no longer manage session cookies.
+
+**Status**: SUPERSEDED (2026-01-09)
 **Last Updated**: 2025-12-29
 **Breaking Change**: No (backward compatible)
 **Affects**: All SDKs (Ruby, Python, PHP, Node)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mbuzz
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - mbuzz team
@@ -44,9 +44,11 @@ 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/current.rb
 - lib/mbuzz/middleware/tracking.rb
 - lib/mbuzz/railtie.rb
 - lib/mbuzz/request_context.rb