ClearFlask
FeedbackRoadmapChangelog

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

Defining Content types

Whether you want to gather user feedback, show off your blog or create a Q&A, you need to define the rules of your content.

User Creatable
First thing to decide is whether the content can be created by users or locked down to Moderators.

Feedback
Next up, choose the appropriate type of feedback and discussion you want to achieve including:

  • Voting (and/or downvoting)
  • Expressions
  • Funding
  • Commenting

Workflow
Some content may go through stages of progression such as a development task. (idea -> implementation -> deployment)
For this, you should define a series of states as part of your workflow.
Each state may allow or disallow feedback. For example a completed development task shouldn't receive any more upvotes.

Tagging
Use tagging to differentiate sub-types of your content. You can filter content by tags when searching. You can also force a specific page to show only certain tags.
Note: Don't forget to create a Tag group in order to configure whether tags can be added by users or mods

Tags can be created by users or restricted to mods only. A Tag Group can define rules such as whether a tag is required, and whether multiple tags from the same group can be attached.

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)
If you do not provide an email, user will not receive notifications. If you do not provide a name, an auto-generated name will be given.

In addition, you should be also 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.
Powered by 
ClearFlask