Overview

Setting up SDK to automatically authenticate users to Featurebase and sync their data is one of the most impactful setups you can do for your support & feedback management.

Automatic auth ensures your users are seamlessly logged in and don’t have to create a separate Featurebase account to submit feedback or interact with your team.

Should you use the SDK?

Why should you use it?

• User data sync – enables you to sync your customer data to Featurebase to see who is behind customer interactions, create segments, restrict their access, and better prioritize feedback.

• Seamless authentication – the SDK identification functionality provides a flexible way to authenticate users coming from your app to your Featureaseb portal, Help center, Changelog, Survey widgets, etc. But not in your Messenger! Messenger requires booting it separately with the correct data.

When should you not use it?

• Only using the Messenger widget – if you are only using the support Messenger widget, then this is not needed, as the Messenger already handles this functionality on its own.

• Already use SSO – if you already use SSO, then you can instead authenticate the user from a widget by passing a JWT directly to its initialization function.

• Don’t care about auto-auth – If you do not care about authenticating users to your Featurebase portal, then you don’t need to set this up. However, we strongly suggest automatically authenticating users.

Installing the SDK

To set it up, start by importing our SDK using any of the code examples below:

Example
HTML
Next.js
Vue
Svelte
Copy
<!-- Import Featurebase SDK -->
<script>
  !(function (e, t) {
    const a = "featurebase-sdk";
    function n() {
      if (!t.getElementById(a)) {
        var e = t.createElement("script");
        (e.id = a),
        (e.src = "https://do.featurebase.app/js/sdk.js"),
        t.getElementsByTagName("script")[0].parentNode.insertBefore(
          e,
          t.getElementsByTagName("script")[0]
        );
      }
    }
    "function" != typeof e.Featurebase &&
      (e.Featurebase = function () {
        (e.Featurebase.q = e.Featurebase.q || []).push(arguments);
      }),
    "complete" === t.readyState || "interactive" === t.readyState
      ? n()
      : t.addEventListener("DOMContentLoaded", n);
  })(window, document);
</script>

<!-- Identify user in Featurebase -->
<script>
  Featurebase(
    "identify",
    {
      // Each 'identify' call should include an "organization"
      // property, which is your Featurebase board's name before the
      // ".featurebase.app".
      organization: "yourorg",
      // Required fields. Replace with your customers data.
      email: "yourcustomer@example.com",
      name: "Your Customer",
      userId: "123456",
      // Both email and userId should be provided when possible
      // At minimum, either email or userId must be present

      // Optional - add a profile picture to the user
      profilePicture: "https://example.com/images/yourcustomer.png",
      
      // Add any optional custom attributes - must be configured from settings to work
      title: "Product Manager",
      plan: "Premium",
      number: 123,

      // locale: "en", // optional, provide expected language for user
      // Optional - add user company information as needed
      companies: [
        {
          id: "987654321", // required
          name: "Business Inc. 23", // required
          monthlySpend: 500, // optional
          createdAt: "2023-05-19T15:35:49.915Z", // optional
          // Custom company attributes - make sure to configure from settings to work
          industry: "Fintech",
          location: "Canada",
        },
      ], // optional
    },
    (err) => {
      // Callback function. Called when identify completed.
      if (err) {
        // console.error(err);
      } else {
        // console.log("Data sent successfully!");
      }
    }
  );
</script>

Required by default: Secure your installation

Please follow this guide → for the user to be authenticated.

If you do not follow the guide above, you must disable the secure login requirement for the example code to work here.

⚠️ Disabling secure login is ok for local testing, but it should never be used for production when using Featurebase with end-user data for sensitive data.

Also required for data to appear: Configure custom attributes

To make sure custom attributes are added for users, please make sure to configure them by following this guide →

Automatic authentication for the web portal

The auto authentication will automatically sign the user in with no other actions needed if you:

• Have a custom domain set up

• Are you calling the identify function on the same TLD (Top-level domain) as your Featurebase web portal custom domain

Example: If you have a custom domain called feedback.yourdomain.com that points to your Featurebase web portal, then you need to call identify from e.g. yourdomain.com or anyothersubdomain.yourdomain.com for the user to be automatically signed in from feedback.yourdomain.com

Workaround: If you are not following the requirements above, you can add the data-featurebase-link attribute to all links on your website that link to your Featurebase portal.

This will ensure that users are automatically logged in even when a session can not be created.

Example
HTML
Copy
<a data-featurebase-link href="https://yourorg.featurebase.app" target="_blank" rel="noopener noreferrer">
  Give feedback
</a>

Automatic authentication for widgets

Our SDK will smartly keep and share the state you provided in the identify function with all widgets to automatically authenticate and associate data about the user.

Next, explore and set up widgets here: What are in-app widgets?

Advanced use cases

Associate session-specific data about the user

You can attach metadata to user feedback to provide additional context about the user’s session (e.g. App version, Device type, etc) from all the widgets that support feedback posting & the public portal.

Please check out the What is metadata for posts? for this.

Actions after authentication

You may want to perform some actions once a user has been successfully identified.

Each identify call takes a callback parameter that runs once the identify function is finished.

Example
JavaScript
Copy
function featurebaseIdentifyCallback(err) {
  if (err) {
    console.log("Could not identify user") return
  }
  // Perform follow-up actions here.
}

Featurebase("identify", {
  // Required. Replace with your customers data.
  email : "yourcustomer@example.com",
  name : "Your Customer",
  userId: "123456",
}, featurebaseIdentifyCallback);

Troubleshooting & common issues