Web Widget 🌐 Integration Guide

The best way to integrate FeatureCat into your web app is to embed it as a widget. This allows you to integrate FeatureCat into your app without having to redirect your users to a different page, and you can make it feel like a native part of your app.

Users need to be authenticated to vote on features, submit feedback, and leave comments, so you’ll need to integrate FeatureCat Authentication. The recommended way (as per the Integration Overview) is to use the FeatureCat.JS SDK.

Option A: FeatureCat.JS SDK (recommended)

The FeatureCat.JS SDK is a small Javascript SDK you can embed into your web app, which can handle all the work of Authentication and embedding for you - all that’s needed is to add a small snippet to a website.

It can also handle feedback submission and opening the public board on a new window or tab, but this guide will focus on embedding the public board as a widget via an iframe.

Step 1: Add the FeatureCat.JS SDK to your website

To initialize the FeatureCat.JS SDK, you’ll need the following information:

• Your chosen public board URL (e.g. appity, with the board being available on https://appity.featurecat.app)
• Your product’s secret board token (available in your product settings)
• A unique identifier for your user, that you can access from within your app (e.g. a UUID)
• A way to create a hash using the HMAC SHA-256 algorithm, combining your product’s secret board token and the user’s unique identifier (see examples for different languages below)

Once you have this information, you can add the FeatureCat.JS SDK to your website by adding the following snippet to your website’s HTML. You can also add it directly with the configuration in the next step.

<!-- Add the FeatureCat.JS SDK to your website's HTML -->
<script src="https://sdk.featurecat.com/v2/featurecat.js"></script>

Step 2: Initialize the FeatureCat.JS SDK

Before the FeatureCat.JS SDK can load and embed the widget, you’ll first need to initialize it with the user’s information for Authentication. To securely authenticate your user, you’ll need to sign the user’s unique identifier with your product’s secret board token using the HMAC SHA-256 algorithm, passing it as the key and data respectively. You can then pass this signature and the user’s identifier, as well as other user data, to the FeatureCat.JS SDK.

When initializing the FeatureCat.JS SDK, you’ll need at least the user’s identifier and the previously generated signature, as well as the board_mode (e.g. feedback) and the board_url (e.g. appity), and can optionally pass additional User Data.

<!-- 
  Add the FeatureCat.JS SDK to your website's HTML
 (unless you've already done this in Step 1) 
-->
<script src="https://sdk.featurecat.com/v2/featurecat.js"></script>

<!-- 
  Initialize the FeatureCat.JS SDK, 
  passing 'emebed' to launch it into widget embed mode 
-->
<script>
  FeatureCat.init('embed', {
    board_url: 'appity', // your product's public board URL (required)
    board_mode: 'feedback',  // configuration for feature voting and feedback (required)
    identifier: "abcd1234", // user unique identifier (required)
    signature: "a1b2c3d4e5", // your previously generated signature (required)
    name: "Jane Doe", // user name (optional)
    email: "[email protected]", // user email address (optional)
    revenue: 3.50, // user revenue (optional)
    user_since: "2023-05-03T09:25:48Z", // user first usage date (optional)
    app_version: "1.2.3", // user app version (optional)
    region: "US", // user region (optional)
  });
</script>

Step 3: Add the embed element to your website

Once the FeatureCat.JS SDK is initialized, it will automatically load and embed the widget into your website via an iframe. To position this widget on your website, you can add a div element with the data-featurecat-embed dataset to your website’s HTML. The FeatureCat.JS SDK will then automatically add the iframe element to this div element.

<!-- 
  Add this div element to your website's HTML,
  and the FeatureCat.JS SDK will automatically add the widget to it
-->

<div data-featurecat-embed></div>

That’s it!

Finally, you can style the widget to fit your website’s design. Make sure your public board’s background color matches the widget’s surrounding color, and choose the correct theme for the widget (light, dark, or adaptive).

Hash function examples

The following examples show how to create a hash using the HMAC SHA-256 algorithm, combining your product’s secret board token ($BOARD_TOKEN) and the user’s unique identifier ($USER_IDENTIFIER). You can use these examples to create the signature for the FeatureCat.JS SDK.

Ruby

require 'openssl'

signature = OpenSSL::HMAC.hexdigest('sha256', $BOARD_TOKEN, $USER_IDENTIFIER)

Python

import hashlib
import hmac
import base64

message = bytes($USER_IDENTIFIER, 'utf-8')
secret = bytes($BOARD_TOKEN, 'utf-8')

signature = hmac.new(secret, message, digestmod=hashlib.sha256).hexdigest()

NodeJS:

import crypto from 'crypto'

const signature = crypto
  .createHmac('sha256', $BOARD_TOKEN)
  .update($USER_IDENTIFIER)
  .digest('hex')

PHP

$signature = hash_hmac('sha256', $USER_IDENTIFIER, $BOARD_TOKEN);

Option B: Server-generated iframe Board Session

The Board Session is a way to generate a one-time URL that is valid for a short period of time. If you don’t want to use the FeatureCat.JS SDK, you can generate an iframe-specific Board Session on your server, and then pass the session URL to the client, which can then be embedded into your website via an iframe.

Step 1: Create the Board Session

To create the Board Session, you’ll need the following information:

• Your chosen public board URL (e.g. appity, with the board being available on https://appity.featurecat.app)
• Your product’s secret board token (available in your product settings)
• A unique identifier for your user, that you can access from within your app (e.g. a UUID)

Then you’ll need to create a HTTP request in your backend, and configure it as follows:

• Set the URL to https://appity.featurecat.app/auth/board_session/iframe (and replace appity with your chosen public board URL)
• Set the HTTP Method to POST
• Set the HTTP Header Field Authorization to Bearer $token (where $token is your product’s secret board token)
• Set the HTTP Content-Type to application/json
• Create a JSON object with your user’s data and session configuration (see below) and set it as the HTTP Body

The JSON body must contain at least the board session’s board_mode and the user’s identifier, and can optionally contain additional User Data.

// Example JSON body of the HTTP request to create a board session

{
    "board_mode": "feedback", // configuration for feature voting and feedback (required)
    "identifier": "abcd1234", // user unique identifier (required)
    "name": "Jane Doe", // user name (optional)
    "email": "[email protected]", // user email address (optional)
    "revenue": 3.50, // user revenue (optional)
    "user_since": "2023-05-03T09:25:48Z", // user first usage date (optional)
    "app_version": "1.2.3", // user app version (optional)
    "region": "US", // user region (optional)
}

As the response to this request, you’ll receive a board session object, which contains the URL to the public board, which you can then pass to the client to open in an iframe.

// Example board session object response

{
    
    "object": "board_session",
    "created": "2023-05-03T11:44:42Z",
    "board_mode": "feedback", 
    "user_identifier": "abcd1234",
    "url": "http://appity.feature/front/iframe?session_token=$UNIQUE_SESSION_ID"
}

Step 2: Open Session URL in an iframe

Once you have received the board session object, you can pass the URL to your frontend and open it in an iframe, setting the src attribute to the session URL. We recommend to set the sandbox attribute to allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-top-navigation allow-top-navigation-by-user-activation allow-modals to prevent the iframe from accessing your website’s DOM.

<iframe 
  name="ifr_featurecat" 
  width="100%" 
  height="800px" 
  id="featurecat-iframe" 
  referrerpolicy="origin" 
  sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-top-navigation allow-top-navigation-by-user-activation allow-modals" 
  src="http://appity.feature/front/iframe?session_token=$UNIQUE_SESSION_ID">
</iframe>