README.md

Xperience Disqus Widget

The Disqus comments widget for Kentico Xperience 13 provides an option to add a comment section to any page on your website. Disqus offers advanced moderation tools, analytics and monetization options. This integration also includes advanced on-line marketing tools to integrate Disqus with marketing automation, activities and macros.

Prerequisite

This integration is compatible with any Kentico Xperience 13 (version 13.0.32 or newer) project using the ASP.NET Core development model.

Installation

1. Install the Kentico.Xperience.Disqus NuGet package in your live site Xperience project.
2. Open the Disqus Admin website.
   1. Select the "I want to install Disqus on my site" option if you haven't done so before.
   2. Create a new site (or select an existing one) and note the Shortname from the Settings application -> General tab.
3. In your live-site project's appsettings.json, add the following setting:

"xperience.disqus":  {
    "siteShortname": "my-awesome-site"
}

Adding Disqus widget to your pages

The Disqus comments widget can be added as a standard page builder widget to any page with the page builder where editable area restrictions and widget zone restrictions were adjusted accordingly.

Alternatively, the widget can be added directly to your views as a standalone widget:

@using Kentico.Xperience.Disqus

<standalone-widget widget-type-identifier="@DisqusComponent.IDENTIFIER" widget-properties="new DisqusComponentProperties()" />

There are 3 optional properties that you can configure:

• Title - A custom title for the created Disqus thread. If not set, the DocumentName or HTML title will be used.
• PageIdentifier - The Disqus identifier of the created thread. If not set, the DocumentGUID is used.
• CssClass - One or more classes to add to the <div> element that surrounds the Disqus comments.

The widget can be placed on any view in your .NET Core project. However, if it is placed on a view without representation in the Xperience content tree, the PageIdentifier property must be specified.

⚠️ Do not add more than one instance of the Discuss widget on a single page as only one instance can be loaded at once.

Displaying links with comment counts

You can place a link to the comments section of any page by appending #disqus_thread to the URL. The link can also contain the number of comments on that page:

If you'd like to also display the number of comments, you can use the default Disqus functionality, which requires adding the count.js script along with the absolute URL. To get the URL of an Xperience page, you can use IPageUrlRetriever:

@inject IPageUrlRetriever urlRetriever

<a href="@(urlRetriever.Retrieve(node).AbsoluteUrl)#disqus_thread"></a>

On-line marketing integration

Logging On-line marketing activities

With this integration, you can log activities whenever a new comment is posted. If you have text analytics enabled, the sentiment of the comment will be also logged with the activity. This is helpful during the creation of marketing automation processes or contact groups. For example, if a contact leaves a positive comment on an article, you may want to send them an email offering a discount on the products advertised in the article.

To begin logging activities, configure the following custom activity type in Contact management application -> Configuration -> Activity types. Only the code name of the activity type needs to match exactly, the rest can be altered to meet your needs.

You also need to register a comment activity route in your project:

app.UseEndpoints(endpoints =>
{
    endpoints.Kentico().MapRoutes();
    ...
    endpoints.MapDisqusActivityTracking();
...

Triggering marketing automation processes

You can reference these activies to trigger marketing automation processes. For example, you may want to trigger a process when a positive comment is left on a specific page:

• Trigger:
  • Display name: Positive comment on article
  • Type: Contact performed an activity
  • Activity type: Disqus comment
  • Additional condition: Activity.ActivityValue == "positive" && Activity.Node.NodeAliasPath == "/Articles/Coffee-Beverages-Explained"

You could also check the comment's sentiment in an if/else step to create a process with multiple branches. Remove the Additional condition from the above trigger so the process runs for all comments. Then, set up your process something like this:

In the if/else condition, you can check the sentiment of the triggering activity in the AutomationState object:

AutomationState.StateCustomData["TriggerDataActivityValue"] == "negative"

In this example, if the comment is negative the contact will be sent an email after 1 day. If it is positive, the contact is added to a contact group.

Creating macro rules

These activities can be used in conditional contact groups and other on-line marketing functionality by creating your own macro rules. The following steps create a macro rule that can be used in a contact group which contains contacts who left a comment with the chosen sentiment in the last X days:

1. In Contact management application -> Configuration -> Macro rules, click New macro rule:
   • Display name:"Contact commented on Disqus"
   • User text: "Contact left a {sentiment} comment in the last {days} days"
   • Condition: Contact.DidActivity("disquscomment", "", {days}, "ActivityValue='{sentiment}'")
2. Save and switch to the Parameters tab
3. On the sentiment property, change the control to "Drop-down list" and under List of options, add:
   • positive
   • negative
   • neutral
   • mixed
4. On the days property, change the Data type to "Integer number".

Your marketers can now use this rule when creating contact groups:

Support

Please note that the level of provided support is always determined by the LICENSE file of a given open-source project. Unless stated otherwise, Kentico Software does not provide support nor testing for open source software. OS projects are developed by volunteers and maintained by Kentico employees in their spare time. The software is distributed as it is, without any guarantee.

• Use Stack Overflow to ask questions about using Kentico's OS projects. Make sure you label them with the kentico-kontent, kentico-xperience, or kentico tag to make it easy for the community to find them.
• Use GitHub Issues for submitting bugs and feature requests related to OS projects.