formaly-sdk

Show targeted, contextual Formaly surveys inside your product — popups, slide-ins, or a launcher widget — triggered by behavior and audience rules you configure in the dashboard. Framework-agnostic, dependency-free, ~14 KB minified.

Install

npm install formaly-sdk

Or drop in the CDN script (no build step):

<script src="https://formaly.io/formaly-sdk.js" defer></script>

Quick start

import { Formaly } from "formaly-sdk";

Formaly.init({ apiKey: "fml_..." });

// Tell Formaly who the current user is so audience targeting works.
Formaly.identify({ userId: "u_123", plan: "pro", daysActive: 14 });

init() fetches the surveys configured for your workspace and wires up their triggers (delay, scroll depth, exit intent, element click, page view) and audience conditions. Matching surveys appear automatically; nothing else to do.

CommonJS works too: const { Formaly } = require("formaly-sdk");

API

| Method | Description | | --- | --- | | init(config) | Start the SDK and load surveys. Idempotent. Returns a Promise. | | identify(attributes) | Set user attributes used by audience targeting. Merges with previous calls. | | reset() | Clear user attributes (e.g. on logout) and re-evaluate targeting. | | show(surveyId) | Manually open a survey (use with the manual trigger). | | hide(surveyId?) | Close a specific survey, or all open surveys. | | on(event, handler) / off(event, handler) | Subscribe to lifecycle events. | | destroy() | Tear down all listeners and state. |

Config

interface FormalyConfig {
  apiKey: string;     // required, e.g. "fml_..."
  baseUrl?: string;   // defaults to "https://formaly.io"
  debug?: boolean;    // console logging, defaults to false
}

Events

ready · show · complete · dismiss · error

Formaly.on("complete", ({ surveyId }) => {
  console.log("survey completed:", surveyId);
});

Async / non-blocking install (CDN)

Queue calls before the script loads; they replay once it does:

<script>
  !function(){var f=window.Formaly=window.Formaly||{};f.q=f.q||[];
    ["init","identify","show","hide","on","off","reset","destroy"].forEach(
      function(m){f[m]=function(){f.q.push([m,arguments]);};});}();
</script>
<script async src="https://formaly.io/formaly-sdk.js"></script>
<script>
  Formaly.init({ apiKey: "fml_..." });
</script>

SSR / non-browser

Importing the package is safe in SSR — construction never touches window. init() is a no-op outside the browser, so call it from a client-side effect.

License

MIT