Skip to main content

​
Installation

​
Basic Installation

Add the script tag to your HTML: 
<script async src="https://p.midbound.net/mdb_pxl_XXXXX"></script>
Or inject it dynamically: 
(function() {
  var s = document.createElement('script');
  s.src = 'https://p.midbound.net/mdb_pxl_XXXXX';
  s.async = true;
  document.head.appendChild(s);
})();

​
Geo Restrictions

US traffic only. We block visitors from regions where we don’t have permission to deliver identities (EU, LATAM, etc.). We use 5 signals to determine visitor location - non-US traffic will not be identified.

​
Best Practices

Always use async, never defer. The pixel is lightweight and non-blocking. Using defer can cause timeouts and missed identifications.
  • Load the pixel as early as possible in <head>
  • Don’t wrap it in DOMContentLoaded or window.onload
  • Don’t conditionally load based on cookies/consent for testing (handle consent separately in production)

​
Wrapping the Pixel

If you’re building a platform and want to wrap our pixel inside yours: 
// your-pixel.js
(function() {
  // Your initialization logic here

  // Load Midbound pixel
  var s = document.createElement('script');
  s.src = 'https://p.midbound.net/mdb_pxl_XXXXX';
  s.async = true;
  document.head.appendChild(s);

  // Your other tracking logic here
})();
Your customers then install your script, and Midbound loads transparently.

​
Verification Handshake

This is optional. You can add a verification handshake to your pixel wrapper so customers can confirm installation from your dashboard.
(function() {
  var params = new URLSearchParams(window.location.search);

  // Load Midbound pixel
  var s = document.createElement('script');
  s.src = 'https://p.midbound.net/mdb_pxl_XXXXX';
  s.async = true;
  document.head.appendChild(s);

  // Verification handshake
  if (params.get('your_verify_param') === 'true' && window.opener) {
    window.opener.postMessage('YOUR_HANDSHAKE_MESSAGE', '*');
  }
})();
Then in your dashboard, open the customer’s site with ?your_verify_param=true and listen for the postMessage to confirm the pixel is installed.

​
Custom Options

Pass custom data through to your webhooks using the options parameter: 
(function() {
  var options = {
    plan: 'enterprise',
    region: 'us-west',
    internalId: 'abc123'
  };

  var s = document.createElement('script');
  s.src = 'https://p.midbound.net/mdb_pxl_XXXXX?options=' +
    encodeURIComponent(JSON.stringify(options));
  s.async = true;
  document.head.appendChild(s);
})();
The options are echoed back in data.session.options: 
{
  "type": "identity.enriched",
  "data": {
    "session": {
      "tenant": "customer_123",
      "options": {
        "plan": "enterprise",
        "region": "us-west",
        "internalId": "abc123"
      },
      "landingPage": "https://example.com/pricing",
      "referrer": "https://www.google.com/",
      ...
    }
  }
}
Use this for any metadata you need for routing or processing - internal IDs, feature flags, A/B test variants, etc.

​
Query Parameters

ParameterDescription
tenantTag traffic by customer/tenant. See Multi-tenancy.
optionsJSON object echoed back in webhooks.

​
Framework Examples

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://p.midbound.net/mdb_pxl_XXXXX"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}