Getting Started with Multibuzz

Server-side multi-touch attribution tracking for your application.

The 4-Call Model

Multibuzz uses a simple 4-call SDK model:

That's it. Four methods to complete multi-touch attribution.

Quick Start

1. Get Your API Key

1. Log in to your dashboard
2. Navigate to API Keys
3. Click Create API Key
4. Choose Test environment for development
5. Copy your API key (starts with sk_test_...)

2. Install the Client Library

# Gemfile
gem 'mbuzz'

# Then run:
bundle install

No installation needed.
Use any HTTP client.

3. Initialize (init)

# config/initializers/mbuzz.rb
Mbuzz.init(
  api_key: ENV['MBUZZ_API_KEY'],
  debug: Rails.env.development?
)

# Set your API key as environment variable
export MBUZZ_API_KEY=sk_test_your_key_here

# Use in Authorization header
curl -H "Authorization: Bearer $MBUZZ_API_KEY" \
     https://mbuzz.co/api/v1/events

⚠️ Security: Never commit API keys to git. Use environment variables.

4. Track Events (event)

Track steps in the customer journey:

# Track user interactions
Mbuzz.event("page_view", url: "/pricing")
Mbuzz.event("add_to_cart", product_id: "SKU-123", price: 49.99)
Mbuzz.event("checkout_started", cart_total: 99.99)

# Group events into funnels for focused analysis
Mbuzz.event("signup_start", funnel: "signup", source: "homepage")
Mbuzz.event("signup_complete", funnel: "signup")

curl -X POST https://www.mbuzz.co/api/v1/events \
  -H "Authorization: Bearer $MBUZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "add_to_cart",
    "visitor_id": "abc123...",
    "funnel": "purchase",
    "properties": {
      "product_id": "SKU-123",
      "price": 49.99
    }
  }'

Core Concepts

Sessions (The Foundation of Attribution)

A session is a single visit to your site with acquisition context. Sessions are the touchpoints used for attribution.

What a session captures:
- UTM parameters (utm_source, utm_medium, utm_campaign, etc.)
- Referrer URL (for organic/referral traffic)
- Channel (derived from UTMs + referrer: paid_search, organic, email, etc.)
- Landing page

Session behavior:
- Auto-created: SDK middleware creates sessions automatically
- 30-minute timeout: New session after 30 min of inactivity
- Non-blocking: Session POST is async (doesn't slow your app)

Why sessions matter: Without sessions, you can't know how a visitor arrived. Sessions make multi-touch attribution possible.

Visitors

Anonymous users tracked via cookies.

• Lifetime: 2 years
• Auto-generated: By SDK (64-char hex, stored in _mbuzz_vid cookie)
• Thread-safe: Works with multi-threaded servers
• Privacy-first: No PII required

A single person may have multiple visitors (multiple devices/browsers).

Users

Known, identified users in your system.

• Cross-device: One user identity across all devices
• Permanent: Persists beyond cookies
• Your ID: Use your application's user identifier

Link visitors to users with Mbuzz.identify() or Mbuzz.alias().

Events

Actions users take in your application.

Required fields:
- event_type - Event name (e.g., "signup", "purchase", "add_to_cart")
- user_id OR visitor_id - At least one identifier required

Recommended fields:
- session_id - Links event to session for attribution
- funnel - Group events into funnels for focused analysis

Optional fields:
- properties - Custom metadata (JSON object)
- timestamp - When event occurred (defaults to now)

Funnels

Group related events into funnels for focused conversion analysis.

Why use funnels?
- Separate signup flow from purchase flow
- Analyze each conversion path independently
- Filter dashboard to specific customer journeys

Example funnels:
```ruby

Signup funnel

Mbuzz.event("pricing_view", funnel: "signup")
Mbuzz.event("signup_start", funnel: "signup")
Mbuzz.event("signup_complete", funnel: "signup")

Purchase funnel

Mbuzz.event("add_to_cart", funnel: "purchase")
Mbuzz.event("checkout_started", funnel: "purchase")
Mbuzz.event("purchase_complete", funnel: "purchase")
```

Dashboard filtering: Use the funnel dropdown to view specific funnels. "All Funnels" shows everything.

Automatic Session Tracking

The Ruby gem includes Rack middleware that automatically creates sessions when visitors land on your site.

What happens on each request:
1. SDK checks for existing visitor cookie (_mbuzz_vid)
2. SDK checks for existing session cookie (_mbuzz_sid)
3. If new session detected → POST to API with full context
4. Cookies refreshed

Session context captured automatically:
- Full URL (including UTM parameters)
- Referrer URL
- User-Agent
- IP address (for geo lookup)

Session detection:
- New visitor: No _mbuzz_vid cookie → new session
- Returning visitor, new session: _mbuzz_vid exists but _mbuzz_sid missing/expired (30+ min) → new session
- Same session: Both cookies valid → no new session

The API handles:
- UTM parameter extraction
- Referrer analysis
- Channel derivation (paid_search, organic, email, etc.)
- Visitor/Session record creation

Important: Session POSTs are async and non-blocking. Your page render is not slowed.

Disable if needed:

# config/initializers/mbuzz.rb
Mbuzz.configure do |config|
  config.enabled = false
end

User Identification (identify)

Link visitors to known users and store traits. This enables cross-device attribution.

# On signup or login - links visitor automatically
Mbuzz.identify(current_user.id,
  traits: {
    email: current_user.email,
    name: current_user.name,
    plan: current_user.plan
  }
)

curl -X POST https://www.mbuzz.co/api/v1/identify \
  -H "Authorization: Bearer $MBUZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123",
    "visitor_id": "abc123def456...",
    "traits": {
      "email": "user@example.com",
      "name": "Jane Doe",
      "plan": "pro"
    }
  }'

When to call:
- On signup (links first visitor to new user)
- On every login (links new devices to existing user)
- When user attributes change

What Identify Does

identify performs two actions in one call:

1. Links visitor to user (if visitor_id provided or available from cookie)
2. Stores user traits (email, name, plan, etc.)

When you link a visitor:

Backward attribution:
- All past sessions from this visitor are attributed to the user
- Sessions from before signup become part of their journey

Forward attribution:
- All future sessions from this visitor automatically attributed to the user

Retroactive recalculation:
- If the user has existing conversions, and the newly-linked visitor has sessions
within those conversions' lookback windows, attribution is automatically recalculated

Cross-Device Attribution

Users often visit on multiple devices. Each device has a different visitor ID:

Desktop visitor (abc) ─────┐
                           ├──→ User (usr_123)
Mobile visitor (def) ──────┘

How it works:
1. User visits on desktop → visitor abc created
2. User visits on mobile → visitor def created
3. User signs up on mobile → identify() links mobile visitor
4. User logs in on desktop → identify() links desktop visitor
5. Now both visitors linked → full cross-device attribution

Call identify on every login, not just signup. This ensures visitors from new devices get linked.

Example: Full Journey Attribution

Day 1: Jane visits via Google Ads (desktop) → Session A
Day 3: Jane visits via Facebook (mobile) → Session B
Day 5: Jane signs up (mobile) → identify() links mobile visitor
Day 6: Jane logs in (desktop) → identify() links desktop visitor
Day 7: Jane purchases → Attribution spans ALL sessions (A, B, etc.)

Without identify on each device, you'd only see mobile sessions.

Conversion Tracking

Conversions are the key metric for attribution. When a user converts (signup, purchase, etc.),
the system automatically calculates attribution across all your configured models.

Creating Conversions

You can create conversions in two ways:

Option A: Event-based (recommended for precise attribution)

# First track the conversion event
result = Mbuzz::Client.track(
  visitor_id: mbuzz_visitor_id,
  event_type: 'checkout_completed',
  properties: { order_id: order.id }
)

# Then create the conversion linked to that event
if result[:success]
  conversion = Mbuzz::Client.conversion(
    event_id: result[:event_id],
    conversion_type: 'purchase',
    revenue: order.total
  )

  # Access attribution data
  if conversion[:success]
    conversion[:attribution][:models].each do |model, credits|
      puts "#{model}: #{credits.map { |c| c[:channel] }.join(', ')}"
    end
  end
end

# Create conversion from event
curl -X POST https://mbuzz.co/api/v1/conversions \
  -H "Authorization: Bearer $MBUZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion": {
      "event_id": "evt_abc123",
      "conversion_type": "purchase",
      "revenue": 99.99
    }
  }'

Option B: Visitor-based (simpler, for direct conversions)

# Create conversion directly from visitor ID
# (uses visitor's most recent session)
conversion = Mbuzz::Client.conversion(
  visitor_id: mbuzz_visitor_id,
  conversion_type: 'purchase',
  revenue: order.total,
  funnel: 'purchase',  # Optional: group into funnel
  properties: { plan: 'pro' }
)

# Create conversion from visitor ID
curl -X POST https://mbuzz.co/api/v1/conversions \
  -H "Authorization: Bearer $MBUZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion": {
      "visitor_id": "65dabef8d611f332d5bb88f5d6870c733d89f962594575b66f0e1de1ede1ebf0",
      "conversion_type": "purchase",
      "funnel": "purchase",
      "revenue": 99.99
    }
  }'

Conversion Response

Successful conversions return attribution data immediately:

{
  "id": "conv_xyz789",
  "conversion_type": "purchase",
  "revenue": "99.99",
  "attribution": {
    "lookback_days": 30,
    "sessions_analyzed": 3,
    "models": {
      "first_touch": [
        { "channel": "organic_search", "credit": 1.0, "revenue_credit": "99.99" }
      ],
      "last_touch": [
        { "channel": "email", "credit": 1.0, "revenue_credit": "99.99" }
      ],
      "linear": [
        { "channel": "organic_search", "credit": 0.333, "revenue_credit": "33.00" },
        { "channel": "paid_social", "credit": 0.333, "revenue_credit": "33.00" },
        { "channel": "email", "credit": 0.334, "revenue_credit": "33.99" }
      ]
    }
  }
}

When to Use Each Approach

Common Use Cases

E-Commerce Tracking

class OrdersController < ApplicationController
  def create
    @order = current_user.orders.create!(order_params)

    # Track the event
    Mbuzz.event("checkout_completed", order_id: @order.id)

    # Record the conversion with revenue
    Mbuzz.conversion("purchase",
      revenue: @order.total,
      order_id: @order.id
    )

    redirect_to order_path(@order)
  end
end

curl -X POST https://www.mbuzz.co/api/v1/events \
  -H "Authorization: Bearer $MBUZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123",
    "event_type": "Purchase Completed",
    "properties": {
      "order_id": "order_456",
      "amount": 99.99,
      "items": 2,
      "currency": "USD"
    }
  }'

SaaS Subscription Tracking

class SubscriptionsController < ApplicationController
  def create
    @subscription = current_user.create_subscription!(
      plan: params[:plan]
    )

    # Record as conversion with MRR
    Mbuzz.conversion("subscription",
      revenue: @subscription.monthly_revenue,
      plan: @subscription.plan,
      billing_cycle: @subscription.billing_cycle
    )

    redirect_to dashboard_path
  end
end

curl -X POST https://www.mbuzz.co/api/v1/events \
  -H "Authorization: Bearer $MBUZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123",
    "event_type": "Subscription Created",
    "properties": {
      "plan": "pro",
      "billing_cycle": "monthly",
      "mrr": 99.00
    }
  }'

Error Handling

Client libraries never raise exceptions. All errors are:

• Logged (if debug mode enabled)
• Returned as false from tracking methods
• Silently ignored otherwise

Why: Tracking failures should never break your application.

Debugging:

# Enable debug mode in initializer
Mbuzz.init(api_key: ENV['MBUZZ_API_KEY'], debug: true)

# Check return values
result = Mbuzz.event("test_event", foo: "bar")
if result
  puts "Tracking succeeded"
else
  puts "Tracking failed (check logs)"
end

Testing

Disable Tracking in Tests

# config/initializers/mbuzz.rb
Mbuzz.init(
  api_key: ENV['MBUZZ_API_KEY'],
  enabled: !Rails.env.test?
)

# Use test API key for development
export MBUZZ_API_KEY=sk_test_your_key_here

Next Steps

Now that you understand the 4-call model:

1. Initialize - Set up Mbuzz.init() in your app
2. Track events - Call Mbuzz.event() for user interactions
3. Record conversions - Call Mbuzz.conversion() for revenue events
4. Identify users - Call Mbuzz.identify() on signup/login (enables cross-device)
5. View attribution - Check your dashboard for attribution data

Need help? Check out:
- Authentication - API key management