Embedding guide

Add the Onramp Kit configurator 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 configurator appears -->
<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-handoff-url="https://app.deepfathom.ai/signup"
></div>

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

Place the container <div> wherever you want the configurator 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.

Required attributes

Attribute	Description
`data-deep-fathom-onramp`	Marks this element as the configurator container
`data-partner-id`	Your unique partner identifier for attribution

Recommended attributes

Attribute	Description
`data-handoff-url`	Where visitors go after completing the assessment (typically the Deep Fathom signup page)
`data-host`	The hosted configurator origin (required for cross-origin embeds)

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-handoff-url="https://app.deepfathom.ai/signup"
></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 configurator 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-handoff-url="https://app.deepfathom.ai/signup"
  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 leads and handoff URLs, 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-snapshot-endpoint="https://api.deepfathom.ai/snapshots"
  data-handoff-url="https://app.deepfathom.ai/signup"
></div>

Attribute	Description
`data-snapshot-endpoint`	API endpoint for saving assessment state (enables sharing and resume)
`data-handoff-url`	Destination URL that receives the snapshot ID and attribution
`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 configurator can render in two modes:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-mode="iframe"
></div>

Mode	Description
`iframe`	Default. Renders in an isolated iframe for maximum compatibility and security isolation.
`inline`	Renders directly in your page DOM. Requires modern browser features. (Coming soon)

For most integrations, leave this unset—the SDK automatically chooses the best mode for the visitor's browser.

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 configurator with JavaScript instead of data attributes:

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

mount('#configurator-container', {
  partnerId: 'your-partner-id',
  host: 'https://onramp.deepfathom.ai',
  handoffUrl: 'https://app.deepfathom.ai/signup',
  snapshotEndpoint: 'https://api.deepfathom.ai/snapshots',
  mode: 'iframe',
  theme: { mode: 'auto' },
  attribution: {
    referralCode: 'SPRING2025',
    utmSource: 'partner-website',
    utmMedium: 'embed',
    utmCampaign: 'cmmc-assessment',
  },
  allowUrlPii: false,
});

This approach is useful when you need to:

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

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://onramp.deepfathom.ai
connect-src: https://api.deepfathom.ai

Iframe restrictions

If your site sets X-Frame-Options or frame-ancestors policies, ensure they don't block the configurator's iframe. The configurator iframe loads from https://onramp.deepfathom.ai.

If something doesn't load

Common issues and solutions:

Symptom	Likely cause	Solution
Blank space where configurator 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
Configurator loads but events don't fire	Origin mismatch	Verify `data-host` matches iframe origin

See Browser support for detailed compatibility information.

All configuration attributes

Attribute	Required	Description
`data-deep-fathom-onramp`	Yes	Marks element as configurator container
`data-partner-id`	Yes	Your partner identifier
`data-host`	For cross-origin	Hosted configurator origin
`data-handoff-url`	Recommended	Destination after completion
`data-snapshot-endpoint`	For sharing	Snapshot API base URL
`data-mode`	No	`iframe` (default) or `inline`
`data-iframe-src`	No	Override full iframe URL
`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 completions 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​

Supporting older browsers​

Configuration options​

Attribution​

Snapshots and sharing​

Rendering mode​

Versioning​

Programmatic initialization​

Security considerations​

Content Security Policy (CSP)​

Iframe restrictions​

If something doesn't load​

All configuration attributes​

Next steps​