User Guide

Here is where you can find information on how to use ClearFlask. If you are still having issues, feel free to email us.

Check out our API.
Similar



Installation

To get the basic setup of ClearFlask, start with the Creation Wizard in the dashboard by clicking "New project". Choose the options that best suit you. Don't worry, everything can be changed later in more detail.

Further customization
Take a moment to explore the powerful "Project Settings". If anything is unclear, please submit an idea to us for improvement. You may want to adjust settings in these areas:


Credit System
If you are interested in using the Credit System, we highly encourage you to reach out to us as we can give you suggestions on how to use it most effectively.
If you feel you are comfortable, check out the Credit System article

Invite moderators
Invite users to be your moderators for you project. Allow them to populate ideas and get familiar with the tool.

Pre-populate content
For a smooth start, we suggest adding any ideas of your own.
If you are already using an existing planning tool or feedback platform, reach out to us for migration options.

Embed in your website/app
You have a few options on how to direct your users to give you feedback:

  • Post a link to your <subdomain>.clearflask.com page
  • Embed in an IFrame

You can else embed a particular page be prefixing the path with "/embed". As an example, this article can be embedded like this:

Onboarding users

Let's setup how you want your users to sign-up.

Feedback value VS onboarding friction
Feedback from a user that signs up anonymously is less valuable than a user that has asked to be notified when the feedback is addressed.
At the same time, asking users for their email address will discourage some to leave any feedback at all.

Recommendation
You want to have the least amount of friction when asking for your users contact. The recommended options from most recommended are:
  1. Single Sign-On
  2. Email restricted to domain
  3. Browser Notifications
  4. Email
  5. Anonymous

Single Sign-On (SSO)

Email restricted to domain

Browser Notifications
Also known as Web Push, Browser Notifications are a fairly recent feature of Web Browsers that allow websites to send you push notifications.

Caveats:
  • The user will not be able to log in from another browser unless they add an email to the account.
  • If the user disables Web Push, they will lose access to the account completely.
  • Not all browsers support Web Push, we recommend to enable Anonymous login as a fallback if Web Push is not supported by current browser.

Email
This is the standard way to onboard your users. As long as a user has an email address, they can sign up.

We recommend not to ask users to set a password as it adds friction. They will be able to set a password later in account settings. Without a password, users are still able to log in later by receiving a one-time code to their email address.

If you plan to use your users' email addresses, you may choose the option of verifying the address before they're allowed to finish creating an account. This ensures the email addresses are valid. It is not recommended in most cases as it adds the most amount of friction.

Anonymous
Lastly, you can choose to let users sign-up anonymously. On one hand, this option has the least amount of friction, consider whether anonymous feedback is valuable to you.

How to setup OAuth

If you want your users to sign-in with an external provider, you have an option to use OAuth.

If your service already manages user accounts, we recommend using Single Sign-On instead as it has a seamless, better user experience than OAuth provides.

To setup OAuth, visit your provider to get started. Your provider will require from you a Redirect URL for security measures. You should provide one or both of the following depending on whether you are using subdomain or domains on ClearFlask:
https://<subdomain>.clearflask.com/oauth
https://<domain>/oauth

Once you have all the details, head on over to the Onboarding page and scroll down to OAuth to set it up.

Short button title - User visible text
Client ID - Given to you by your provider
Client Secret - Given to you by your provider (We will keep this private)
Authorize URL - Authorization URL your users will be redirected to.
Token URL - Token URL our backend server will retrieve to exchange an authorization to an access token.
Request Scope - Specify the minimum scope required to fetch user ID, email and name.
User Profile URL - This URL will be retrieved using the token from the previous step to fetch user details
GUID/Name/Email Path - a JsonPath expression that helps us determine how to parse the User Profile response from previous step.

Below is a list of common providers to get you started quickly.

Google
  • Client ID / Client Secret - Can be setup here
  • Authorize URL - "https://accounts.google.com/o/oauth2/v2/auth"
  • Token URL - "https://www.googleapis.com/oauth2/v4/token"
  • Request Scope - "profile email"
  • User Profile URL - "https://www.googleapis.com/oauth2/v2/userinfo"
  • GUID Path- "id"
  • Name Path- "name"
  • Email Path - "email"

GitHub
  • Client ID / Client Secret - Can be setup here
  • Authorize URL - "https://github.com/login/oauth/authorize"
  • Token URL - "https://github.com/login/oauth/access_token"
  • Request Scope - "user:email"
  • User Profile URL - "https://api.github.com/user"
  • GUID Path- "id"
  • Name Path- "name, login"
  • Email Path - "email"

Facebook
  • Client ID / Client Secret - Can be setup here
  • Authorize URL - "https://www.facebook.com/v3.2/dialog/oauth"
  • Token URL - "https://graph.facebook.com/oauth/access_token"
  • Request Scope - "public_profile email"
  • User Profile URL - "https://graph.facebook.com/me?fields=name,email"
  • GUID Path- "id"
  • Name Path- "name"
  • Email Path - "email"

Gitlab
  • Client ID / Client Secret - Can be setup here
  • Authorize URL - "https://gitlab.com/oauth/authorize"
  • Token URL - "https://gitlab.com/oauth/token"
  • Request Scope - "read_user"
  • User Profile URL - "https://gitlab.com/api/v4/user"
  • GUID Path- "id"
  • Name Path- "name"
  • Email Path - "email"

Discord
  • Client ID / Client Secret - Can be setup here
  • Authorize URL - "https://discordapp.com/api/oauth2/authorize"
  • Token URL - "https://discordapp.com/api/oauth2/token"
  • Request Scope - "identify email"
  • User Profile URL - "https://discordapp.com/api/users/@me"
  • GUID Path- "id"
  • Name Path- "username"
  • Email Path - "email"

Twitch
  • Client ID / Client Secret - Can be setup here
  • Authorize URL - "https://id.twitch.tv/oauth2/authorize"
  • Token URL - "https://id.twitch.tv/oauth2/token"
  • Request Scope - "user:read:email"
  • User Profile URL - "https://api.twitch.tv/helix/users"
  • GUID Path- "data[0].id"
  • Name Path- "data[0].display_name"
  • Email Path - "data[0].email"

Microsoft Azure AD
  • Client ID / Client Secret - Visit here -> Azure Active Directory -> App Registrations.
  • Authorize URL - "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize"
  • Token URL - "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"
  • Request Scope - "User.Read"
  • User Profile URL - "https://graph.microsoft.com/v1.0/me"
  • GUID Path- "id"
  • Name Path- "displayName"
  • Email Path - "mail"

How to setup Single Sign-On (SSO)

SSO allows users to seamlessly login with their existing account provided by your website/app without having to create an additional account on ClearFlask.

There are two ways how your users can log in and it's best to complete both of them for best experience:

#1 Log in by link

(Optional, but, recommended)

  1. Your user visits your website/app and now they want to provide you feedback on ClearFlask.
  2. Your server will generate a JWT using a secret key found here and pass it along to the user.
  3. The user will click a link to ClearFlask with the JWT embedded as a parameter: https://<your_subdomain>.clearflask.com/?token=<jwt_token>
  4. User is seamlessly logged in automatically and can post on ClearFlask

Example: Our own feedback page works the same way, head over to the dashboard and hover over the "Feedback" link in the menu. Notice the link contains a JWT token that will automatically log you in when you click it.

#2 Log in with redirect:


  1. Your user visits ClearFlask directly to provide you with feedback.
  2. When user performs an action that requires an account, a prompt will be shown to log in.
  3. An option to use SSO will be shown upon which a popup will open with your website's log-in page.
  4. After signing in, the popup redirects back to ClearFlask to complete the sign-in and continue with the user action.

Example: Our own feedback page works the same way, if you visit our feedback account page, sign out if you're already signed in and click the account icon at the top right corner. You will be asked to sign-in as an "Existing customer" which will open up a sign-in popup.


Generating JWT Tokens

Depending on your server architecture, a library may already exist for JWTs that can be found here that implements the JWT specification.

The supported claims you should be setting are:
guid (String, required)
email (String, optional)
name (String, optional)
In addition, you should be setting:
expiry (optional)
issuedAt (optional)
The issuedAt date is important for invalidating all tokens prior to a certain date in some cases.

The JWT should use HS256 with GZIP and DEFLATE.

Java example:
Jwts.builder()
    .setIssuedAt(now)
    .setExpiration(expiration)
    .addClaims(ImmutableMap.of(
            "guid", account.getClearFlaskGuid(),
            "email", account.getEmail(),
            "name", account.getName()))
    .signWith(new SecretKeySpec(
            config.secretKey().getBytes(Charsets.UTF_8),
            SignatureAlgorithm.HS256.getJcaName()))
    .compressWith(new GzipCompressionCodec())
    .compact();

Creating a custom sign-in page for redirect

Either create a custom sign-in page or re-use your existing sign-in page that will detect a callback url from ClearFlask. Type in the sign-in page url in your dashboard. Remember that <return_uri> will be replaced by the callback url.

Once a user opens up the sign-in page, first let them sign-in if they're not already. At this point, your server should have generated a JWT and returned it back to the client.

Once the user is signed in, read and verify the callback url domain is either <your_app>.clearflask.com or a custom domain you have setup with us.

Now you can safely redirect back to the callback url with the jwt appended at the end like so:
<return_uri>?token=<jwt_token>

Need help?
Feel free to reach out to us for additional help.