Developer Docs

SDK: App Survey

Overview

The Formbricks JS SDK is a 2-in-1 SDK for seamlessly integrating both App Surveys and Website Surveys into your projects. In this section, we'll explore how to leverage the SDK specifically for app surveys. It’s available on npm here.

Install

npm install @formbricks/js

Methods

Initialize Formbricks

Initialize the Formbricks JS Client for app surveys where you pass the userId (creates a user if not existing in Formbricks) to attribute & target the user based on their actions.

import formbricks from "@formbricks/js/app";

formbricks.init({
  environmentId: "<your-environment-id>", // required
  apiHost: "<your-api-host>", // required
  userId: "<user-id>" // required
});

The moment you initialise Formbricks, your user will start seeing surveys that get triggered on simpler actions such as on New Session, Page Exit, & other custom actions!

if (window !== undefined) {
    formbricks.init({
        environmentId: "<your-environment-id>",
        apiHost: "<your-api-host>", 
        userId: "<user-id>"
    });
} else {
    console.error("Window object not accessible to init Formbricks");
}

Set Attribute

You can set custom attributes for the identified user. This can be helpful for segmenting users based on specific characteristics or properties. To learn how to set custom user attributes, please check out our User Attributes Guide.

formbricks.setAttribute("Plan", "Paid");

Track Action

Track user actions to trigger surveys based on user interactions, such as button clicks or scrolling:

formbricks.track("Clicked on Claim");

Logout

To log out and deinitialize Formbricks, use the formbricks.logout() function. This action clears the current initialization configuration and erases stored frontend information, such as the surveys a user has viewed or completed. It's an important step when a user logs out of your application or when you want to reset Formbricks.

formbricks.logout();

After calling formbricks.logout(), you'll need to reinitialize Formbricks before using any of its features again. Ensure that you properly reinitialize Formbricks to avoid unexpected errors or behavior in your application.

Reset

Reset the current instance and fetch the latest surveys and state again:

formbricks.reset();

Register Route Change:

Listen for page changes and dynamically show surveys configured via no-code actions in the Formbricks app:

formbricks.registerRouteChange();

Debug Mode

To enable debug mode in Formbricks, add ?formbricksDebug=true to your app’s URL.

For example, if you’ve integrated Formbricks JS to your app hosted at https://example.com, then change the URL to https://example.com?formbricksDebug=true and refresh the page, now view the console logs to see the debug mode live in action.

This activates detailed debug messages in the browser console, providing deeper insights into Formbricks' operation and potential issues.

Troubleshooting

In case you don’t see your survey right away, here's what you can do. Go through these to find the error fast:

Formbricks Cloud and your app are not connected properly.

Go back to app.formbricks.com or your self-hosted instance's URL and go to the Setup Checklist in the Settings. If the status is still indicated as “Not connected” your app hasn't yet pinged the Formbricks Cloud:

How to fix it:

1. Check if your app loads the Formbricks widget correctly.
2. Make sure you have debug mode enabled in your integration and you should see the Formbricks debug logs in your browser console while being in your app (right click in the browser, Inspect, switch to the console tab). If you don’t see them, double check your integration.

Survey not loaded

If your app is connected with Formbricks Cloud, the survey might have not been loaded properly. Check the debug logs and search for the list of surveys loaded. It should look like so:

How to fix it:

The widget only loads surveys which are public and in progress. Go to Formbricks Cloud and to the Survey Summary page. Check if your survey is live:

Survey not triggered

If the survey is loaded by the widget it might not have been triggered properly.

How to fix:

1. Open your local app in an incognito tab or window. The New Session event is only fired if a user was inactive for 60 minutes or was logged out of Formbricks via formrbicks.logout().
2. Check the debug logs for “Event ‘New Session” tracked”. If you see it in the logs and the survey still did not get displayed, please let us know.

Survey not displayed in HTML page

If the survey is loaded by the widget in the HTML page, try the below steps:

How to fix:

1. Make sure you have added the script in the head of the HTML page.
2. Verify that you have set the <environment-id> and <host> as per your Formbricks instance.
3. Verify that you have the latest version of the JS Package.
4. Check the debug logs to see if you still see any errors.

Cannot read undefined of .init()

If you see this error in the console, it means that the Formbricks JS package is not loaded properly.

How to fix:

1. Update to the latest version of the JS Package.
2. Verify this wherever you call initialise the Formbricks instance in your code.
3. It should now start working.

If you are still facing issues, please Open an Issue on GitHub or join our Discord! We’re more than happy to help you get started 😊