JavaScript SDK

Integrate Formbricks surveys into your vanilla JavaScript application

The Formbricks JavaScript SDK allows you to integrate surveys into any vanilla JavaScript application or website.

Installation

1. Install the package

   Install the Formbricks JavaScript SDK using your preferred package manager:

   npm

   npm install @formbricks/js
   
2. Initialize the SDK

   Import and initialize Formbricks in your main JavaScript file:

   import formbricks from "@formbricks/js";
   
   if (typeof window !== "undefined") {
     formbricks.setup({
       environmentId: "your-environment-id",
       appUrl: "https://app.formbricks.com",
     });
   }
   

   Replace your-environment-id with your actual environment ID from the Formbricks dashboard.

Configuration

The setup() method accepts the following configuration options:

Parameter	Type	Required	Description
environmentId	string	Yes	Your Formbricks environment ID
appUrl	string	Yes	Your Formbricks instance URL (e.g., https://app.formbricks.com)

User Identification

Set User ID

Identify users to track their responses across sessions:

await formbricks.setUserId("user-123");

Set User Email

Associate an email address with the current user:

await formbricks.setEmail("[e-mail]");

Set User Attributes

Add custom attributes to segment and target users:

// Set a single attribute
await formbricks.setAttribute("plan", "premium");

// Set multiple attributes at once
await formbricks.setAttributes({
  plan: "premium",
  company: "Acme Inc",
  role: "admin"
});

Set User Language

Set the language preference for the user:

await formbricks.setLanguage("en");

Tracking Events

Track custom events to trigger surveys based on user actions:

// Track a simple event
await formbricks.track("feature_used");

// Track an event with properties (deprecated)
await formbricks.track("purchase_completed", {
  hiddenFields: {
    amount: "99.99",
    currency: "USD"
  }
});

Hidden fields in track properties are deprecated and will be removed in a future version.

Single Page Applications (SPAs)

For SPAs, you need to manually trigger route change detection:

// Call this after route changes
await formbricks.registerRouteChange();

Example with History API

// Intercept pushState and replaceState
const originalPushState = history.pushState;
const originalReplaceState = history.replaceState;

history.pushState = function(...args) {
  originalPushState.apply(this, args);
  formbricks.registerRouteChange();
};

history.replaceState = function(...args) {
  originalReplaceState.apply(this, args);
  formbricks.registerRouteChange();
};

// Listen for popstate events
window.addEventListener('popstate', () => {
  formbricks.registerRouteChange();
});

Logout

Clear user data when a user logs out:

await formbricks.logout();

Content Security Policy (CSP)

If your application uses Content Security Policy, you can set a nonce for inline styles:

formbricks.setNonce("your-csp-nonce");

Pass the nonce value without the nonce- prefix.

TypeScript Support

The SDK is fully typed. Import types as needed:

import formbricks from "@formbricks/js";
import type { TFormbricks } from "@formbricks/js";

// The SDK instance is fully typed
const fb: TFormbricks = formbricks;

Complete Example

import formbricks from "@formbricks/js";

// Initialize
if (typeof window !== "undefined") {
  formbricks.setup({
    environmentId: "clxyz123abc",
    appUrl: "https://app.formbricks.com",
  });

  // Identify user after login
  async function handleLogin(user) {
    await formbricks.setUserId(user.id);
    await formbricks.setEmail(user.email);
    await formbricks.setAttributes({
      plan: user.subscription.plan,
      signupDate: user.createdAt
    });
  }

  // Track events
  document.querySelector('#checkout-button').addEventListener('click', () => {
    formbricks.track('checkout_initiated');
  });

  // Handle logout
  async function handleLogout() {
    await formbricks.logout();
  }
}

Debugging

Enable debug mode by setting the formbricksDebug flag:

window.formbricksDebug = true;

This will log detailed information to the browser console.

Next Steps

React Integration

Learn how to integrate Formbricks with React

Next.js Integration

Learn how to integrate Formbricks with Next.js