Mobile App 📱 Integration Guide

The best way to integrate FeatureCat into your mobile app is to embed the public board in a web view, which is supported on all major platforms. 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 Board Session.

Option A: Board Session (recommended)

The Board Session is a way to generate a one-time URL that is valid for a short period of time. All it takes is a single HTTP POST request, that you configure with your user’s data and authenticate with your product’s secret board token. The response will contain a unique URL that you can open in a web view.

Depending on your platform, we usually recommend creating the board session upon the user’s navigation to the public board in the app, and then immediately loading the URL in a web view.

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 app, and configure it as follows:

• Set the URL to https://appity.featurecat.app/auth/board_session (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)
    "board_locale": "en", // locale for the board (optional)
    "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)
    "metadata": {
        "session_count": 200, // examplary metadata 
        "user_plan": "Professional" // examplary metadata
    }
}

As the response to this request, you’ll receive a board session object, which contains the URL to the public board, that you can open in a web view.

// Example board session object response

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

Step 2: Open the public board in a web view

Once you have received the board session object, you can open the URL in a web view. The board session is valid for 8 hours, so you should create the board session immediately before opening the web view. As discussed above, you should couple this to the user’s navigation to the public board in your app.

Example implementations

This setup is supported by all major platforms.

• For example, on iOS, you could use URLSession to create the Board Session, and WKWebView to open the URL.
• On Android, you could use a library like OkHttp to create the Board Session, and WebView to open the URL.
• With Flutter, you could use http to create the Board Session, and webview_flutter to open the URL.
• With React Native, you could use Fetch to create the Board Session, and react-native-webview to open the URL.

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.

One important distinction to the Board Session is that FeatureCat Authentication with a JWT only requires a single HTTP GET request, which makes it easier to integrate on some platforms. This also enables you to have the user visit a URL on your server, and then redirect the user to the public board with the signed JWT, which can be useful if you want to authenticate the user on your own server instead of the user’s device.

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: Open the public board in a web view with the JWT

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 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

• On iOS with Swift, you could use SwiftJWT.
• On Android, you could use Java JWT.
• With Flutter, you could use Dart JWT.

Option C: Direct POST

If the platform you are using supports opening a web view with a POST request (e.g. WKWebView on Apple platforms), you can also configure the POST request direcly on your device. Using this setup, upon opening the web view with a request with HTTP method POST, the user will be authenticated and redirected to the public board.

Step 1: Create the POST request

To create the POST request, 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 app, and configure it as follows:

• Set the URL to https://appity.featurecat.app/auth (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)
}

Step 2: Open the POST request with a web view

Now that you have the POST request, you can open it in a web view. FeatureCat will authenticate the user and redirect them to the public board.

There is an exemplary integration in Swift for iOS on Github that should make it even easier for you.

FAQ

How do I get the user’s unique identifier?

If you have a user account system, you can use the user’s account ID, or a derivative (e.g. a hashed version, as long as it is consistent). If you don’t have a user account system, you can use a UUID that you generate and store locally on the user’s device.

Can I authenticate the user on my own server instead of the user’s device?

Yes, you can. With Board Session Authentication, you’ll need to create the Board Session on your server, and then send the board session URL to the user’s device.

When using JWT Authentication, you can also create the JWT on your server, and send it to the user’s device. Alternatively, you can open the web view with a URL pointing to a resource on your own server, create the JWT on your server, and redirect the user to the public board with the JWT.