Integration with your Content (legacy)

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

Suggest Edits

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.
  1. 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.
  1. 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:

  • 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>

Updated almost 4 years ago