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

Custom Fonts Internal Link

FastComments is designed to be customized, and the font our widgets use is no exception.

By default, FastComments uses the system font stack to look as good as possible on a wide range of devices.

To define your own fonts, see the Custom CSS documentation.

There you will find a way to define custom CSS, which will allow you to define your desired fonts.

How to Define The Font

To override the font, we recommend you define your CSS using the .fast-comments, textarea selectors. For example:

Custom External Font Example
External Link
1
2@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@300&display=swap');
3.fast-comments, textarea {
4 font-family: 'Roboto', sans-serif;
5}
6

Removing Branding Internal Link

For customers with Pro or Enterprise 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-v2.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-v2.min.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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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.

Collapse Replies by Default Internal Link

By default, replies to top level comments show.

This can be configured so that the user has to click "Show Replies" on the top-level comments to see the children.

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

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

Collapse Replies

This setting will not affect the number of top-level comments initially loaded. If you have one top level comment, and 29 children, with this setting on you will:

  • See the top level comment.
  • See Show Replies (29) under this comment.

If you wish to show all top level comments in combination with this option, set starting page to -1.

Disabling The Toolbar Internal Link

By default, FastComments will show a toolbar when writing a comment to provide shortcuts for decorating text and uploading images.

This toolbar can be disabled in code or with the Customization UI.

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

This can also be done without code. In the widget customization page, see the "Disable The Reply Toolbar" option.

Disabling The Toolbar

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

Switching Comment Threads Without Reloading The Page Internal Link

We've covered how urlId is the page or article id the comments are tied to.

Also, to recap, if not defined the urlId will default to the current page URL.

What about SPAs, or Single-Page-Applications, where the page or content the comments are tied to changes dynamically without a fresh page reload?

Angular, React, Vue, etc

With our libraries such as Angular and React, simply updating the urlId property passed to the widget will cause the comment widget to refresh. You can see this in action for the React app, for example, here.

VanillaJS

If you're using the VanillaJS library it is slightly more complicated as there isn't a framework like Angular or React to handle the data binding or state propagation.

When you instantiate the VanillaJS widget, it returns some functions which can be called to update it.

Here's a functional example where we change the page hash and update the comment widget:

Switching Page Hash Example
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed-v2.min.js"></script>
3<button id="change-page"></button>
4<div id="fastcomments-widget"></div>
5<script>
6 (function fastCommentsMain() {
7 let config = {
8 tenantId: 'demo'
9 };
10 let instance = window.FastCommentsUI(document.getElementById('fastcomments-widget'), config);
11
12 let page = '#page-1';
13 function getNextPage() {
14 if (page === '#page-1') {
15 return '#page-2';
16 } else {
17 return '#page-1';
18 }
19 }
20
21 let button = document.getElementById('change-page');
22 function nextPage() {
23 page = getNextPage();
24 button.innerText = 'Go to ' + getNextPage();
25 window.location.hash = page;
26 let locationString = window.location.toString();
27
28 config.url = locationString; // We update url, too, so notifications can link back to the right page
29 config.urlId = locationString;
30
31 instance.update(config);
32 }
33 nextPage();
34 button.addEventListener('click', nextPage);
35 })();
36</script>
37

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

Showing Both Absolute & Relative Dates 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 keep this relative date format, but also show the full date alongside it, in which case you set this parameter to true.

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

This can be customized without code, on the widget customization page, under Advanced Options. You will first have to enable Absolute Dates to see this option in the UI.

Use Both Absolute and Relative 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-v2.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

Toggling Comments With a Button 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.

The button uses different translated text based on whether the comments are currently shown or not. If the comments are hidden, it uses translations.SHOW_COMMENTS_BUTTON_TEXT. If the comments are shown, it uses translations.HIDE_COMMENTS_BUTTON_TEXT. The translations can contain the text [count] which will be replaced by the localized count.

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

This is designed to replace the hideCommentsUnderCountTextFormat configuration.

The count is updated live with the comment thread. The button is not shown if there are no 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-v2.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

Disable Image Redirect Internal Link

By default, FastComments allows users to upload images. When a user clicks that image, FastComments will, by default, open a new tab to show that image in full. Setting this flag to true disables this behavior:

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

If you don't plan to capture the image click yourself (see onImageClicked), we recommend this is combined with some styling to remove the appearance that the image can be clicked.

Disable Automatic HashTag Creation Internal Link

When users enter hashtags, in the form of #someexampletag, FastComments will automatically create that HashTag and highlight it in their comment.

In some cases it's desirable to disable this feature, or control what hashtags can be used via the API.

To do so, simply enable Disable Automatic #hashtag Creation via the Widget Customization UI.

Disabling Automatic HashTag Creation

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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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 currently get access to SSO. However, the max number of SSO users will vary depending on your package. As with other features, the Pro plans and higher provide 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.

WordPress SSO - Moderators

Note that currently for the "Moderator" badge to show next to your moderators when they comment with the FastComments WordPress plugin, they must also be added as a Moderator in the FastComments dashboard, and have their email verified.

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.

Updating User Data

With Secure SSO, each time you pass the sso user payload, we will update their user with the latest information. For example, if the user has a username X, and you pass Y in the SSO payload, their username will become Y.

If you want to remove values using this approach then set them to null (not undefined).

Secure SSO API

We also provide an API for interacting with the SSO users. See the docs.

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.

Simple SSO API

We do not provide an api for interacting with the users created from the Simple SSO flow.

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-v2.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": 1638554476329,
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 for URLs. Default is from gravatar based on email. Supports 64 encoded images, in which case the limit is 50k characters. **/
10 avatar?: string;
11 /** Optional. Default false. **/
12 optedInNotifications?: boolean;
13 /** Optional. 100 Characters Max. This label will be shown next to their name. Default is Administrator/Moderator when applicable. **/
14 displayLabel?: string;
15 /** Optional. 2k Characters Max. The user's name will link to this. **/
16 websiteUrl?: string;
17 /** Optional. Up to 100 groups per user. A group id may not be longer than 50 characters. **/
18 groupIds?: string[];
19}
20

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-v2.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 "avatar": "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.

Notes:

  • 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.
  • While Simple SSO can automatically create users, it cannot update users. This is because Simple SSO has no form of authentication - we can't let an anonymous request change a user's name, or avatar, for example.

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

Disable Email Inputs Internal Link

When users comment, and they are not logged in, they will be asked to provide their email.

This will create an "unverified session" for that user, and we will ask them to verify that session via email.

For some sites, or applications, it's desirable not to ask the user for their email when commenting or voting.

Enabling anonymous commenting makes the email input field optional. However, we can disable it completely. First, enable anonymous commenting, and then the option to disable the email input fields will appear.

Disable Email Inputs

With this on, the email fields will not show at all in all of our commenting products.

Note that, with this configuration, all comments will be unverified unless the user creates an account and logs into https://fastcomments.com.

You may want to consider disabling the unverified label.

Disable The Unverified Label Internal Link

By default, FastComments will show an "Unverified Comment" label for comments that have been left for a user that has an unverified browser session. Read more about unverified commenting here.

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

Additionally, this feature can be used, without writing code, in the Customization UI:

Disable The Unverified Label

Allow Anonymous Voting Internal Link

When users attempt to vote on a comment, and they are not logged in, they will be asked to provide their username and email.

We can remove this requirement, allowing anyone to vote on a comment without leaving any information.

Allow Anonymous Votes

Setting a Default Username Internal Link

When users comment or vote, and they are not logged in, they will be asked to provide their email and username.

In the case of anonymous commenting, sometimes it is desirable to define a default username to reduce the friction when commenting. This can be done from the Customization UI. Anonymous Commenting must be enabled first.

Setting The Default Username

Callbacks Internal Link

All libraries for the comment widget (currently Angular, React, Vue) support callbacks.

The callbacks are specified in the configuration object, with the same signature for each library.

The callbacks supported are:

  • onInit
  • onRender
  • onReplySuccess
  • onVoteSuccess
  • onImageClicked

The exact signatures can be found in the TypeScript definitions.

Here's an example with all callbacks used:

Callbacks Examples
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed-v2.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5 window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 tenantId: 'demo',
7 onInit: function () {
8 console.log('Library started to fetch comments!');
9 },
10 onRender: function () {
11 console.log('Render event happened!');
12 },
13 onReplySuccess: function (comment) {
14 console.log('New comment saved!', comment);
15 },
16 onVoteSuccess: function (comment, voteId, direction, status) {
17 console.log('New vote saved!', comment, voteId, direction, status);
18 },
19 onImageClicked: function (src) {
20 console.log('Image clicked!', src);
21 },
22 });
23</script>
24

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.

When a user comments or logs in, we update their last used locale and use this for sending emails, as well.

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

Via The UI

This can be defined using the widget customization UI. See the "Locale / Language" option:

Changing The Locale / Language

Via Code

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-v2.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-v2.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 no new comments or votes can be left 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-v2.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-v2.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, this is true - it is a count of the latter - all comments. In older versions of the comment widget the default value is false.

We can change the behavior, 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-v2.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

If we wanted the count to reflect only the top level comments, we set the flag to false.

Counting Top Level Comments
External Link
1
2<script src="https://cdn.fastcomments.com/js/embed-v2.min.js"></script>
3<div id="fastcomments-widget"></div>
4<script>
5window.FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 "tenantId": "demo",
7 "countAll": false
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

Disabling Live Commenting Internal Link

By default, FastComments will have live commenting enabled.

This means that every viewer of the comment thread should see the same content.

For example, if a comment is added, that comment should show. If a comment is edited or removed, then those comments will be edited or removed for all viewers of the thread. Same with votes, and all moderation actions.

However, we can disable this:

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

This can also be done without code. In the widget customization page, see the "Disable Live Commenting" section.

Disable Live Commenting