The minimum install is two lines of HTML.
The basic snippet
<div data-form-id="frm_01H..."></div>
<script src="https://formspring.io/embed.js" defer></script>
That's it. Save, deploy, the form appears.
The data-form-id is the public ID of your form. Find it on the form's edit page → Embed tab. It's also in the URL of the form on the dashboard.
The script auto-discovers every element with data-form-id on the page and renders into it. You can have multiple forms on the same page - give each its own <div> with its own data-form-id.
Init options as data attributes
Most options can be set inline:
<div
data-form-id="frm_01H..."
data-theme="dark"
data-redirect="https://example.com/thanks"
data-success-message="Got it. We'll be in touch soon."
data-button-text="Send message"
></div>
<script src="https://formspring.io/embed.js" defer></script>
| Attribute | Default | Notes |
|---|---|---|
data-form-id |
required | Form's public ID |
data-theme |
auto |
light, dark, auto (matches prefers-color-scheme) |
data-redirect |
inherits form setting | URL to redirect to on success |
data-success-message |
inherits form setting | Inline success text shown if no redirect |
data-button-text |
"Submit" | Submit button label |
data-locale |
auto |
en, de, fr, es, it, nl, pt, ja |
data-disable-analytics |
false |
Set to true to skip the page-view ping |
Init options programmatically
For options that don't fit cleanly in a string attribute, configure via the global Formspring object before the script loads:
<div id="contact"></div>
<script>
window.formspringConfig = {
formId: 'frm_01H...',
mountTo: '#contact',
theme: 'dark',
onSuccess: (submission) => console.log('sent', submission.id),
onError: (error) => console.warn('failed', error),
fields: {
message: { placeholder: 'How can we help?' }
}
};
</script>
<script src="https://formspring.io/embed.js" defer></script>
When you provide window.formspringConfig, the widget skips auto-discovery and only renders the form you configured. To configure multiple forms manually, use window.formspringConfigs as an array.
CSP considerations
If your site has a Content Security Policy, you'll need to allow the widget's domain in three directives:
script-src https://formspring.io;
connect-src https://formspring.io;
img-src https://formspring.io data:;
If you use captcha, also allow:
- hCaptcha:
https://hcaptcha.com https://*.hcaptcha.comforscript-src,connect-src,frame-src. - reCAPTCHA:
https://www.google.com https://www.gstatic.comforscript-src,connect-src,frame-src.
The widget does not use eval or inline <script>. It's safe with strict script-src policies.
If you cannot allow a third-party script at all (high-security environments), use headless mode - you bundle the validation logic yourself and POST to the API directly.
Versions
https://formspring.io/embed.js always points to the latest stable release. We don't ship breaking changes within a major version. Pinned, versioned script URLs with integrity hashes are not offered yet.
Campaign tracking and consent
Embedded Formspring content can record how a visitor reached your page: the campaign parameters on your page address (utm_source, utm_medium, utm_campaign, utm_term, utm_content), the ad-platform click ids (gclid, fbclid, ttclid, msclkid), the short-link click id (fs_click) and the link-in-bio block marker (fs_bio). This applies to an embedded funnel, to the forms and booking pages you embed with the snippet or the SDK, and to surveys shown by the SDK. It only happens when your page tells Formspring the visitor allowed analytics. Nothing is read, sent or stored before then.
Tell Formspring from your own consent banner, before the embed loads or any time after:
<script>
window.formspring = window.formspring || {};
window.formspring.consent = { analytics: true, marketing: false };
</script>
<!-- then the embed snippet from your funnel's Embed tab -->
| Your page says | Formspring does |
|---|---|
analytics: true |
Sends the campaign parameters and click ids from your page address with the request, remembers the last campaign visit for 30 days, and keeps a random visitor id in your site's own local storage so that the same visitor's later visits are linked |
analytics: false |
Sends nothing, and deletes the remembered visit and the visitor id it stored earlier |
Nothing (no window.formspring.consent) |
Sends nothing and stores nothing |
The decision can change while the page is open and it applies straight away, without a reload. Assigning a new value is enough:
window.formspring.consent = { analytics: true, marketing: false }; // accepted
window.formspring.consent = { analytics: false, marketing: false }; // withdrawn
If your banner replaces the whole window.formspring object, or changes the decision some other way, tell Formspring to look again:
window.dispatchEvent(new CustomEvent('formspring:consent'));
A funnel that was already on screen when the visitor accepted is attributed from then on (its session receives the campaign context and visitor id). A visitor who withdraws has that removed from the session and is no longer linked to their earlier visits. Forms, surveys and booking pages read the decision when the visitor submits, so a choice made while they fill the form counts.
An embedded form or booking page runs in an iframe and cannot see your page, so the embed script asks your page for the decision and the context (it loads /embed-touch.js from the Formspring address, a small script that only answers iframes Formspring placed). If your page's content security policy limits scripts, allow that address as you do for the embed script itself.
The funnel, form, survey or booking page works the same whatever your page says; a visitor who has not allowed analytics is counted as unattributed.
The visitor id is not a cookie and is never shared with another site. It links a returning visitor's visits for up to 90 days after their last visit, which is what lets the Analytics page credit the first and the last campaign touch. A visitor who clears their browser storage starts a new history.
Verifying the install
- Load the page in a fresh browser tab.
- Open the dev tools console. The widget logs
[Formspring] mounted form frm_01H...when it boots. - Submit a test entry. You should see it appear in your dashboard within seconds.
- The submission's metadata will include
source: "embed"so you can tell embed traffic apart from raw POST traffic.
If the form doesn't render, check:
- The form ID is correct.
- The form is published (unpublished forms refuse to render via embed).
- Your CSP allows
formspring.ioinscript-srcandconnect-src. - The browser console for explicit errors.
