Integrate the Formbricks App Survey SDK into your app using multiple options. Explore the available choices below. If you need something else, open a GitHub Discussion, and we’ll be happy to help!
Important for Self-Hosted Setups:Multi-Domain Setup: If you are using the multi-domain setup, the appUrl
parameter in all SDK configurations should point to your public domain (PUBLIC_URL environment variable). This is the domain where surveys and public-facing content are served, which may be different from your admin interface domain (WEBAPP_URL).Single Domain Setup: If you are using the single domain setup, the appUrl
parameter in all SDK configurations should point to your admin domain (WEBAPP_URL environment variable).
Prerequisites
Before getting started, make sure you have:
-
A running web application with user authentication in your chosen framework.
-
A Formbricks account with your environment ID and API host, available in the Setup Checklist under Settings.
HTML
All you need to do is copy a <script>
tag to your HTML head:
<!-- START Formbricks Surveys -->
<script type="text/javascript">
!function(){
var appUrl = "https://app.formbricks.com"; // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
var environmentId = "<your-environment-id>";
var t=document.createElement("script");t.type="text/javascript",t.async=!0,t.src=appUrl+"/js/formbricks.umd.cjs";var e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(t,e),setTimeout(function(){window.formbricks.setup({environmentId: environmentId, appUrl: appUrl})},500)}();
</script>
<!-- END Formbricks Surveys -->
Required Customizations
Name | Type | Description |
---|
environment-id | string | Formbricks Environment ID. |
app-url | string | URL of the hosted Formbricks instance. |
Now, visit the Validate Your Setup section to verify your setup!
React.js
Install the Formbricks SDK using one of the following package managers: npm
, pnpm
, or yarn
.
Note that zod
is required as a peer dependency and must also be installed in your project.
npm install @formbricks/js zod
pnpm add @formbricks/js zod
yarn add @formbricks/js zod
Update your App.js/ts
file to initialize Formbricks.
// other imports
import formbricks from "@formbricks/js";
if (typeof window !== "undefined") {
formbricks.setup({
environmentId: "<environment-id>",
appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
});
}
function App() {
// your own app
}
export default App;
Required Customizations
Name | Type | Description |
---|
environment-id | string | Formbricks Environment ID. |
app-url | string | URL of the hosted Formbricks instance. |
Now, visit the Validate Your Setup section to verify your setup!
Next.js
Next.js projects use either the App Directory or the Pages Directory. Since the Formbricks SDK runs on the client side, follow these steps based on your setup:
-
App Directory: Create a new component in
app/formbricks.tsx
and call it in app/layout.tsx
.
-
Pages Directory: Initialize Formbricks directly in
_app.tsx
.
Code snippets for the integration for both conventions are provided to further assist you.
npm install @formbricks/js zod
pnpm add @formbricks/js zod
yarn add @formbricks/js zod
App directory
"use client";
import { usePathname, useSearchParams } from "next/navigation";
import { useEffect } from "react";
import formbricks from "@formbricks/js";
export default function FormbricksProvider() {
const pathname = usePathname();
const searchParams = useSearchParams();
useEffect(() => {
formbricks.setup({
environmentId: "<environment-id>",
appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
});
}, []);
useEffect(() => {
formbricks?.registerRouteChange();
}, [pathname, searchParams]);
return null;
}
// other imports
import FormbricksProvider from "./formbricks";
import { Suspense } from "react";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<Suspense>
<FormbricksProvider />
</Suspense>
<body>{children}</body>
</html>
);
}
Pages directory
// other import
import { useRouter } from "next/router";
import { useEffect } from "react";
import formbricks from "@formbricks/js";
if (typeof window !== "undefined") {
formbricks.setup({
environmentId: "<environment-id>",
appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
});
}
export default function App({ Component, pageProps }: AppProps) {
const router = useRouter();
useEffect(() => {
// Connect next.js router to Formbricks
const handleRouteChange = formbricks?.registerRouteChange;
router.events.on("routeChangeComplete", handleRouteChange);
return () => {
router.events.off("routeChangeComplete", handleRouteChange);
};
}, []);
return <Component {...pageProps} />;
}
Required Customizations
Name | Type | Description |
---|
environment-id | string | Formbricks Environment ID. |
app-url | string | URL of the hosted Formbricks instance. |
First, initialize the Formbricks SDK to run only on the client side. To track page changes, register the route change event with the Next.js router.
Next, go to the Validate Your Setup section to verify your setup!
Vue.js
Integrating the Formbricks SDK with Vue.js is easy. We’ll ensure the SDK is only loaded and used on the client side, as it’s not meant for server-side use.
npm install @formbricks/js
import formbricks from "@formbricks/js";
if (typeof window !== "undefined") {
formbricks.setup({
environmentId: "<environment-id>",
appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
});
}
export default formbricks;
// other imports
import formbricks from "@/formbricks";
const app = createApp(App);
app.use(router);
app.mount("#app");
router.afterEach((to, from) => {
if (typeof formbricks !== "undefined") {
formbricks.registerRouteChange();
}
});
Required Customizations
Name | Type | Description |
---|
environment-id | string | Formbricks Environment ID. |
app-url | string | URL of the hosted Formbricks instance. |
Now, visit the Validate Your Setup section to verify your setup!
React Native
Install the Formbricks React Native SDK using one of the package managers, i.e., npm, pnpm, or yarn.
npm install @formbricks/react-native
pnpm add @formbricks/react-native
yarn add @formbricks/react-native
Now, update your App.js/App.tsx
file to initialize Formbricks:
// other imports
import Formbricks from "@formbricks/react-native";
const config = {
environmentId: "<environment-id>",
appUrl: "<app-url>", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
};
export default function App() {
return (
<>
{/* Your app content */}
<Formbricks initConfig={config} />
</>
);
}
Required Customizations
Name | Type | Description |
---|
environment-id | string | Formbricks Environment ID. |
app-url | string | URL of the hosted Formbricks instance. |
Now, visit the Validate Your Setup section to verify your setup!
Swift
Install the Formbricks iOS SDK using the following steps:
Swift Package Manager
-
In Xcode choose File → Add Packages…
-
Enter your repo URL (e.g.
https://github.com/formbricks/ios.git
)
-
Choose version rule (e.g. “Up to Next Major” starting at
1.0.0
).
-
Import in your code:
CocoaPods
-
Add the following to your
Podfile
:
platform :ios, '16.6'
use_frameworks! :linkage => :static
target 'YourTargetName' do
pod 'FormbricksSDK', '1.0.0 (or the latest version)'
end
-
Run
pod install
in your project directory
-
Import in your code:
Now start using FormbricksSDK
import FormbricksSDK
// 1. Build your config (you can also inject userId + attributes here)
let config = FormbricksConfig.Builder(
appUrl: "https://your‑app.bricks.com", // use PUBLIC_URL if you are using multi-domain setup, otherwise use WEBAPP_URL
environmentId: "YOUR_ENV_ID"
)
.setLogLevel(.debug)
.build()
// 2. Initialize the SDK (once per launch)
Formbricks.setup(with: config)
// 3. Identify the user
Formbricks.setUserId("user‑123")
// 4. Track events
Formbricks.track("button_pressed")
// 5. Set or add user attributes
Formbricks.setAttribute("blue", forKey: "favoriteColor")
Formbricks.setAttributes([
"plan": "pro",
"tier": "gold"
])
// 6. Change language (no userId required):
Formbricks.setLanguage("de")
// 7. Log out (no userId required):
Formbricks.logout()
// 8. Clean up SDK state (optional):
Formbricks.cleanup(waitForOperations: true) {
print("SDK torn down")
}
Required Customizations
Name | Type | Description |
---|
environment-id | string | Formbricks Environment ID. |
app-url | string | URL of the hosted Formbricks instance. |
Now, visit the Validate Your Setup section to verify your setup!
Android
Install the Formbricks Android SDK using the following steps:
Installation
Add the Maven Central repository and the Formbricks SDK dependency to your application’s build.gradle.kts
:
repositories {
google()
mavenCentral()
}
dependencies {
implementation("com.formbricks:android:1.0.0") // replace with latest version
}
Enable DataBinding in your app’s module build.gradle.kts:
android {
buildFeatures {
dataBinding = true
}
}
Usage
// 1. Initialize the SDK
val config = FormbricksConfig.Builder(
"https://your-formbricks-server.com",
"YOUR_ENVIRONMENT_ID"
)
.setLoggingEnabled(true)
.setFragmentManager(supportFragmentManager)
.build()
// 2. Setup Formbricks
Formbricks.setup(this, config)
// 3. Identify the user
Formbricks.setUserId("user‑123")
// 4. Track events
Formbricks.track("button_pressed")
// 5. Set or add user attributes
Formbricks.setAttribute("test@web.com", "email")
Formbricks.setAttributes(mapOf(Pair("attr1", "val1"), Pair("attr2", "val2")))
// 6. Change language (no userId required):
Formbricks.setLanguage("de")
// 7. Log out:
Formbricks.logout()
Required Customizations
Name | Type | Description |
---|
environment-id | string | Formbricks Environment ID. |
app-url | string | URL of the hosted Formbricks instance. |
Validate your setup
Once you’ve completed the steps above, validate your setup by checking the Setup Checklist in the Settings. The widget status indicator should change from this:
To this:
The debug mode is only available in the JavaScript SDK and works exclusively in the browser. It is not
supported in mobile SDKs such as React Native, iOS, or Android.
Enabling debug mode in your browser can help troubleshoot issues with Formbricks. Here’s how to activate it and what to look for in the logs.
Activate Debug Mode
To enable debug mode, add ?formbricksDebug=true
to your app’s URL (e.g., https://example.com?formbricksDebug=true)
.
View Debug Logs
- Open your browser’s developer tools:
-
Google Chrome/Edge: Press
F12
or right-click and select “Inspect” > “Console”.
-
Firefox: Press
F12
or right-click and select “Inspect Element” > “Console”.
-
Safari: Press
Option + Command + C
to open developer tools and go to the “Console” tab.
Common Use Cases
Debug mode is helpful for:
-
Verifying Formbricks initialization.
-
Identifying issues with survey triggers.
-
Troubleshooting unexpected behavior.
Debug Log Messages
Logs provide insights into:
-
API calls and responses.
-
Survey triggers and form interactions.
-
Initialization errors.
If you’re stuck, visit GitHub Discussions for assistance.