LogoFastComments.com

Customizations and Configuration

Context

Here you will find in-depth documentation on each of the features and settings that the comment widget supports.

This documentation will cover core concepts, and will go deep into each area of functionality, with how-tos and common gotchas.

Code examples will be provided, with relevant lines highlighted. Screenshots of configuration pages will be provided where applicable.

The code examples will use our vanilla JavaScript library, however the configuration options use the exact same names for all versions of the comment widget (React, Vue, etc).

Most configuration and features outlined in this guide do not require writing any code.

Identifying Your Account Internal Link

You may notice that the comment widget can be used with a Tenant ID of "demo", for example:

Demo Tenant ID
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo"
7});
8</script>
9

This is only meant to try out and play with the comment widget. In production, you would pass your Tenant ID, like so:

Defining Your Tenant ID
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "aKa2Z4Q="
7});
8</script>
9

Your Tenant ID can be found already applied on the comment widget code snippet in your account.

From this point on, if you are logged into FastComments, the code examples will use your real tenant id.

How Comments are Tied to Pages and Articles Internal Link

When rendering a comment thread, or leaving a comment, FastComments needs to know what page, or article, or product those comments belong to.

To do this, we use something we call the "URL ID". It's either an identifier, like a string or a number, or a URL.

By default, if you do not specify the urlId, it will become the page URL. We will take the current page URL, and clean it to remove any common marketing parameters or tracking identifiers.

In the case of third party integrations, like WordPress, our plugin will usually use the identifier that represents the current information being viewed as the URL ID, for example the article/page id.

Defining a Custom URL ID
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "urlId": "https://example.com/page"
8});
9</script>
10

One thing that we'll often reference in this document is the Widget Customization UI.

This UI can be used to make many changes to the comment widget without using code.

When creating a customization rule, we'll often want it to apply to all pages to our site. However, in some cases we want to customize the comment widget on a particular page, either to apply custom styling, or maybe make comments for that particular page anonymous. You could also, for example, have live comments appear right away on some pages, while hiding them under notification buttons on others.

This is all possible via the URL ID input field on this page, which looks like as follows:

URL ID Input in The Widget Customization Page

The value in this field should match the urlId parameter passed into the comment widget. If you want your customization rule to be urlId agnostic, leave this field empty or enter *.

Gotchas

  1. If your page has hash parameters (like example.com#page-1) - this will become part of the URL ID, by default.
  2. During migrations, for example from WordPress to Gatsby, you may have to migrate the URL ID comment values after the initial migration. For that, reach out to us.

Rendering The Same Comments on Different Pages Internal Link

Since the urlId parameter allows us to define which page, or id, the comments are tied to, we can simply set urlId to the same value on those pages.

The Same Comments on Multiple Pages
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "urlId": "https://example.com/source-page"
8});
9</script>
10

Custom Styling Internal Link

FastComments is designed to be customized. The commenting widget itself runs inside an iframe for security reasons, so to apply custom styling you have to follow one of two approaches.

The first, the easiest approach, and preferred by us, is to use the widget customization page.

In the widget customization page, see the "Show Advanced Options" section, under which there is an area labeled "Custom CSS":

Custom CSS Input Area

This approach has some benefits:

  1. The entered CSS is minified before it is sent to the user, and the formatting is kept consistent in the editing UI.
  2. You get all the benefits of the widget customization UI, for example easily customizing the commenting widget differently for different sites.
  3. When we make changes to the comment widget, your custom styling will be tested as part of our release process.

The second approach is to specify the customCSS parameter in the widget configuration, as follows:

Passing Custom CSS
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "customCSS": "button { background: red; }"
8});
9</script>
10

However, this has limitations:

  1. There is a limit to how much custom CSS that can be passed before our servers will reject the request, due to the size of the headers.
  2. You must manage the custom CSS in your infrastructure, and build system. This may be an upside rather than a downside, as well.
  3. There is an additional overhead of sending the custom CSS over the network twice in this use case, as it has to be sent to our servers, and then sent back in the iframe content. However for most payload sizes, this is not noticeable.
  4. A common optimization is minifying the CSS to reduce its size over the network, however with this approach you will have to handle that.
  5. Your custom CSS won't be tested when we make changes.

Backwards Compatibility

At FastComments, we know our customers customize the commenting widget. That's by design - the last thing we want is for our product to cause design inconsistencies in your product.

Since this is an important part of our product, we have a build pipeline that allows us to review changes to the comment widget, per-customer, each release.

If we find minor issues, we will update your account to ensure our release goes smoothly. If we see major breaking changes, this allows us to halt the release.

Removing Branding Internal Link

For customers with Pro or Unlimited accounts, white labeling is allowed. Simply reach out to us and we'll be happy to help.

Supporting Dark Backgrounds (Dark Mode) Internal Link

By default, the FastComments comment widget will automatically detect dark mode on most sites.

When dark mode is detected, FastComments will switch from black text on white backgrounds to white text on a black background. Images will also change.

On page load, the widget will try to determine how dark the background of the page is behind the comment widget. This means that the page could have a white background, but if you put the comment widget inside a container with a black background, dark mode should still automatically be enabled to make the comments readable.

However, the detection mechanism, which relies on determining "luminance", may not enable dark-mode when you want to. To forcefully enable it, set the hasDarkBackground flag to true as follows:

Force Dark Background Mode
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "hasDarkBackground": true
8});
9</script>
10

Toggling Dark Mode Internal Link

For sites that allow toggling dark mode after the initial page load, this is a bit more involved.

First, all current versions of the Comment widget library (React, Vue) have examples of toggling dark mode in their respective repositories.

For the VanillaJS widget, we will need to do some more work. First, the FastCommentsUI returns an object with the functions "destroy" and "update".

We can simply call the update function every time we want to update the comment widget configuration, as follows. Here is a complete functioning example of toggling dark mode with the VanillaJS widget.

Toggling Dark Mode Complete Example
External Link
1
2<script src="https://fastcomments.com/js/embed.js"></script>
3<button id="toggle-dark-mode">Toggle Dark Mode</button>
4<div id="fastcomments-widget"></div>
5<script>
6 (function() {
7 const button = document.getElementById('toggle-dark-mode');
8 const config = {
9 tenantId: 'demo',
10 hasDarkBackground: false
11 };
12 const instance = window.FastCommentsUI(document.getElementById('fastcomments-widget'), config);
13 button.addEventListener('click', function() {
14 config.hasDarkBackground = !config.hasDarkBackground;
15 if (config.hasDarkBackground) {
16 document.body.classList.add('dark');
17 } else {
18 document.body.classList.remove('dark');
19 }
20 instance.update(config);
21 });
22 })();
23</script>
24<style>
25 body.dark {
26 background: #000;
27 color: #fff;
28 }
29</style>
30

Overriding Text Internal Link

With FastComments, all text in the comment widget is customizable.

You can override a single piece of text, like the submit button, or all text in the entire comment widget.

By default, the text in the comment widget is translated based on the user's locale. However, we can override the text, if we are confident that our user-base is using the same local/language, for example:

Custom Text
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "translations": {
8 "SUBMIT_REPLY": "Reply"
9 }
10});
11</script>
12

All customizable translations can be found here under the "advanced options" tab.

However, there is an easier way, via the widget customization UI. In there, we can simply find the text that shows in the commenting widget in the EN_US locale, and specify a replacement.

Custom Text

All translations overrides currently affect all locales.

Changing The Default Avatar Internal Link

When a user comments with FastComments for the first time we will try fetch their avatar from http://gravatar.com/.

However, if we don't find an avatar, or the user never sets one in their account, we render a static default avatar image.

To specify your own static avatar image we can use the defaultAvatarSrc setting.

Override The Default Avatar
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "defaultAvatarSrc": "https://example.com/some-image.png"
8});
9</script>
10

This can also be done without code. In the widget customization page, see the "Default Avatar" section.

Customizing The Default Avatar

Note that defining the avatar for a particular user, like with SSO, is covered in its own section.

Disabling Avatars Internal Link

Avatars can be completely removed from the comment widget, even if users have defined their own avatar.

Hiding Avatars
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "hideAvatars": true
8});
9</script>
10

This can be customized without code, on the widget customization page:

Hiding Avatars

Disabling All Default Styles Internal Link

For larger custom styling projects, it may be desirable to start with a clean slate and not use the default styling at all.

All default styling can be removed by setting the noStyles parameter to true, as follows:

Disabling All Default Styles
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "noStyles": true
8});
9</script>
10

This can be customized without code, on the widget customization page, under Advanced Options:

Disabling All Default Styles

Linking from Comments to Pages Internal Link

When sending notification emails, or rendering comments in user interfaces like the moderation page, it's helpful to be able to link from the comment to the page it's on.

If URL ID isn't always an ID, then we have to store the URL some place else. That's what the "url" property is for, defined as follows.

Defining a Custom URL
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "url": "https://example.com/article-5"
8});
9</script>
10

A common use case is tying the comment thread to an identifier, like an article, and then linking back to a particular page, for example:

Defining Custom URL and URL IDs together
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "url": "https://example.com/article-5",
8 "urlId": "article-5"
9});
10</script>
11

The URL does not get cleaned of common marketing parameters. By default, whatever the current page URL is, is the URL stored with the comment.

Determining Which Page to Render Internal Link

When fetching and rendering comments, the comment widget needs to know which page to start on. By default, it starts with the first page, only rendering that page.

If desired, the exact page to be rendered can be passed to the comment widget as the setting startingPage.

Specifying The Page to Render
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "startingPage": 1
8});
9</script>
10

Note that pages numbers start from zero, so the above example renders the second page.

Absolute Dates (Disable Human-Friendly Timestamps) Internal Link

By default, localized relative dates are used. For example, next to a recently left comment you may see "11 minutes ago".

It may be necessary or desired to use absolute dates, in which case you set this parameter to true.

Use Absolute Dates
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "absoluteDates": true
8});
9</script>
10

This can be customized without code, on the widget customization page, under Advanced Options:

Use Absolute Dates

Adding Header Text Internal Link

Some text, like a header or message, can be rendered below the comment count but above the login status text.

We call this the header, and by default it is hidden.

Specifying Header HTML
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "headerHTML": "<h1>Leave a Comment!</h1>"
8});
9</script>
10

This can be customized without code, on the widget customization page, under Advanced Options:

Specifying Header HTML

Adding a Button to Show Comments Internal Link

By default, FastComments will render the comment input box and comment thread at the same time. To save some vertical space, it will also hide any other required fields until the widget is interacted with.

However, the comment widget can be hidden behind a button, with customized text using hideCommentsUnderCountTextFormat.

This string value can also contain a [count] token, which will be replaced with the localized comment count.

Click to Show Comments
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "hideCommentsUnderCountTextFormat": "Show [count] Comments"
8});
9</script>
10

This can be customized without code, on the widget customization page:

Click to Show Comments

Customizing The Comment Count Text Internal Link

The comment count displayed at the top of the comment widget can be customized.

This can be replaced with any string, and the value [count] will be replaced with the count value, localized for the user.

Customizing The Comment Count Text
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "commentCountFormat": "There are [count] comments."
8});
9</script>
10

This can be customized without code, on the widget customization page:

Customizing The Comment Count Text

Show Live Comments Right Away Internal Link

By default, live commenting is enabled. This means that if any comments are added, deleted, edited, or pinned, the changes should appear to all users viewing the comment thread at the same time.

However, by default those new comments will appear under a dynamically shown button with the text similar to "Show 2 New Comments".

If the new comments are replies directly to the page, the button will show at the top of the comment thread. If they are replies to a particular comment, the button will show under that comment.

This is to prevent the page size changing constantly on the user, potentially causing frustration when trying to grab the scroll bar.

For some use cases, like live bidding, or online events, this is not the desired behavior - you may want the commenting widget to be more like a "chat" box where new comments "show right away".

Hence, the name of the flag that enables that feature: showLiveRightAway.

We can turn it on as follows:

Show Live Comments Right Away
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "showLiveRightAway": true
8});
9</script>
10

This can be customized without code, on the widget customization page:

Show Live Comments Right Away

Rendering All Comments at Once - Disable Pagination Internal Link

To disable pagination, and just render all comments at once, set startingPage to -1.

Render All Comments
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "startingPage": -1
8});
9</script>
10

Changing The Default Sort Direction Internal Link

By default, FastComments will sort comments by the "Most Relevant" sort direction.

Most Relevant sorting takes the time the comment was left, and the number of votes into account for sorting.

The user can then change the sort direction to either Oldest or Newest First in the comment widget UI.

However, we can change the default to be any of the three. For example if you wanted to show the oldest comments first:

Changing The Default Sort To Oldest First
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "defaultSortDirection": "OF"
8});
9</script>
10

We set the value of defaultSortDirection to "OF" to set the direction to "OF".

For the newest-first sort direction, we would do the following:

Changing The Default Sort To Newest First
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "defaultSortDirection": "NF"
8});
9</script>
10

The valid values for defaultSortDirection are:

  • MR: "Most Recent"
  • NF: "Newest First"
  • OF: "Oldest First"

This can also be done without code. In the widget customization page, see the "Default Sort Direction" section.

Changing The Default Sort Direction

Note that, the comments on each page for each sort direction are pre-computed, so all sort directions have the same performance.

Moving The Reply Box to After The Comments Internal Link

By default the comment input area is before the comment thread. However, by setting this configuration parameter to true we can move it to after.

Moving The Reply Box to The Bottom
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "inputAfterComments": true
8});
9</script>
10

This can be customized without code, on the widget customization page:

Moving The Reply Box to The Bottom

Limiting The Comment Length Internal Link

The max number of characters allowed to be entered in the comment input field can be limited by the maxCommentCharacterLength parameter.

The default is 2000.

Things like image URLs are not included in the length determination.

Limit Comment Length
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "maxCommentCharacterLength": 500
8});
9</script>
10

This can be customized without code, on the widget customization page:

Limit Comment Length

Disable Multi-Line Commenting Internal Link

By default, FastComments will allow the user to enter a comment of as many lines as they like, up to the default character limit.

However, it may be desirable to limit the user to entering only a single line of text. Some example use cases include online bidding, or live chat, which FastComments can be used for.

We enable the useSingleLineCommentInput flag as follows:

Enable Single-Line Comment Input
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "useSingleLineCommentInput": true
8});
9</script>
10

This can also be done without code. In the widget customization page, see the "Enable Single-Line Comment Input" section.

Enable Single-Line Comment Input

Note that, the comments on each page for each sort direction are pre-computed, so all sort directions have the same performance.

Single Sign On (SSO) Overview Internal Link

SSO, or single-sign-on, is a set of conventions used to allow you or your users use FastComments without having to create another account.

Assuming you don't allow anonymous commenting, an account is required to comment with FastComments. We make this sign up process very easy - the user just leaves their email when they comment. However, we understand that even that is extra friction some sites want to avoid.

We can reduce that friction by only having one login flow for your entire site.

How do I get it?

All account types - from the $4.99/mo plan to the $350/mo plan - get access to SSO. As with other features, the Pro plan provides direct development support.

Let's compare the options, and then go into details of each.

WordPress Users

If you're using our WordPress plugin then there is no code to write! Simply go to the plugin's Admin page, click SSO Settings, and then Enable.

This will take you to a single-button click wizard which will create your API key, send it over to your WordPress install and turn SSO on. We've consolidated this into a single button click for you.

Note that if you are installing the plugin for the first time you will have to follow up the setup process before you see the admin page with the SSO Settings button.

Custom Integrations

For Custom integrations, there are two options.

Option One - Secure SSO

With Secure SSO, FastComments knows that the user commenting, voting, and reading comments is a real user on your site.

As long as you create a valid payload, the user will always have a seamless commenting experience.

With Secure SSO, the SSO payload is created server-side using HMAC authentication and then passed to the widget on the client.

With Secure SSO, the user's account is completely separate from the rest of the FastComments user-base. This means if we have two partners Company A and Company B, each can have an SSO user with the username "Bob". This is not possible with Simple SSO if emails are provided.

Requirements

  • Some basic knowledge around backend development.
  • Some basic knowledge around dealing with secret API keys.
  • Some basic knowledge around API development or server-side rendering.

Pros

  • Secure.
  • Seamless commenting experience.

Cons

  • Requires backend development.

Option Two - Simple SSO

The alternative to Secure SSO is to simply pass the user information to the commenting widget. They won't actually be logged in, but it will appear as so in the commenting widget. The reason for this is we can't actually create a "session" - however instead we will email them when they take action like commenting or voting to verify their activity, without ever asking them for their username or email.

Note that providing an email with Simple SSO is not required, however by default their comments will show as "Unverified".

However, if invalid information is provided, for example: An email is provided along with a username, Bob. However, there is already a FastComments user with the user Bob. So, when the user goes to comment, they would get an error to pick a different username. This is one of the trade-offs of using Simple SSO.

This is due to the fact that when providing an email, we seamlessly create an account for the user. However, if only a username is provided, we will not. Please note that the user will be sent a welcome email to verify their account. If they wish, they can also delete their account and keep their comment.

Ideally, Simple SSO should only be picked when developing on a platform that doesn't provide backend access.

Requirements

  • Some basic knowledge around client-side development.
  • Have to know at least the user's email.

Pros

  • Simple.
  • All activity still gets verified.
  • The user never enters their username or email.

Cons

  • Username must be unique when paired with an email.
  • If Username is not unique, the user will go through the same flow as if not using SSO.
  • The user now has to deal with another account, not only the account associated with your website.

Custom Integrations - Secure Single Sign On (SSO) Internal Link

FastComments Secure SSO uses HMAC-SHA256 encryption as the mechanism to implement SSO. First we'll go over the overall architecture, provide examples, and detailed steps.

There is also some documentation regarding migrating from other providers with similar SSO mechanisms, and the differences.

The flow looks like this:

Secure SSO Flow
Secure SSO Diagram

Since Secure SSO involves full-stack development, full working code examples in Java/Spring, NodeJS/Express, and vanilla PHP are currently on GitHub.

Although we use ExpressJS in the NodeJS example and Spring in the Java example there are no frameworks/libraries required in these run-times to implement FastComments SSO - the native crypto packages work.

You don't have to write any new API endpoints with FastComments SSO. Simply encrypt the user's info using your secret key and pass the payload to the comment widget.

Get Your API Secret Key

Your API Secret can be retrieved from this page. You can find this page also by going to My Account, clicking the API/SSO tile, and then clicking "Get API Secret Key".

Comment Widget Parameters

High-level API documentation for the comment widget can be found here.

Let's go into more detail of what these parameters mean.

The comment widget takes a configuration object - you already pass this if you're using FastComments to pass your customer id (called tenantId).

To enable SSO, pass a new "sso" object, which must have the following parameters. The values should be generated server side.

  • userDataJSONBase64: The user's data in JSON format, which is then Base64 encoded.
  • verificationHash: The HMAC-SHA256 hash created from UNIX_TIME_MILLIS + userDataJSONBase64.
  • timestamp: Epoch timestamp, in milliseconds. Must not be in the future, or more than two days in the past.
  • loginURL: A URL that the comment widget can show to log the user in.
  • logoutURL: A URL that the comment widget can show to log the user out.
  • loginCallback: When provided instead of the login URL, a function that the comment widget will invoke when clicking the login button.
  • logoutCallback: When provided instead of the logout URL, a function that the comment widget will invoke when clicking the logout button.
Secure SSO Client Code
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "sso": {
8 "userDataJSONBase64": "...",
9 "verificationHash": "...",
10 "timestamp": 1618606188433,
11 "loginURL": "https://example.com/login",
12 "logoutURL": "https://example.com/logout"
13 }
14});
15</script>
16

The User Object

The User object contains the following schema:

The User Object
1
2interface User {
3 /** Required. 1k Characters Max. **/
4 id: string;
5 /** Required. 1k Characters Max. Note: Must be unique. **/
6 email: string;
7 /** Required. 1k Characters Max. Note: The username cannot be an email. Does not have to be unique. **/
8 username: string;
9 /** Optional. 3k Characters Max. **/
10 avatar?: string;
11 /** Optional. **/
12 optedInNotifications?: boolean;
13 /** Optional. 100 Characters Max. This label will be shown next to their name. **/
14 displayLabel?: string;
15 /** Optional. 2k Characters Max. The user's name will link to this. **/
16 websiteUrl?: string;
17}
18

Notifications

To enable or disable notifications, set the value of optedInNotifications to true or false respectively. The first time the user loads the page with this value in the SSO payload, their notification settings will be updated.

VIP Users & Special Labels

You can display a special label next to the user's name by using the optional "displayLabel" field.

Unauthenticated users

To represent an unauthenticated user, simply do not populate userDataJSONBase64, verificationHash, or timestamp. Provide a loginURL.

Direct Examples for Serializing and Hashing User Data

More details as an examples here (js), here (java) and here (php).

We understand that any integration can be a complicated and painful process. Don't hesitate to reach out to your representative or use the support page.

Custom Integrations - Simple Single Sign On (SSO) Internal Link

With Simple SSO, we can provide the commenting widget with information about the user so that they don't have to enter their username or email to comment.

We can configure Simple SSO as follows:

Simple SSO
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "simpleSSO": {
8 "username": "Bob",
9 "email": "bob@example.com",
10 "avatarSrc": "https://example.com/bob.png",
11 "websiteUrl": "https://example.com/profiles/bob"
12 }
13});
14</script>
15

The user won't actually be logged in, but it will appear as so in the commenting widget. When they take any action, we will email them asking to verify it, if an email is provided.

Note that providing an email with Simple SSO is not required, however by default their comments will show as "Unverified".

If the provided username is not unique, they will be asked for a new username when attempting to comment.

Custom Integrations - Migrating from Disqus SSO Internal Link

The biggest differences between Disqus and FastComments Secure SSO is that Disqus uses SHA1 for encryption while we use SHA256. This means migrating from Disqus is easy - change the hashing algorithm used from SHA1 to SHA256 and update the property names passed to the UI.

Custom Integrations - Migrating from Commento SSO Internal Link

Commento uses a drastically different SSO approach - they require you to have an endpoint that they invoke to authenticate the user. FastComments is the other way around - simply encode and hash the user's information using your secret key and pass it along.

Protecting Comment Threads With Single-Sign-On Internal Link

FastComments SSO (details here) provides your users with a way to comment without having to log in to another platform.

However, this alone doesn't secure your comment threads, since by default comment data is publicly available information - anybody that can view the page can view the comments.

By changing a setting, we can restrict comments from being fetched unless it is by an administrator or valid SSO user.

No-Code Setup

We can prevent viewing and interacting with our comment threads, when SSO is set up, by creating a customization rule.

When doing so, search for SSO, and you will find this option:

Require SSO To View Comments

Enable it and save the customization rule.

Only Protect a Certain Domain or Page

To only protect a certain Domain or Page, we'll simply configure the customization rule to do so.

At the top of the customization UI, we'll find two inputs, Domain and URL ID.

To just protect a particular domain, enter the domain in question into the "domain" field.

To protect a particular page, enter a page URL in the "URL ID" field. If you have a custom integration with FastComments, you may enter a type of ID here instead of a URL.

Protection Beyond Reading

Enabling this option will protect the page or domain from being commented on unless the user is logged in via SSO.

Gotchas

Any users that created comments before your SSO integration will not be able to see them, unless they log in via your SSO integration.

Allow Anonymous Commenting Internal Link

By default, FastComments will require an email to comment. It does not have to be a valid email, however until the user clicks a link sent to them, their comment will display an "Unverified Comment" label.

However, we can remove the email requirement. The email input field will still show, but it will no longer be required.

This can be configured via the widget customization UI:

Enabling Anonymous Comments

Preventing Anonymous Comments From Expiring Internal Link

FastComments can be configured to remove unverified comments after a desired number of days. This helps combat spam.

By default, it does not.

This can be configured, or disabled, via the Moderation Settings page.

Moderation Settings

Manually Defining the User's Locale Internal Link

By default, FastComments will render the comment widget in the locale determined by the user's system and browser.

This impacts how the commenting widget is translated for the user.

This can be overridden with a desired locale. Please check here for valid locales.

Manually Defining the User's Locale
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "locale": "ru_ru"
8});
9</script>
10

Page Titles Internal Link

The current page title is associated with the specified urlId and saved for use in moderation tools.

By default, this is retrieved from document.title.

If desired, your own page title can be specified as follows:

Specifying The Page Title
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "pageTitle": "Article 42"
8});
9</script>
10

Prevent New Replies & Disable Votes Internal Link

Commenting can be locked so new comments or votes can be made by setting the readonly flag to true.

Comments will also be unable to be edited or deleted.

Making The Comment Thread Readonly
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "readonly": true
8});
9</script>
10

This can be customized without code, on the widget customization page:

Making The Comment Thread Readonly

Disabling Image Uploads Internal Link

By default FastComments allows image uploads. This can be disabled by setting the noImageUploads flag to true.

Disabling Image Uploads
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "noImageUploads": true
8});
9</script>
10

This can be customized without code, on the widget customization page:

Disabling Image Uploads

The Comment Count & Counting All Nested Replies Internal Link

The comment count displayed at the top of the comment widget can either show all "top-level" comments, meaning those replies that are replies directly to the page or article itself, or it can be a count of all nested comments. By default, it is a count of the former.

We can change this, so that it is a count of all nested comments by setting the countAll flag to true.

Counting All Comments
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "countAll": true
8});
9</script>
10

This currently cannot be customized without code changes.

By default, FastComments will only ask the user for their comment, their username, and their email.

However, in some situations you may want to have the user leave a link to their own blog or website.

We can enable showing an extra input field to leave the user's website URL by setting the enableCommenterLinks flag to true:

When said URL is provided, the user's account will be updated and all of their username on all past and future comments will link to this URL.

This can be customized without code, on the widget customization page:

Enabling Commenter Links