mbuzz Shopify App

Multi-touch attribution for Shopify stores. Track the complete customer journey from first click to purchase.

Architecture

mbuzz-shopify/
├── app/                          # Remix app (settings UI)
│   ├── routes/
│   │   ├── app._index.tsx       # Settings page
│   │   ├── app.tsx              # App layout
│   │   ├── auth.$.tsx           # OAuth callback
│   │   └── webhooks.tsx         # Webhook handler (fallback)
│   └── shopify.server.ts        # Shopify API client
├── extensions/
│   └── mbuzz-tracking/          # Theme App Extension
│       ├── assets/
│       │   └── mbuzz-shopify.js # Client-side tracking
│       └── blocks/
│           └── tracking.liquid  # Theme block
├── prisma/
│   └── schema.prisma            # Session + settings storage
└── shopify.app.toml             # App configuration

How It Works

1. Theme Extension sets visitor cookies and stores IDs in Shopify cart attributes
2. Webhook subscriptions send order/customer events to mbuzz.co/webhooks/shopify
3. mbuzz backend matches visitor_id from cart attributes to create attributed conversions

Development

Prerequisites

• Node.js 20+
• Shopify Partner account
• Shopify development store

Setup

# Install dependencies
npm install

# Set up database
npm run setup

# Create .env from example
cp .env.example .env

# Start development server
npm run dev

Authentication

The first time you run npm run dev, you'll need to authenticate with Shopify:

1. Run npm run dev
2. Follow the authentication prompt
3. Select your development store

Testing

1. Install the app on your development store
2. Enable the theme extension in your theme customizer
3. Enter your mbuzz API key
4. Browse your store and make a test purchase
5. Check mbuzz dashboard for attributed conversion

Deployment

Deploy to Fly.io:

# Install Fly CLI
brew install flyctl

# Login
fly auth login

# Create app (first time only)
fly launch

# Deploy
fly deploy

Update shopify.app.toml with your production URL before deploying.

Webhook Flow

Customer visits store
    ↓
Theme Extension sets visitor cookie (_mbuzz_vid)
    ↓
Events sent with user_agent for server-side session resolution
    ↓
Customer adds to cart
    ↓
Theme Extension stores visitor_id in cart.attributes
    ↓
Customer completes checkout
    ↓
Shopify sends orders/paid webhook to mbuzz.co
    ↓
mbuzz extracts visitor_id from note_attributes
    ↓
Conversion created with full attribution

Note (v0.7.0+): Session cookies (_mbuzz_sid) are no longer used. The mbuzz server handles session resolution using device fingerprinting (IP + User Agent) with a true 30-minute sliding window.

License

Proprietary - mbuzz