These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content
EmbeddingEmbedding Guide

Embedding Guide

DropAFinder finders are designed to live inside your website, not on a separate domain. This guide explains how that embedding works, what it requires from the host page, and what trade-offs the embed model implies.

How embedding works

A DropAFinder embed is two things on the host page:

  1. A mount target — an empty <div id="finder-app" finder-key="…"> where the widget will render.
  2. A script tag — a single <script type="module" src="https://cdn.locationfinders.com/snippet.js"> that loads the widget runtime.

When the page loads, the script reads the finder-key attribute, fetches the finder’s configuration and locations from the DropAFinder CDN, and renders the widget into the mount div. No iframe, no shadow DOM by default — the widget mounts directly into the page.

🟡 [SCREENSHOT: Browser dev-tools view of a host page with the finder embedded, showing the <div id="finder-app"> in the elements panel and the rendered widget on the page.]

Supported embedding methods

There is one supported method: the script tag with a paired mount div. Specifically:

  • ❌ Not an <iframe>
  • ❌ Not a Web Component / custom element
  • ❌ Not an npm package or React component
  • ✅ HTML script-tag embed only

The single supported method is fully documented in Script tag.

💡 Tip: This constraint is intentional. The script-tag embed gives the widget access to the host page’s font stack and CSS variable scope, which makes “matches our brand” customization much easier than an iframe. The trade-off is that the host page is responsible for not breaking the widget’s styles (see “Host page requirements” below).

Host page requirements

The widget runs as a normal browser script. It needs:

  • Module support — type="module" on the script tag. All modern browsers support this; the widget does not target IE.
  • A mount target in the DOM at the time the script runs (or shortly after; the script will wait briefly).
  • Permission to fetch from https://cdn.locationfinders.com and https://api.locationfinders.com. If your host page enforces a Content Security Policy, you’ll need to allowlist those origins.

Things the host page should not do:

  • Apply aggressive CSS resets that target every element (* { all: unset } will visibly break the widget).
  • Strip data-* attributes during HTML sanitization.
  • Block third-party fetches via a CSP connect-src 'self' directive without an allowlist.

What the visitor sees

The widget renders inline at the location of the mount div. The visitor sees a search input, optional refinement controls, the location list, and a map. Behavior is configured in the Finder Builder under How it Behaves — see Behavior.

Authorization

Every finder has an Authorized URLs list. The widget checks the host page’s origin against the list and refuses to render on unlisted domains.

This is your protection against someone copying your snippet and embedding it on their own site. See Authorized URLs.

Caching and update propagation

When you save a change in the Finder Builder, the new configuration goes to the CDN. The widget loads a small pointer file with a 5-minute cache TTL, then loads the actual payload at a versioned URL. In practice, edits visible to visitors within ~5 minutes; the visitor’s browser may cache the old version slightly longer if they recently loaded the page.

Detail: Caching.

Analytics

The widget reports load and interaction events back to DropAFinder. Visitors are not individually identified; events are aggregated per finder. You can review the aggregated view at any finder’s Analytics tab.

The widget does not track visitors across sites or persist their identity. See Analytics for the exact event list and privacy posture.

Picking your finder key

Every finder has a public token (the finder key) that identifies it. The key is in the embed snippet’s finder-key attribute. It grants:

  • Read-only access to that one finder’s design + location data
  • The ability to post analytics events for that finder

It does not grant:

  • Any write access
  • Access to other finders, even in the same workspace
  • Access to the dashboard

Treat finder keys as public. They’re meant to be visible in your HTML.

⚠️ Warning: Don’t paste an account login token, JWT, or API token into the embed snippet by mistake. Only the finder token from the Embed snippet modal belongs there.

Where to next

Typography customizationAnalytics