Skip to main content

​
Pixel Integration (v1)

Current Version - This is the latest version of the MDB pixel with improved reliability and performance. For the previous version, see Legacy Pixel.
The MDB pixel is the core component that enables person-level website visitor identification. This page covers everything you need to know about implementing and configuring the new v1 pixel.

​
Quick Start

Follow these three simple steps to start identifying your website visitors:

​
Step 1: Login to MDB

  1. Go to mdb.tools/dash
  2. Login with your credentials
  3. Navigate to the dashboard

​
Step 2: Create a Webhook

Before setting up the pixel, you’ll need to configure where you want to receive visitor identification data:
  1. Navigate to Webhooks in your MDB dashboard
  2. Create a new webhook endpoint URL
  3. Configure your webhook settings - See the Webhook Integration (v1) guide for details
  4. Save your webhook configuration
MDB uses Svix for reliable webhook delivery. You can view and manage your webhook event types at Svix Dashboard.

​
Step 3: Create and Deploy Your Pixel

  1. Create a new pixel in your MDB dashboard
  2. Copy your pixel ID - You’ll receive a guide after generation
  3. Add the pixel to your website using the script below:
<script src="https://p.mdb.tools/v1/PIXEL_ID?options={}"></script>
Replace PIXEL_ID with your actual pixel ID from the dashboard.
After creating your pixel, you’ll receive a complete implementation guide specific to your pixel ID. Make sure to follow those instructions for the exact script tag to use.

​
Implementation

​
Basic Implementation

<script src="https://p.mdb.tools/v1/pixel_abc123?options={}"></script>

​
With Custom Options

<script src="https://p.mdb.tools/v1/pixel_abc123?options={\"source\":\"homepage\",\"campaign\":\"summer2024\"}"></script>

​
Parameters

  • PIXEL_ID - Your unique pixel ID from the MDB dashboard
  • options - A stringified JavaScript object with custom configuration

​
Options Object

The options parameter allows you to pass ANY custom data that will be included in your webhook responses. You have complete flexibility to structure your data however you need. The only requirement: Your options object must be JSON stringified and URI encoded using encodeURIComponent(JSON.stringify(optionsObject)).

​
Common Use Cases

While you can include anything, common examples include:
  • Campaign tracking - Identify which campaigns are driving identified visitors
  • Tenant/customer identification - Track which customer or client the visitor belongs to
  • Page categorization - Segment data by page type or content category
  • User segmentation - Track different user types or segments
  • Product information - Include product IDs, categories, or pricing tiers
  • Custom metadata - Any additional context your application needs
Important: The options object must be properly JSON stringified and URI encoded when included in the script src. Use encodeURIComponent(JSON.stringify(optionsObject)) to ensure proper encoding.

​
Example with Proper Encoding

// Define your options
const options = {
  tenant_id: "client_abc123",
  page_id: "homepage_v2",
  source: "homepage",
  campaign: "summer2024"
};

// Create the script tag with properly encoded options
const script = document.createElement('script');
script.src = 'https://p.mdb.tools/v1/pixel_abc123?options=' + 
             encodeURIComponent(JSON.stringify(options));
script.async = true;
document.head.appendChild(script);

​
Multi-Tenancy Support

The MDB pixel has built-in support for multi-tenant applications. Any custom options you pass during pixel initialization will be echoed back to you in every webhook associated with that visitor session. This makes it easy to route and process webhook data for multiple customers or tenants.

​
How It Works

  1. At pixel init - Include tenant-specific data in your options object
  2. MDB processes the visitor - The options are stored with the session
  3. Webhook delivery - Your options are included in the webhook payload, allowing you to identify which tenant the data belongs to

​
Multi-Tenant Example

// Initialize pixel with tenant-specific options
const options = {
  tenant_id: "tenant_abc123",           // Your internal customer ID
  tenant_name: "Acme Corp",             // Customer name for reference
  plan_tier: "enterprise",              // Subscription level
  custom_field: "any_value_you_need"    // Any additional context
};

const script = document.createElement('script');
script.src = 'https://p.mdb.tools/v1/pixel_abc123?options=' + 
             encodeURIComponent(JSON.stringify(options));
script.async = true;
document.head.appendChild(script);

​
Webhook Response

When MDB identifies a visitor, your webhook will include the options you provided: 
{
  "events": [
    "...behavioral data..."
  ],
  "options": {
    "tenant_id": "tenant_abc123",
    "tenant_name": "Acme Corp",
    "custom_field": "any_value_you_need"
  },
  "subjects": [{
    "...identified person data..."
  }]
}
The options object in the webhook payload is an exact echo of what you passed during pixel initialization. Use this to route data to the correct tenant, apply tenant-specific logic, or enrich your CRM with customer context.

​
Use Cases

  • White-label solutions - Maintain separate data streams per customer
  • Resellers - Route leads to the appropriate partner

​
Debug Mode

For troubleshooting pixel integration issues, you can enable debug mode by adding mdb_pixel_debug=true to your page URL: 
https://yoursite.com/page?mdb_pixel_debug=true
When debug mode is enabled, the pixel will log status messages to the browser console:
  • “mdb pixel loaded” - Pixel successfully initialized and loaded
  • “mdb pixel error” - Pixel failed to load or initialize
Debug mode only affects console logging and doesn’t change pixel functionality. Remove the debug parameter for production use.

​
Best Practices

  • Test thoroughly - Always test your pixel implementation in a development environment first
  • Validate options - Ensure your options object is valid JSON before deployment
  • Monitor performance - The pixel is designed to be lightweight, but monitor your site’s performance
  • Use meaningful options - Include options that will be useful in your webhook processing
  • Use debug mode - Enable debug mode during development to troubleshoot integration issues

​
What’s New in v1?

The v1 pixel includes several improvements over the legacy version:
  • Improved reliability - Enhanced error handling and retry logic
  • Better performance - Optimized loading and execution
  • Enhanced tracking - More accurate session management
  • Clearer versioning - Explicit version in the URL path

​
Migration from Legacy

If you’re using the legacy pixel (https://p.mdb.tools/TRACKING_ID), see the Legacy Pixel documentation for migration guidance.

​
Next Steps

Once you have the pixel implemented:
  1. Set up webhook handling - Configure your server to receive and process webhooks
  2. Access webhook portal - Visit mdb.tools/dash/pixel-wrap/webhook-portal to manage webhooks
  3. Review event types - Check available webhook events and their payloads
  4. Understand billing - Learn how MDB’s credit system works
  5. Test identification - Verify that visitor identification is working correctly