Embedding the Boundary Advisor™

Add the Deep Fathom Boundary Advisor™ — an interactive CMMC scoping and boundary planning tool — to your website with a simple code snippet. This guide covers the standard embed, configuration options, and advanced patterns.

Basic embed

The simplest integration requires just two elements: a container and a script.

<!-- Container: where the Boundary Advisor appears -->
<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
></div>

<!-- Loader: initializes the Boundary Advisor -->
<script type="module" src="https://cdn.deepfathom.ai/onramp-kit/v1/widget.mjs"></script>

Place the container <div> wherever you want the Boundary Advisor™ to appear on your page. The script can go in the <head> or at the end of <body>—it loads asynchronously and won't block your page. Keep the SDK and iframe paths on the same version line (for example, v1/widget.mjs with v1/hosted/index.html).

Required attributes

Attribute	Description
`data-deep-fathom-onramp`	Marks this element as the Boundary Advisor container
`data-partner-id`	Your unique partner identifier for attribution
`data-iframe-src` or `data-host`	Iframe target URL or host prefix for the hosted Boundary Advisor

Recommended attributes

Attribute	Description
`data-partner-name`	Your organization name (shown to visitors)
`data-iframe-src`	Full iframe URL (recommended; version-pinned and explicit)

Use data-iframe-src when possible. Use data-host only if your host path resolves directory requests to index.html.

Partner branding

Display your logo and company name in the Boundary Advisor header with a "Powered by Deep Fathom" badge:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
  data-branding-name="Acme Security"
  data-branding-logo="https://acme.com/logo.svg"
  data-branding-logo-dark="https://acme.com/logo-dark.svg"
  data-branding-logo-height="32"
></div>

When partner branding is configured, the header displays:

Your logo (or company name if no logo provided)
"Deep Fathom Boundary Advisor™" product name
"Powered by Deep Fathom" badge

Attribute	Required	Description
`data-branding-name`	Yes (for branding)	Your company name (used as fallback if logo fails to load)
`data-branding-logo`	No	URL to your logo image (SVG, PNG, or JPG). Must be HTTPS.
`data-branding-logo-dark`	No	URL to dark mode variant of your logo
`data-branding-logo-height`	No	Logo height in pixels (16-48, default: 28)

Logo guidelines

Format: SVG recommended for crisp rendering at any size. PNG and JPG also supported.
Height: Keep logos between 16-48px tall. The width scales automatically.
Dark mode: Provide a data-branding-logo-dark variant if your logo doesn't work on dark backgrounds.
Security: Only HTTPS URLs are allowed. Data URLs and JavaScript URLs are blocked.

Name-only branding

If you don't have a logo, just provide your company name:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
  data-branding-name="Acme Security Partners"
></div>

Your name will be displayed prominently in place of a logo.

Supporting older browsers

For maximum browser compatibility, include a fallback script for browsers that don't support ES modules:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-partner-name="Acme Security"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
></div>

<!-- Modern browsers use this -->
<script type="module" src="https://cdn.deepfathom.ai/onramp-kit/v1/widget.mjs"></script>

<!-- Older browsers (IE11, legacy Edge) use this instead -->
<script nomodule src="https://cdn.deepfathom.ai/onramp-kit/v1/widget.legacy.js"></script>

Modern browsers ignore the nomodule script; older browsers ignore type="module". This pattern ensures the Boundary Advisor works everywhere.

Configuration options

Attribution

Track where your leads come from with UTM parameters and referral codes:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-partner-name="Acme Security"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
  data-referral-code="SPRING2025"
  data-utm-source="partner-website"
  data-utm-medium="embed"
  data-utm-campaign="cmmc-assessment"
></div>

All attribution data flows through to the Deal Registration API and is included in onDealRegistered events, so you can track performance in your analytics and CRM.

Attribute	Description
`data-referral-code`	Custom code for campaigns or sales tracking
`data-attribution-source`	Override the default source identifier
`data-utm-source`	UTM source parameter
`data-utm-medium`	UTM medium parameter
`data-utm-campaign`	UTM campaign parameter
`data-utm-content`	UTM content parameter
`data-utm-term`	UTM term parameter

Enable visitors to save and share their assessment progress:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
  data-snapshot-endpoint="https://api.deepfathom.ai/snapshots"
></div>

Attribute	Description
`data-snapshot-endpoint`	API endpoint for saving assessment state (enables sharing and resume)
`data-allow-url-pii`	Set to `true` to include company name in URL snapshots (default: redacted for privacy)

See the Snapshots reference for details on how sharing and resume work.

Rendering mode

The current SDK release renders via iframe mode:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
  data-mode="iframe"
></div>

Mode	Description
`iframe`	Default. Renders in an isolated iframe for maximum compatibility and security isolation.
`inline`	Reserved for future use. Currently logs a warning and falls back to iframe mode.

For most integrations, leave this unset.

Theme mode

Control how the SDK resolves theme values from CSS variables and color palettes:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
  data-theme-mode="auto"
></div>

Supported values: auto, light, dark, partner, df. See the Theming guide for details.

Loading states

Enable a built-in loading placeholder while the iframe initializes:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-iframe-src="https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html"
  data-loading
></div>

You can also provide a custom loading UI via the JavaScript API.

Versioning

The SDK follows semantic versioning. Choose a version strategy based on your needs:

URL pattern	Behavior
`.../v1/widget.mjs`	Latest stable v1.x release (recommended)
`.../v1.2.3/widget.mjs`	Pinned to specific version (for reproducible deployments)
`.../latest/widget.mjs`	Latest release including pre-releases (not recommended for production)

Pre-release versions (like v1.3.0-rc.1) don't update the v1 or latest aliases.

Programmatic initialization

For more control, initialize the Boundary Advisor with JavaScript instead of data attributes:

import { mount } from '@onramp-kit/sdk';

const handle = mount('#configurator-container', {
  partnerId: 'your-partner-id',
  partnerName: 'Acme Security',
  iframeSrc: 'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',
  snapshotEndpoint: 'https://api.deepfathom.ai/snapshots',
  mode: 'iframe',
  theme: { mode: 'auto' },
  loading: true,

  // Partner branding (displays your logo with "Powered by Deep Fathom")
  branding: {
    name: 'Acme Security',
    logo: 'https://acme.com/logo.svg',
    logoDark: 'https://acme.com/logo-dark.svg',
    logoHeight: 32,
  },

  attribution: {
    referralCode: 'SPRING2025',
    utmSource: 'partner-website',
    utmMedium: 'embed',
    utmCampaign: 'cmmc-assessment',
  },
  allowUrlPii: false,

  // Event handlers
  onReady: () => {
    console.log('Boundary Advisor loaded');
  },
  onError: (error) => {
    console.error('Onramp Kit error:', error);
  },
  onDealRegistered: (payload) => {
    console.log('Deal registered:', payload.dealId);
    // Send to your CRM, analytics, etc.
  },
  onComplete: (payload) => {
    console.log('Assessment completed:', payload.summary);
  },
});

// Later: clean up when done
handle.destroy();

This approach is useful when you need to:

Set configuration dynamically based on user context
Initialize multiple Boundary Advisor instances on one page
Integrate with a JavaScript framework (React, Vue, etc.)

Preloading (optional)

If you want faster perceived load times, preload the iframe early and mount it later:

import { preload } from '@onramp-kit/sdk';

const pre = preload({
  partnerId: 'your-partner-id',
  iframeSrc: 'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',
});

// Later, when the user clicks a CTA:
const handle = pre.mount('#configurator-container', { loading: true });

Security considerations

Content Security Policy (CSP)

If your site uses a Content Security Policy, add these directives:

script-src: https://cdn.deepfathom.ai
frame-src: https://cdn.deepfathom.ai
connect-src: https://api.deepfathom.ai https://go.deepfathom.ai

Iframe restrictions

If your site sets X-Frame-Options or frame-ancestors policies, ensure they don't block the Boundary Advisor's iframe. The iframe loads from your configured data-iframe-src (or data-host) origin.

If something doesn't load

Common issues and solutions:

Symptom	Likely cause	Solution
Blank space where Boundary Advisor should be	Script blocked by CSP	Add CDN to `script-src` directive
"Refused to frame" error in console	Iframe blocked by policy	Add origin to `frame-src` directive
Boundary Advisor loads but events don't fire	Origin mismatch	Verify `data-iframe-src` (or `data-host`) points to the expected iframe origin

See Browser support for detailed compatibility information.

All configuration attributes

Attribute	Required	Description
`data-deep-fathom-onramp`	Yes	Marks element as Boundary Advisor container
`data-partner-id`	Yes	Your partner identifier
`data-partner-name`	Recommended	Your organization name
`data-iframe-src`	Yes (or `data-host`)	Full iframe URL (recommended)
`data-host`	Yes (or `data-iframe-src`)	Host/prefix used to build the iframe URL
`data-branding-name`	No	Company name for header branding
`data-branding-logo`	No	Logo URL for header branding (HTTPS only)
`data-branding-logo-dark`	No	Dark mode logo URL
`data-branding-logo-height`	No	Logo height in pixels (16-48)
`data-snapshot-endpoint`	For sharing	Snapshot API base URL
`data-mode`	No	`iframe` (default). `inline` currently falls back to iframe
`data-theme-mode`	No	Theme resolution mode (`auto`, `light`, `dark`, `partner`, `df`)
`data-loading`	No	Show built-in loading placeholder
`data-referral-code`	No	Campaign/sales tracking code
`data-attribution-source`	No	Override source identifier
`data-utm-source`	No	UTM source
`data-utm-medium`	No	UTM medium
`data-utm-campaign`	No	UTM campaign
`data-utm-content`	No	UTM content
`data-utm-term`	No	UTM term
`data-allow-url-pii`	No	Include PII in URL snapshots (`true`/`false`)

Next steps

Track leads with events — Capture deal registrations and integrate with your CRM
Match your brand — Apply your colors and styling
Snapshots and sharing — Enable visitors to save and share assessments

Basic embed​

Required attributes​

Recommended attributes​

Partner branding​

Logo guidelines​

Name-only branding​

Supporting older browsers​

Configuration options​

Attribution​

Snapshots and sharing​

Rendering mode​

Theme mode​

Loading states​

Versioning​

Programmatic initialization​

Preloading (optional)​

Security considerations​

Content Security Policy (CSP)​

Iframe restrictions​

If something doesn't load​

All configuration attributes​

Next steps​