Open Direct Integration Guide

The easiest way to integrate FeatureCat into your web app is open the public board in a new window or tab. 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 launching FeatureCat for you - all that’s needed is to add a small snippet to a website.

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

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 'identify' to identify the user
-->
<script>
  FeatureCat.init('identify', {
    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: Launch the public board

Once the FeatureCat.JS SDK is initialized, you can launch the public board in a new window or tab by calling FeatureCat.launch(). This will open the public board in a new window or tab, and automatically authenticate the user.

You can call the method from anywhere after the FeatureCat.JS SDK is initialized, e.g. from a button click handler.

<!-- 
  Launch the public board in a new window or tab
  (after the FeatureCat.JS SDK is initialized)
-->
<button onclick="FeatureCat.launch();">Launch FeatureCat</button>

That’s it!

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: JWT Authentication

With Signed JSON Web Tokens (JWT), you can create a secure token that is signed with your product’s secret board token. This token can then be used to authenticate the user on the public board.

FeatureCat Authentication with a JWT only requires a single HTTP GET request, which allows you to create the JWT on your own server, and then construct the full public board URL in a single redirect on your server.

Step 1: Create the JWT

For JWT Authentication, you’ll need to create the JWT, which is basically just transforming the user’s data (similar to the JSON body of the Board Session) into a long string, and signing it with your product’s secret board token. That JWT is then passed to FeatureCat as a query parameter in the URL.

All major platforms have libraries that can create a JWT for you (see below). To create the JWT, 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)

Similar to the Board Session, the JWT must contain at least the board session’s board_mode and the user’s identifier, and can optionally contain additional User Data. Please not that due to constraints with the maximum lengths of a URL, additional user metadata is not supported with JWT Authentication.

// Example JSON body before creating the JWT

{
    "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)
}

That JSON then acts as the payload, which can then be encoded and signed with your product’s secret board token.

FeatureCat is using the RFC 7519 OAuth JSON Web Token (JWT) standard. The token must be signed with the HMAC SHA256 (HS256) algorithm, and the secret board token must be used as the signing key.

Step 2: Redirect to the public board

Now that you have the JWT, you can include it with the query parameter sso_token in the URL to the public board on the /auth route, using a regular GET request.

So if, for example, your public board URL is https://appity.featurecat.app, and your JWT is $YOUR_JWT, you should have the user open the URL https://appity.featurecat.app/auth?sso_token=$YOUR_JWT (in reality, your JWT will be much longer).

Example libraries for creating a JWT

• Ruby: ruby-jwt
• Python: PyJWT
• NodeJS: jsonwebtoken
• PHP: firebase/php-jwt