Viafoura

The Viafoura Documentation Hub

Welcome to the Viafoura documentation hub. You'll find comprehensive guides and documentation to help you start working with Viafoura as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Integration with your Content

Using Unique IDs to associate your content with our engagement tools.

Introduction to the Viafoura Unique ID System

The unique_id attribute allows multiple URLs to be linked to the same page and thus, comments created under associated URLs will be the same. You may specify any string you would like to use as your unique_id, as long as it is no more than 100 characters in length.

Caution

If used incorrectly, unique_ids can lead to problems such as comments for different pages showing in the wrong places. As such we recommend exercising caution when utilizing this feature.

When to use unique_id's

Unique IDs may be appropriate if the following conditions are true:

  • You do not know the canonical URL of the page AND
  • You want to display the widget on multiple pages OR a different page than the related article

When NOT to use unique_id's

Unique IDs are most likely not appropriate if any of the following conditions are true:

  • You know the canonical URL
  • The unique ID is not known the first time a page is loaded
  • You just want a unique identifier for a page (use the canonical URL or Viafoura page ID instead)
  • If you might want to change the unique ID in the future

In these cases it is safer to use the default setup of our widgets which auto-detect the current page OR to use the data-path attribute which allows you to specify the page which the widget belongs to.

Integration Considerations

There are a few caveats:

  • unique_id will have to be present in the API request that creates the page
  • Editing a unique_id after a page has been created with a unique_id is not supported
  • Having a single page with multiple unique_id's is not supported

A common use case that can cause problems is when a user decides to change the URL of content that does not already have a unique ID.

Caution

Please ensure Unique ID's are unique.
If an ID is duplicated, the system will assume that the content (i.e. comments) belong to that ID, and will merge them to that ID. This cannot be un-done.

Caution

When implementing Unique ID in your CMS, please double check that the value is not static, and does indeed change with the content. If you launch with a static ID, ALL content will belong to that ID, and it can not be un-done.

How to integrate unique_id's

  1. Create a page http://mysite.com/page1.html, with no unique_id
  2. Create a new page http://mysite.com/page2.html with a unique_id=ABCD
  3. Add the unique_id=ABCD to page1
  4. Comments previously on page1 disappear and are replaced with the comments on page2

There are 3 possible integrations paths

  1. Ensure that you use Unique IDs on ALL pages at creation time and that when you publish a new copy of a page at a different URL that it has the same unique_id as that page at the time it is first visited by anyone. This will ensure that you do not accidentally attempt to apply a unique_id to a page that will not work with it, and that subsequent moves to new URLs will work as expected.

  2. If updating an existing page to a new URL, add the unique_id to the original page before creating the page at the new URL.

  3. If the page you wish to move does not have a unique_id at the time you wish to move it, you can keep the old URL active, and add a new page with a commenting widget that has the data-path parameter set to the URL of the original page.

Examples

Page Settings:
Unique IDs can be set either on the page or widget. When setting a unique ID on a page, that page will be considered identical to any other pages with the same unique ID.

This is very similar to using the URL meta properties but, allows the use of any alphanumeric characters (any UTF8 character with a limit of 100 characters). Make sure you insert the tag before the Viafoura snippet, as per the Getting Started section. Here is a sample implementation of the unique_id meta tag:

<!-- All Meta Tags should belong in the HTML HEAD -->
<meta property="vf:unique_id">
<content="some_random_unique_id_that_is_less_than_100_chars">

Note

The vf:unique_id meta tag will always take precedence over any URL meta properties

The social plugins will attempt to auto-detect the current page's content in the following order:

  • <meta property="vf:unique_id" content="XXX">

  • <meta property="og:url" content="XXX">

  • window.location

Widget Settings

Unique IDs can also be set for some widgets (eg commenting and article share widgets). These settings must be set in conjunction with a data-path attribute.

These settings will override any page-level settings for the widget in question.

Note

Ensure that the page indicated by the data-path is also tagged with the correct unique id.

<div class="viafoura">
  <div class="vf-comments vf-widget">
     data-widget="comments";
     data-path="http://example.com/path/to/page";
     data-unique_id="SOME_UNIQUE_ID";
  </div>
</div>

Integration with your Content


Using Unique IDs to associate your content with our engagement tools.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.