Creating a Widget for Tracking External Links in Kentico 11
As long as your visitors stay on your website, Kentico can track their page visits, form submissions, and many other activities with ease. Nevertheless, in some cases, you would like to track if the visitor clicked the link on your website pointing to an external site.
This sounds easy to track, but because the website visitor’s journey continues to an external site, upon clicking the link, Kentico is not able to log the page visit activity for the visitor (contact).
So, are you ready to solve it? I thought so!
Here is what we need to do:
-
Create and register a custom activity for tracking external link clicks
-
Create a custom web part that displays the link, logs the activity if clicked, and redirects the visitor to the external site
-
Convert the web part into a widget so marketers can use it in a rich text editor
A pretty straightforward approach, right? So, let’s not wait any longer, and dive into each of the implementation steps.
A Custom Activity for Tracking External Link Clicks
Our documentation explains perfectly how to register your custom activity, so I recommend reading it first.
As described in the documentation, you first need to register the custom activity in the Kentico 11 EMS admin interface. This is how I did it in my Kentico 11 instance in the Contact management app:
I named my custom activity External Link Clicked, and made sure that the Code name property had been set to ExternalLinkClicked (as highlighted in the screenshot above).
At this point, the activity exists in the system, but we are still not able to log it via the Kentico API. That’s where custom code comes in, and you guessed it, it will be connected via the Code name property of the activity created earlier.
So, let’s open Visual Studio, and create a separate project in the Kentico web project. Best practices, right? :)
I named the project MyCustomCode (what an original name!), created a new ExternalLinkClickedInitializer class in there, and used this code in the class:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 |
using CMS.Activities;
namespace MyCustomCode
{
/// <summary>
/// ExternalLinkClicked activity inherits from the CustomActivityInitializerBase class.
/// </summary>
public class ExternalLinkClickedInitiliazer : CustomActivityInitializerBase
{
private readonly string mActivityValue;
/// <summary>
/// Default constructor that takes activity data as parameters.
/// </summary>
public ExternalLinkClickedInitiliazer(string activityValue)
{
mActivityValue = activityValue;
}
/// <summary>
/// Initializes an activity with required data.
/// </summary>
public override void Initialize(IActivityInfo activity)
{
activity.ActivityTitle = string.Format("Clicked the external link '{0}'", mActivityValue);
activity.ActivityValue = mActivityValue;
}
/// <summary>
/// The code name of the corresponding activity type in Kentico.
/// </summary>
public override string ActivityType
{
get
{
return "ExternalLinkClicked";
}
}
}
} |
Notice the ActivityType value returned by the class. Yes, it returns the same code name (ExternalLinkClicked) as we defined for our custom activity in the Contact management app earlier. If the code name didn’t match, our custom activity couldn’t be logged via the Kentico API.
I also adjusted the title of the activity to “Clicked the external link ‘someURL’” so it is easy to see right away for which external link was clicked by a contact.
As the custom activity is ready to be logged, it is time to move ahead and create a custom web part that will actually use it :)
A Custom Web Part for Logging the External Link Clicks
If you’ve never created a custom web part in Kentico before, feel free to read our documentation, which explains the whole process in perfect detail.
Let’s create the Web User Control in the Kentico web project according to our documentation and name it ExternalLinkTracking.
Replace the original code in the Control declaration with the following code:
1
2 |
<%@ Control Language="C#" AutoEventWireup="true" CodeFile="ExternalLinkTracking.ascx.cs" Inherits="CMSWebParts_MyWebParts_ExternalLinkTracking" %>
<asp:LinkButton ID="externalLinkButton" OnClick="externalLinkButton_Click" runat="server" /> |
As you can see, I used <asp:LinkButton> control that will display the link and make sure that when someone clicks the link, the custom activity is logged for them, and they are redirected to the specified external URL right after it.
Let’s switch to the control’s code behind the file, and replace the original code with the following one:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36 |
using System;
using CMS.PortalEngine.Web.UI;
using CMS.Helpers;
using CMS.Core;
using CMS.Activities;
using MyCustomCode;
public partial class CMSWebParts_MyWebParts_ExternalLinkTracking : CMSAbstractWebPart
{
protected void Page_Load(object sender, EventArgs e)
{
// Gets the value of the link text and assigns it to the externalLinkButton
externalLinkButton.Text = DataHelper.GetNotEmpty(GetValue("LinkText"), "External link");
}
/// <summary>
/// Logs the custom activity and redirects the visitor to the external URL
/// </summary>
protected void externalLinkButton_Click(object sender, EventArgs e)
{
// Gets the value of the external URL
string externalURL = DataHelper.GetNotEmpty(GetValue("ExternalURL"), "https://IfTheUrlIsEmpty");
// Gets an instance of the activity logging service
var service = Service.Resolve<IActivityLogService>();
// Prepares an initializer for logging the custom activity
var activityInitializer = new ExternalLinkClickedInitiliazer(externalURL);
// Logs the activity
service.Log(activityInitializer, CMSHttpContext.Current.Request);
// Redirects the visitor to the external URL
Response.Redirect(externalURL);
}
} |
The code is quite simple. It works with two web part properties: ExternalURL and LinkText. The ExternalURL property is the URL value to which the web part redirects upon the click, and the LinkText property is the clickable text that the web part displays.
As soon as the visitor clicks the displayed link, the externalLinkButton_Clickmethod is called. It logs the custom activity via the Kentico API, and then redirects the visitor to the external URL.
So, let’s rebuild the custom code in Visual Studio, and head over to the Kentico 11 administration interface to register the web part in the system.
Once registered, we need to create both properties (ExternalURL and LinkText) on the Properties tab of the web part in the Web parts app:
Both fields have the data type set as Text, marked as required, and set to be visible in the editing form.
At this moment, the web part is ready to be transformed into a widget.
Converting the Web Part into an Inline Widget
We are reaching the final destination! The only thing left is converting the web part into an inline widget so marketers can use it in the editable text areas.
This part is easy. Switch from the Properties tab to the General tab, and set the web part to a WidgetOnly type:
Head on to the Widgets application, and register a new widget by selecting our web part from the list:
Then switch to the Security tab to specify that our widget can be used only in editor zones or as an inline widget.
Additionally, I narrowed it down even more by allowing only Content editor and Marketing manager roles to use it:
And that’s all! You can now open the Pages application in Kentico 11, and add the inline widget into the editable area:
When you enter the external URL and the link text values into the widget properties,
anyone who clicks the displayed link on the live site:
will be redirected to the specified external URL, while at the same time, the custom activity will be logged for them in Kentico 11 EMS:
Congratulations! You’ve just made a custom web part that logs clicks every time someone clicks the external link!
Had you dealt with the same issue before? Please let me know in comments!
By
Pavel Jirik in
Kentico
Posted: Wednesday 01 August 2018