Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Explore how to manage marketing campaigns and create engaging content.
This section guides you through managing marketing campaigns and creating personalized content for your audience.
This tool lets you view data directly on the front end of the website.
Find generic popup, topbar, and exit intent popup templates to enhance your marketing efforts.
To get the full experience with Umbraco Engage you need to purchase and install a license. Learn more about how a license work in this article.
Umbraco Engage is a commercial product. You can run Umbraco Engage unrestricted locally without the need for a license and will display a trial banner. Running Umbraco Engage in the public domain will require you to have a valid license.
Licenses are sold per backoffice domain and will also work on all subdomains. If you have alternative staging/QA environment domains, additional domains can be added to the license on request.
The licenses are not bound to a specific product version. They will work for all versions of the related product.
Let's say that you have a license configured for your domain, mysite.com
, and you've requested two development domains, devdomain.com
and devdomain2.com
.
The license will cover the following domains:
localhost
*.local
*.test
mysite.com
www.mysite.com
devdomain.com
www.devdomain.com
devdomain2.com
www.devdomain2.com
You can have only 1 license per Umbraco installation.
There are a few differences as to what the licenses cover:
A single license covers the installation of Umbraco Engage in 1 production backoffice domain, as well as in any requested development domains.
The development and production domains work with or without the www
subdomain.
The license also includes localhost
, *.local
, and *.test
as valid domains.
Each individual subdomain has to be specified as part of the license (e.g. subdomain.mysite.com
), wildcard subdomains are not allowed.
If you have multiple backoffice domains pointing at the same installation, you have the option to purchase and add additional domains to your license.
This is an add-on domain for existing licenses. Refunds will not be given for this product.
You can look at the pricing, features, and purchase a license on the Umbraco Engage page. A member of the sales team will manage this process. In the process, you will need to provide all domains you wish to have covered by the license such as primary and development/staging/QA domains. You should then receive a license code to be installed in your solution.
To add additional domains to your license, reach out to a member of the Sales team with your request and they will manage this process.
Once you have received your license code it needs to be installed on your site.
Open the root directory for your project files.
Locate and open the appSettings.json
file.
Add your Umbraco Engage license key to Umbraco:Licenses:Umbraco.Engage
:
You can verify that your license is successfully installed by logging into your project's backoffice and navigating to the settings section. Here you will see a license dashboard which should display the status of your license.
UmbracoApplicationUrl
If you are running on a single domain for both your frontend and backend environments, it's not necessary to configure a UmbracoApplicationUrl
.
If you have different domains for your frontend and backend, then it's advised that you configure an UmbracoApplicationUrl
set to your backoffice URL. This helps the licensing engine know which URL should be used for validation checks. Without this configuration setting, the licensing engine will try and work out the domain to validate from the HTTP request object. This can lead to errors when switching between domains.
An UmbracoApplicationUrl
can be configured in your appSettings.json
file like so:
See the Fixed Application URL documentation for more details about this setting.
Learn about the different ways available for installing Umbraco Engage on your project.
This article covers two ways to install Umbraco Engage:
Via NuGet, or
Check the requirements before you start installing Umbraco Engage.
Install Umbraco Engage via Nuget in your IDE such as Visual Studio, JetBrains Rider, or VSCode (With C# DevKit).
The example shown below uses the Nuget Package Manager in Visual Studio.
Open the project in Visual Studio.
Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution.
Navigate to the Browse tab.
Search for the Umbraco.Engage package.
Select the package.
Choose which project to install it into.
Install the package.
You can install Umbraco Engage using a terminal, like the Package Manager Console in Visual Studio. The steps for doing so are outlined below.
Open the project in Visual Studio.
Find and open the Package Manager Console from the Tools menu.
Type the following into the terminal:
Alternatively, Umbraco Engage can be installed via the console on your operating machine.
Open a terminal window on your operating system.
Navigate to the folder containing your Umbraco website.
Install the Umbraco Engage Nuget package with the following command:
If you have any trouble, please go to Troubleshooting installs.
When you have installed Umbraco Engage, build or restart your website, and the Marketing section will appear in the backoffice, as shown above.
The next step is to configure a license.
It is recommended to consider the information detailed in the section below, to get the best out of Umbraco Engage.
If you have installed Umbraco Forms as well and want to automatically track submissions of Umbraco Forms. Please install the package Umbraco.Engage.Forms via NuGet as well using your preferred approach as above.
PUT THE FOLLOWING TWO INTO TABS
To capture events that happen on the clientside (frontend) of your website, you need to add the clientside tracking script. This is done by including the following snippet on all of your pages.
Cockpit is a tool to help with testing segments and diagnose the data Umbraco Engage collects. It can be viewed on the frontend of your website, only if you are logged into Umbraco as well.
Install cockpit on your website by adding the following Razor Partial View in your templates in Umbraco before the closing </body>
tag
Learn more what Cockpit is and how you can use it.
Here are some optional extras you can do to improve your experience with Umbraco Engage.
Add a Google Analytics bridging script that automatically sends events that you send to Google Analytics, to Umbraco Engage as well.
Add the Google Analytics blocker detection script. This gives you insights in which page traffic Umbraco Engage will track, and Google Analytics will not track.
If you need to influence the default The Umbraco Engage cookie behaviour please go here. Or go to an example implementation using Cookiebot which can be used as an example for other cookie consent providers.\
If you change the default cookie behaviour make sure to perform a client side reload of the initial page after cookie consent. If this is not done, visitor referrer and/or campaigns will not be tracked.
Are you using a load-balanced setup or separate CM and CD environments? Please check our documentation about this topic.
Documentation on how to work with Umbraco Engage for both marketers and developers.
This is the official documentation for the Release Candidate of Umbraco Engage.
Learn more about the product and the expected release date on the product pages on Umbraco.com.
Umbraco Engage is currently only available for Umbraco 13.
Umbraco Engage is a marketing suite that helps marketers and developers create personalized, data-driven experiences for website visitors. This documentation provides a complete guide for setting up analytics, A/B testing, and targeted campaigns using all the features of Umbraco Engage.
Explore the top features and learn more about Umbraco Engage on Umbraco.com.
Use the checklist in this article to verify your Umbraco Engage installation.
If you have problems with Umbraco Engage setup or configuration, this checklist is for you. Verify you installed the Nuget package Umbraco.Engage into your Umbraco website
After logging in to Umbraco you can see the Marketing section next to the other main sections in the Umbraco backoffice.
If you cannot see this, please check if your Umbraco user or user group has access to the Marketing section.
When editing a page within Umbraco you should be able to see the following Content App on the top right of the page:
If you cannot see this, please check if your Umbraco user or user group has access to the Marketing section.
Is the Umbraco Engage Cockpit tool visible on the front end of your site after logging into Umbraco?
No? Ensure you added the Cockpit Partial view in your main template.
Can you see client-side data such as scroll depth & total time on pages in analytics or the cockpit?
No? Ensure you have added the client-side tracking script in your main template.
Go to a form and add a new question. Do you see this option?
Go to Marketing -> Settings -> Create a new goal. Do you see the following option called Umbraco Forms Submission?
If you see both options, this has been configured correctly. If not, ensure that your development team has installed the additional Umbraco Engage UmbracoForms NuGet package.
Edit a page and go to the Content App marked Analytics or Marketing -> Analytics from the top navigation.
Are you able to see analytical data? If not then you need to wait 24 hours for today's analytics to be collected and reported.
Do you only see <unknown> in the Location tab of Analytics?
This means that additional configuration is required. Get in touch with a developer, as they need to work to set up and track visitor locations by country and city.
Once set up, you will see analytics for countries like this below:
Confirm that the IP of your company/office building has been set to be excluded from Umbraco Engage. This is done to ensure it is excluded from tracking and reporting, along with anyone else who is a content editor of the website.
You can check your IP by Googling for What is My IP. Ensure it is in the list of IPs by navigating to Engage -> Settings -> IP Filters.
To ensure that Umbraco Engage can interact with the visitor from the first page, reload the page as soon as the Cookie consent is approved. This enables showing personalized variants on the landing page which requires consent. More info on how to do this can be found at the bottom of the tracking a visitors initial pageview article.
If you have performed all the steps and do not see Analytics data within Umbraco Engage there are a handful of additional steps to take. Please work with a developer to check the following technical steps.
Open your website in a browser with the browser developer tools open.
Refresh the page while the developer tools are open.
Look for a POST request being made to umbraco/engage/pagedata/ping
in the Network Tab of requests
Only 'real' visitors will be tracked and any information we determine to be from a bot is discarded. The following steps are taken to report a page view:
DeviceDetector.NET will assess if the visitor is a bot or a 'real' visitor.
If it is a 'real' visitor the page will send a POST request to umbraco/engage/pagedata/ping
and record a visit.
If they are deemed a bot, they will not make this request and no page view will be tracked
If the POST request still does not happen, reach out via support.
Learn about the system requirements before installing Umbraco Engage.
Umbraco Engage has the following requirements:
Umbraco version 13
SQL Server 2014+, LocalDB, or Azure SQL.
SQL CE & SQLite are not supported.
It is recommended to upgrade your Umbraco installation to the latest version of Umbraco 13.
See the Troubleshooting section if you need to upgrade from SQL CE to SQL Server.
Umbraco Engage is compatible with Umbraco Cloud.
Umbraco Deploy is currently not supported for the Umbraco Engage features.
Learn more about recommendation when is comes to infrastructure and database.
The number of page views and Peak Load are two important metrics for determining the optimal infrastructure sizing for a project.
The following presents recommendations based on the environment and the number of expected page views.
100.000 page views per month or less: Database: CPU 2, 4-8 GB RAM, 50GB disk
500.000 page views per month or less: Database: CPU 4, 8-16 GB RAM, 100GB SSD disk
1.000.000 page views per month or less: Database: CPU 8, 16-32 GB RAM, 250GB SSD disk
1.000.000 page views per month or more: Please contact our Expert Services team to discuss the infrastructure requirements.
Due to the rapidly changing naming and sizing of Azure instances, we recommend using the appropriate supplier tools to determine the exact sizing. Base the sizing on the non-cloud recommendations above.
In general, for Azure SQL, use at least a S3 instance for production purposes.
100.000 page views per month or less: Professional
500.000 page views per month or less: Professional (with dedicated resources)
500.000 page views per month or more: Professional / Enterprise (with dedicated resources)
Always discuss the exact requirements with your agency or the Umbraco Cloud team. Discuss Prioritized Cloud Computing, Prioritized Database Performance, and Dedicated Resources based on the expected load.
Above you will find general recommendations on which infrastructure parameters to use. While these should work well for most cases, you may need to adjust the infrastructure parameters to suit your page view processing workload. Large or heavily trafficked websites may have higher requirements. If you expect high page view peaks it is recommended to scale to a tier higher than normal.
Recommendations for using Umbraco Engage within a load-balanced setup.
Make sure your Umbraco is set up according to best practices. Please refer to the Umbraco documentation for more details.
For the Cockpit to function properly it is necessary that the cockpit can read the Umbraco login cookie. Umbraco and the site should run on the same domain or sub-domain.
For example:
Umbraco: umbraco.domain.com
Site: domain.com
Make sure the AuthCookieDomain
in your SecuritySettings of your Umbraco config has the following value:
To learn more, read the documentation about the SecuritySettings
You need to configure machine keys and data protection to use the same keys on all servers (content delivery and content-management).
Without this setup, each server will generate its own key. This will result in the Umbraco authentication cookie being encrypted and decrypted using different keys leaving the Cockpit unusable on the frontend servers.
To learn more, read the Load Balancing article in the Umbraco CMS documentation.
Umbraco Engage will perform a ping (POST) to detect if the visitor is a visitor or a bot. The umbraco/engage/pagedata/ping
URL should be accessible from the content delivery and front-end servers. Make sure no firewall or other mechanism is blocking POST requests to umbraco/engage/pagedata/ping
. If this URL is blocked, all visitors will be treated like a bot and no analytics data is collected.
Make sure the IsProcessingServer
is set to true
on the content management (Umbraco) environment and to false
on the content delivery or front-end servers.
The setting can be set in yourappSettings.json
file.
Sticky sessions, also known as session affinity, are essential for the proper functioning of Umbraco Engage in a load-balanced environment. Sticky sessions can be enabled using different methods such as cookie-based, IP-based, or URL-based session affinity, depending on the load balancer configuration. By enabling sticky sessions, you can ensure that user sessions remain intact and data consistency is maintained across the Umbraco Engage application. Sticky sessions will ensure that analytics, A/B testing and personalization works properly.
For specific instructions on enabling sticky sessions, refer to the documentation or configuration settings of your load balancer.
Add extra Umbraco Engage functionality to your website using the templates detailed in this section.
As a marketer, you want to interact with your website visitors without the help of a developer. Find in this section, templates to jump-start your onsite visitor interaction.
With the help of these generic CSS and JavaScript templates, you will be up and running within 5 minutes.
Find information to effectively integrate and customize Umbraco Engage within your environments.
In this section, you will find essential information on system requirements, licensing details, and infrastructure considerations.
Get insights on sizing your infrastructure to meet your project's demands.
Discover best practices for setting up load balancing and managing continuous integration and deployment environments.
Explore recommended CDN options to improve content delivery speeds.
View with the technical aspects of the Cockpit for managing marketing features within Umbraco Engage.
Learn more about recommendations when working with the Content Delivery Network.
This article provides information and best practices on using Content Delivery Network (CDN) with Umbraco Engage.
Do not cache pages on the CDN level. Umbraco Engage is based on serving a unique page to every (returning) visitor. By enabling page caching every visitor will be assigned the same Umbraco Engage ID and Analytics, A/B testing, and Personalisation will not work correctly.
It is possible to cache static CSS and JavaScript files. Refer to the documentation of the CDN provider for the best-practice setup.
It is possible to cache /media
files. Refer to the documentation of the CDN provider for best-practice setup.
This section guides you through the initial setup and configuration of Umbraco Engage.
Are you are a marketer looking to create personalized content or a developer integrating Umbraco Engage into your infrastructure? This section offers essential articles on configuring the system, understanding its features, and optimizing it for your needs.
The Cockpit is a tool to let you view data directly on the front end of the website. The cockpit is only visible if the cockpit add-on script is installed and if you are logged on to Umbraco.
The cockpit lets you check out all the stored data when browsing the website. It is also a good way to verify your personalization setup.
You should see the Umbraco Engage Cockpit on the left or right side of the screen:
Click Open to see all the features of the Cockpit:
When the Umbraco Engage code has been added to the page you can see it when you are logged in to Umbraco. Visitors to your website do not have access to the Cockpit.
If you do not see the Cockpit while the Umbraco back-office runs on a different domain please contact the technical team and refer to the load balancing / CM / CD environments section.
If the additional analytics script of Umbraco Engage is installed you can find all tracked data in the Cockpit.
The following information is tracked:
The time on page. This is defined between the time the page was loaded and the current time. If you visit the website at 11:23:12 and it is now 11:25:30, your time on the page is 2 minutes and 18 seconds.
The engaged time on page. This measures the time you were active on the page. When you scroll, move your mouse, type, or select text on the website you are considered "engaged". As soon as you stop one of these actions and have no other interaction in the next five seconds this engaged timer will be stopped. This could happen when you are browsing in another window or tab of your browser or system or when you leave your computer. The time on the page is still counting, but you are not engaged at that moment.
The script tracks the maximum scroll depth that you have reached. This counts in absolute pixels and as a percentage.
All fired events are tracked.
Every out-click to other domains, a pdf file or excel file is measured by default.
In this section you can see all the data that is captured on the server side:
The browser,
The type of device,
The IP address (anonymized or not; depending on your settings)
The total number of pages visited in this session
The total number of sessions with this cookie
Also, you have the option to delete your Umbraco Engage cookie
In the segments section, you can see which segments are configured and which are applied to the current visitor.
The Cockpit is a tool to let you view data directly on the front end of the website.
Umbraco Engage includes a cockpit feature to help verify the tracking of analytics and understand personalization behavior. The cockpit adds a button to the front end, giving real-time insights.
To add the cockpit to your website:
Render the HTML partial provided by Umbraco Engage.
The partial view is located at /Views/Partials/Umbraco.Engage/Cockpit.cshtml
.
Insert the following code before the closing </body>
tag:
Once the code is added, reload the page to see the Umbraco Engage Cockpit on the left or right side of the screen. The cockpit will only be rendered if the user is logged into Umbraco.
Clicking the Open button provides detailed information:
Explore the Engage section to access Analytics, A/B Testing, and global settings for Umbraco Engage.
When you install Umbraco Engage, a new section called Engage is automatically enabled in the Umbraco backoffice.
If you do not see the Engage section, it is likely that you have not been granted access to it. You can set up access in the Users section of Umbraco. If the Engage or Users section is not visible, ask your administrator for assistance.
In the Engage section, you will find several subsections, each providing insights into a specific feature of Umbraco Engage.
Currently, the available sections are:
On the dashboard, you can view the current version of the Umbraco Engage installed and see how the license is configured.
The Marketers and Editor section contains knowledge and tools required to leverrage Umbraco Engage effectively.
This section covers a range of topics, including an introduction to the platform and its various components, personalization, reporting, and so on.
Explore the Umbraco Engage section to access Analytics, A/B Testing, Personalization, Profiling, Reporting and global settings.
Discover how the Content Apps enhance each node with different features for improved content management.
Umbraco Engage uses a cookie to collect visitor data on your Umbraco website. Learn more about how it works in this section.
The Profiling section helps track visitor sessions, manage profiles, and differentiate between identified and anonymous visitors.
The Settings section provides insights on excluding the traffic from specific IP addresses, setting up and implementing goals, and much more.
Learn how the Umbraco Engage cookie works and how the functionality can be tested.
When visiting a website with Umbraco Engage installed you will get a unique cookie. This cookie allows for relating different page visits or sessions to the same visitor. It will also continuously serve the same variant of an A/B test.
By default the Umbraco Engage cookie has the name umbracoEngageAnalyticsVisitorId
. You can change the name in the .
The Umbraco Engage cookie:
Is a first-party cookie. This means it is set by the website itself and can only be used by the website itself. The cookie will not track you across the whole internet on all kinds of websites (like Facebook and LinkedIn).
Sets the HttpOnly
flag.
Sets the Secure
flag.
Is initialized with an expiry date of 365 days (depending on the settings in the configuration file) and has a sliding expiration. That means that if you revisit the website after 30 days, the cookie will reset and expire 365 days after that visit.
To test whether the A/B test is working and distributes the different variants you can use . Delete the Umbraco Engage cookie to become a new visitor to the website and you can test whether it works .
Consult your browser settings to learn how to delete the cookie.
By default, all modules are initiated at the first-page request. If you want to override this behavior, read the documentation about the different .
Discover how the Content Apps enhance each node with different features for improved content management.
In the content section of Umbraco you'll see all Umbraco nodes and most of them will relate to a specific page in your website. If you have installed the Umbraco Engage each Umbraco node will have three extra Content Apps.
If you navigate to a node you will see the Analytics content app. If you open the Content App the Analytics data of this specific node is loaded.
The A/B testing content app will allow you to test your Umbraco node within the splitview functionality. Every document type can be A/B tested:
The personalization content app allows you to score this specific page on the customer journey & persona (if you want to implicit score your content). It also allows you to setup personalized variants of each node.
In the settings of the Engage-section you can manage on which document types these content apps are displayed, and which Umbraco user groups have access to these content apps. They can be easily managed per document type and per user group
If you do not see the Cockpit while the Umbraco backoffice runs on a different domain please refer to the section.
: The most important feature of Umbraco Engage is where all data is collected.
: Set up new projects and start A/B testing directly.
: Implement your marketing strategy and set up your personalizations.
: See how visitors engage with your site.
: See how your optimizations contribute to your goals.
: View and configure various global settings used throughout Umbraco Engage.
Explore the Analytics section of Umbraco Engage to view collected data, client classifications, and options for extending data collection.
In the Analytics section, Umbraco Engage displays all the collected data. This data is gathered through both server-side and client-side tracking.
In this section, you will find:
Which data is collected
How different clients visiting your website are classified
How you can extend the data collection with your own custom data
The Analytics section is accessible from the Engage section and as a content app on each node.
Learn what Umbraco Engage tracks before any additional configuration is added.
If you install Umbraco Engage we will automatically collect a lot of data for you.
Serverside the following data is tracked:
The URL of the visited page (/foobar/
)
The query string of the visited page (?filtering=on¶meter1=2
)
The variant of the page that we serve. This could be a personalized version of the page or one of the A/B-test variants.
The time that the page was visited (31 august 2021, 16:04:22
)
Where the visitor came from before this visit (the so-called referrer). This could be an internal webpage (/my-contentpage/
) or an external URL (www.umbraco.com/products/engage/
)
The browser being used (Firefox), the Operating System used (Windows), and the type of device being used (Desktop). These data points are based on the user-agent string that any browser is sending.
The IP address (213.62.44.123
) or anonymized IP address (213.62.44.0
), depending on your configuration.
With the data collected, the Analytics reports in Umbraco Engage can be visualized. It also allows us to calculate other metrics, such as conversion rates, bounce rates, and landing & exit pages.
If you include the clientside collection script as well, you can also capture behavioural data of your visitors.
Learn about what scripts can be used to connect with other data-gathering tools.
Umbraco Engage helps you with some additional scripts and views.
Find more information about the scripts in the Analytics section for Developers.
Learn more about how Umbraco Engage distinguishes between bots and real visitors.
Engage only tracks 'real' visitors and discard any visit we determine to be from a bot. The data for bots is not stored in Umbraco Engage and cannot be viewed in the Analytics section. From an SEO perspective, bots, search engine crawlers, spiders, and the like, will always see the default content so no personalization and no participation in an A/B test.
The tracking of a visitor is done via the following steps:
DeviceDetector.NET will assess if the visitor is a bot or a 'real' visitor` using the device ID of the browser.
If it is a 'real' visitor the page will send a special ping request to Umbraco Engage to record the visit. If this ping is not received the requests of this visitor will not be tracked.
Discover the Campaigns tab in Umbraco Engage to track UTM-parameterized campaigns and analyze their performance metrics.
In the Campaigns tab of the Umbraco Engage, you can view all analytics data related to your campaigns. These campaigns are tracked automatically using Urchin Tracking Module (UTM) parameters, which you may already be using to monitor your marketing efforts.
You can add five different parameters to your URLs:
utm_source: Identify the advertiser, site, publication that is sending traffic to your property. For example: google, newsletter4, billboard.
utm_medium: The advertising or marketing medium. For example: cpc, banner, email newsletter.
utm_campaign: The individual campaign name, slogan, promo code for a product.
utm_term: Identify paid search keywords. If you are manually tagging paid keyword campaigns, you should also use utm_term to specify the keyword.
utm_content: Used to differentiate similar content or links within the same ad. For example: if you have two call-to-action links within the same email message, you can use utm_content and set different values for each so you can tell which version is more effective.
Each parameter must be paired with a value that you assign. Each parameter-value pair then contains campaign-related information.
For example, if you want to link from a newsletter to the pricing page of the umbraco.com, you can use the following parameters:
utm_source = newsletter-july-2024 to identify that this visitor came from this specific newsletter
utm_medium = newsletter to show that the medium was a newsletter
utm_campaign = more_signups because that newsletter was part of a larger campaign
utm_content = bottom_button to identify a specific link in the newsletter
If you want to use these parameters, you will need to set up the URL like:
The report shows all campaigns set up with the utm_campaign
parameter.
You can see:
How many visitors came to the website via the campaign URL?
How many sessions were created?
How often was a goal triggered by visitors from this campaign?
You can also drill down to view the source and medium for each campaign.
Explore the Device Type report in Analytics to analyze visitor distribution across desktop, tablet, and mobile devices.
In the Devices report within Analytics, you can view the ratio of visitors using different devices. It shows how many visitors access your website via desktop, tablet, and mobile.
Learn more about the difference between how Umbraco Engage and Google Analytics measure traffic in your website.
You can see a difference in statistics (Pageviews, Visitors, etc.) between Google Analytics and Umbraco Engage.
Umbraco Engage will collect pageviews unless Google Analytics / GTM is blocked or GA / GTM cookies are not accepted. So approx. 10% - 25% more pageviews in Umbraco Engage compared to GA should be considered as normal depending on the audience with the current available information.
This article describes what data is tracked from videos on your website.
Umbraco Engage gathers video statistics for the following types of videos:
HTML5 videos (videos provided via the <video>
element)
Embedded YouTube videos
Make sure the embed URL contains ?enablejsapi=1
as part of the full URL to enable tracking. The src
property of the iframe should be something like: https://www.youtube.com/embed/<CODE>?enablejsapi=1
.
The https://www.youtube.com/iframe_api is loaded for this purpose.
Embedded Vimeo videos
The https://player.vimeo.com/api/player.js is loaded for this purpose.
For the videos, the following information is gathered:
Video URL
Video name
For YouTube and Vimeo the name can be retrieved.
For HTML5 we record the file name.
Total Time Watched (seconds)
Total Percentage Watched
In Viewport
True if the video was in the user's viewport.
Watched
True if the video played for at least 1 second.
Apart from the metadata above we also track actions performed on the video player. These actions are:
By collecting this data you can visualize different reports about the videos. You will find these reports in the Analytics subsection and the tab Videos.
Here you find all the videos that are displayed on the website. For each video you can see the following:
How often was the video played?
The total playtime of the video.
The average video playtime of the video.
From here you can also drill down on a specific video to see more details about that video. You can do that by clicking on the video itself.
You see how often the video was started and paused, how often it was resumed, and how often visitors sought within the video.
Examine the Referral Traffic report in Analytics to track visits from external sources and view detailed referral paths.
In the Analytics - Referrers tab, you can view all visits to your site that originated from external sources.
To see the specific path a visitor took, click on the domain, and it will display all exact referral paths.
Learn about what localization data is tracked and how you can view it.
Locations are not visible out of the box. You need to add a location provider which can be set up by a development team.
The localization information is displayed under the Location tab in the Analytics section of the Umbraco Engage dashboard:
The graph contains all sessions started within the given time, similar to the "New and returning visitors" tab. This information is not location-bound and the graph is always displayed, even if no localization information is available.
Underneath the graph, is the table containing session and pageview information based on country.
If the pageviews contain location information, the table with countries is displayed:
There might be cases where you see a message saying that no data is available or that all locations are <unknown>
. This will occur when the LocationExtractor service is not implemented, or if the pageviews for the given date range do not contain location information. Please consult the technical team to implement the location extractor.
From the country, you can drill down to a city. This will filter the displayed data to display session and pageview information for the selected country. Even though Umbraco Engage does support the storage for county and province, currently the UI only supports displaying data by country and city.
Action | Description |
---|---|
Autoplay
If the video was started automatically.
Play
When the video starts playing.
Pause
When the video is paused.
Resume
When the video is resumed from a Paused state.
Ended
When the video is ended.
Seek
When a seek operation is performed.
Learn how you can use the Scroll Heatmap in Umbraco Engage to gather data on the behaviour of your visitors.
The Scroll Heatmap shows you how your visitors consume your content.
The feature gives a visual representation of the average scroll depth of your visitors on a specific page. This feature is only available within the Analytics Content App on an Umbraco page.
An advantage is that you do not need to integrate any 3rd-party tools. This will prevent additional load times and possible issues with data ownership.
The heatmap only collects data if the client-side script is installed on your website.
It goes too far to give a total overview of what A/B testing is. There are some great resource out there that can inspire you and can go in real depth what A/B testing is.
For now we will stick with this explaination: A/B testing is a methodical way of testing (and hopefully improving) your website. By serving two or more versions of a webpage, contentblock or website to different visitors results can be gathered which version is performing better for a specific conversion goal.
Your website is always underperforming its potential. Your website will never have a conversion rate of 100% (all visitors do exactly what you want them to do) and probably not even near that conversion rate. By testing specific parts of your website you can experiment and hopefully increase your conversion rate. The internet gives you the ability to test with different variants of your website and see what happens.
There are already a lot of great A/B testing tooling out there (Google Experiments, Optimizely, Visual Website Optimizer). They do a really great job on A/B testing but they all lack a key feature that Umbraco Engage has; Umbraco Engage is fully integrated within Umbraco. This allows you to integrate A/B testing in your daily workflow instead of an add-on on top of your website. This means:
You can A/B test your content in exactly the same and user-friendly way that Umbraco does. This will enable you and your editors to start A/B testing really easy.
The A/B test is rendered automatically without any additional line of code. This means that you don't have to reserve time to "implement A/B testing". It is just there and you can start immediately start testing. Also that means there is no content flickering like in many other tools (just for fun... Google for ""...)
You can use all the resources that Umbraco gives you. You can reuse images of the media library, you can pick contentblock as you are used, and you do not have to worry about changing url's while doing a test.
Within Umbraco Engage you will see that A/B tests are running, so your fellow editors are aware of this and will not ruin your experiments
Because we use first-party analytics and cookies you will track data across all your visitors and not only on a subset of customers which do not have any ad- and cookie block tooling
Our A/B test is context aware and will make sure that the A/B test is render everywhere correctly. For example; if you are testing a catchy product title it will automatically not render only that new title on the page itself, but also on your overview, your homepage, your shopping cart or at any other place you're using the title. This is impossible with any other tool!
There are a lot of books out there that do a great job explaining the importance of A/B testing and why you should start testing your website today. A short list of the books that inspired the Umbraco Engage team:
Umbraco Engage enables running A/B tests on pages using a specified Document Type. This article covers how and when to use this type of test.
Test all pages using a specific Document Type with this test. Select the Document Type(s) you want to test and Umbraco Engage makes sure the correct CSS and JavaScript is inserted to the correct pages.
The test type "Document Type" can be started in the Engage and in the . The type is selected in step 2 of the setup.
The test allows you to select one or more Document Types within Umbraco. On all pages using the selected Document Type(s) the A/B Test will render the additional CSS and JavaScript you will enter. The CSS and JavaScript must not create any side effects on these pages. This is a manual task.
Once you have selected the pages you want to test, you can specify one or more variants. For each variant, it is possible to click the Edit button. This will bring up a popup that allows you to write JavaScript or CSS:
In this example, some JavaScript changes the page's background color.
You can save and preview whether your code works by clicking Save & preview.
Learn how data from Umbraco Forms is tracked with Umbraco Engage.
To track Umbraco Forms submissions, you need to install with a valid license. You also need to install the Umbraco Engage.
Umbraco Engage measures interactions with Umbraco Forms on your website automatically if you include the . No additional configuration is needed. The data is visualized in the backoffice in Engage > Analytics > Forms.
The following are measured:
The time a visitor started filling in the form.
The time a visitor finished filling in the form (like when it was submitted).
If the visitor has seen the form, and whether it was in their viewport.
If the form was submitted successfully.
This is based on client-side validation only. If client-side validation passes it is seen as a successful submit.
If the form raised any client-side errors, and how many were raised?
Focus/unfocus events of each field and whether the field was empty or contained data at that time.
The "Forms" tab in the Analytics section holds all data gathered about your forms.
In this overview you can see the following:
How many times a form is shown.
How many times a visitor started filling in the form.
The number of times a form was submitted (filled in and hitting the "submit" button).
How often a form was abandoned before it was submitted.
How many errors were triggered in the form.
Select a form to drill down to this specific form and see more details for the specific form fields.
For each field you see:
How many times did the field receive focus.
How often was this field the last field before a visitor abandoned the form.
How often an error was triggered on the specific field.
This data gives you insights on how to optimize your forms to create a better conversion rate.
Finally, you can drill down to a specific field to see which type of error was triggered, be it a validation error or a mandatory error.
It is possible to track a specific visitor to your website and see if they have made any form submissions. To do so, follow these steps:
Edit the Umbraco Form you wish to track visitors for and go to the Design view.
Add a new field to your form called 'Analytics - VisitorId`.
Give the new form field a name such as Visitor ID.
Specify a URL in the settings of the field type called Template:
The URL above is a link to your website, including a visitor ID. By using a URL like this you can click directly through to view the visitor profile from Forms workflows. This includes emails, Slack messages as well as exported Excel data.
By adding the umbraco-engage-no-tracking
attribute you can disable Umbraco Forms tracking on the form or field level. The attribute needs to be added to either the form tag or to a field tag (like input, select, or textarea).
Umbraco Engage provides the option to set up A/B testing on individual pages. This article covers how and when to use this type of test.
The Single-Page test allows an editor to start an A/B test without a single line of code.
When you select the Single-Page test type you can create two or more variants.
The first variant is always the original content and the published page. Variant B is the first variant that can be created and with the button 'Add a variant' more alternatives can be added. More variants mean that a test should run for longer to become reliable.
The variant can be given a name and if you click on Edit you will open up the split view editor:
On the left side, the original content is shown (Original) and the variant is shown on the right. In this side-by-side editing mode, you can edit the content for your variant.
Specifying when segmentation is allowed can be done per property using the Allow segmentation value.
In the overview of the Document Type, you will see if properties can be segmented as they will have the Vary by segments label:
Sometimes you cannot adjust a specific property because it was not configured when Umbraco was set up. In those cases, you can use the CSS/JavaScript field to add a code-snippet to make these adjustments. The best way is to do it via property editing in the split view edit mode. You do not have to write any CSS or JavaScript code.
To do this click CSS/JavaScript in the A/B Testing editor bar:
This will give the editor a popup where CSS and JavaScript can be entered:
These lines of code will automatically be inserted at the bottom of the page.
Use the Save & preview button to make sure all works as expected. This can also be done via the "Save & preview" option in the editor bar.
Once the variant is set up, finish the A/B Test via the Back to A/B test button in the editor bar.
Because of the unique implementation of Umbraco Engage, the content will automatically be updated for this variant.
The algorithm will determine which variant of the propety needs to be rendered.
Umbraco Engage provides the option to run A/B tests across multiple pages. This article covers how and when to use this type of test.
The Multiple Pages test allows you to across multiple pages at once. In Umbraco, you can select the pages you want to test. For all these pages you can specify which type of CSS or JavaScript will be added to the specific variant. The multiple pages test requires you to write (or copy in) some CSS and JavaScript code.
The test type Multiple pages can be started in the and in the . The type is selected in step 2 of the setup.
The test allows you to select one or more pages within Umbraco. On all these pages the A/B Test will render the additional CSS and JavaScript you enter. The CSS and JavaScript must not create any side effects on these pages. This is a manual job that cannot be automated with Umbraco Engage.
Once you have selected the pages you want to test, you can specify one or more variants. For each variant, it is possible to click the Edit button. This will bring up a popup that allows you to write JavaScript or CSS:
In this example, some JavaScript is added to change the page's background color.
You can save and preview whether your code works by clicking Save & preview.
To set up an A/B test in Umbraco Engage you need to go through a series of steps. Learn more about the required configuration is required for initating a test.
Setting up an A/B test in Umbraco Engage requires no code or need for any external tooling.
Starting A/B tests can be done in two ways:
Initiate a Single Page, Multiple Page, or Document Type test via the Content App on the specific page,
Initiate Multipage and Document Type tests via the Marketing section.
Open the Umbraco content tree and select the A/B tests Content App on the page.
When you open the Content App you will have an overview of all the A/B tests that are running or finished. You also have the option to start a new test.
When you start a new test you will have to specify the following:
The name of the test.
Which testing project it should be part of.
Write a description/hypothesis.
After that, you have to specify the type of test and set up the specific test. It is also possible to preview your variant from here.
As a final step, you need to specify which goal you want to measure, as it is all about optimizing for this goal. Set the audience that you want to include in the test.
Once you have set everything up the test is ready to go. You can preview the final variants and check if everything set up correct.
If that is the case you can start the test immediately, or schedule it for later.
Dan Siroker and Pete Koomen. A/B Testing. The most powerful way to turn clicks into customers. Hoboken, New Jersey: John Wiley & Sons, Inc., 2013.
Chris Goward. You should test that! Indianapolis, Indiana: John Wiley & Sons, Inc., 2013.
Will Kurt. Bayesian statistics the fun way. San Fransisco, William Pollock, 2019.
After creating all variants, start your A/B testing as written in the article.
Some properties are inactive (visually indicated because they are greyed out). Which properties you can edit is specified in .
Finish the steps in the article to verify and start your A/B Test.
After you have created all variants start your A/B testing as described in the article.
Make sure that you have access to the Content App. per Document Types or User Groups.
Umbraco Engage offers multiple ways for performaing A/B tests on your website. Learn more about each option and how to configure them in this section.
A/B testing is one of the main features of Umbraco Engage. A/B testing allows you to test your website and specific pages with two sets of configurations. Umbraco Engage supports both the novice and the experienced A/B tester.
This documentation section will help you out with A/B Testing, and covers the following topics:
A brief overview of what A/B testing is.
The kind of A/B Tests that Umbraco Engage supports.
How you can set up the A/B test.
How the results during an A/B test can be analyzed.
How a visitor is assigned the A, B, or n-variant.
Umbraco Engage takes care of applying the correct styles to the pages part of your A/B tests.
The A/B Test will automatically be rendered in your front end. If you have set up a Single page A/B test Umbraco Engage will automatically render the correct properties.
If you have set up one of the other tests and added some CSS and JavaScript this will automatically be added to your webpage.
You do not have to do anything to render the A/B test. If you want to run a more advanced A/B test that requires more coding, you can always do that.
Split URL testing in Umbraco Engage helps you compare different versions of a page.
You create different versions of a page. Each version can have different designs, text, or buttons based on the possibilities that have been setup in Umbraco.
When you set up the A/B test, you can send 50% of visitors to page A and 50% to page B. This way, you can see which page helps achieve the goal of the test better.
The split URL test is a great way to test different checkout workflows, for example.
When running A/B tests using Umbraco Engage it recommended to preview the test before running it. Learn how this is done.
There are different ways to preview your A/B Test variants. In this article, we will discuss all options.
When setting up a new A/B Test there are three options to preview your A/B Test variant. First of all, you open the preview of your variant by clicking on the preview button in the overview of variants:
When editing a specific variant on a single page you can also preview the page. In the top bar, there is a Save & Preview button available:
You can also click on Edit variant which will open a pop-up where you can add some CSS and JavaScript. Also from here, you can open up the preview by clicking on Save & preview:
There are plenty of options to open up the preview.
With all variants set up, you can get an overview before the A/B Test. In that screen, you also have the option to preview all variants:
You can preview all the A/B test variants while a test is running. Go to the specific test, and you will have an overview of the current results. You can also preview each variant by clicking the "preview"-button.
Umbraco Engage distributes visitors randomly across the different variants of your A/B tests.
The default algorithm is based on randomness. When visitors visit the website or a specific page with an A/B test, they get randomly assigned a variant. That variant is stored alongside the visitor's cookie and the same A/B test variant is shown as long as that cookie exists.
Because the algorithm is based on randomness the visitors are not equally distributed between the variants and slight differences can occur.
In the test shown below, the variant distribution is not a perfect 33,333% as you could expect with three variants.
Get an overview of the available types of A/B tests you can run with Umbraco Engage.
Three different types of A/B tests are available:
Single-page tests to test a specific page within Umbraco.
A way to test multiple pages at the same time.
Test an entire Document Type and all of the pages using this type.
Split URL testing. This enables you to select two or multiple pages and serve one of these URLs per visitor.
The A/B tests are set up within an Umbraco context. You can reuse properties that are already created. Umbraco Engage is also aware of the structure of your website and concepts like Document Types.
When setting up the A/B test, you can select the type of test you want to set up.
A Single-Page test can only be started in the A/B test Content App and not from the Engage section.
When the A/B test has enough data for a statistically complete picture, Umbraco Engage will notify you. You can also end the test at any time.
You can decide to finish an A/B test at any time. Normally, you would end a test if it has been running long enough and enough data to gain enough confidence is collected.
Umbraco Engage lets you know when the collected data is statistically significant. The same applies to when not enough data is collected.
Even if not enough data is collected you can always decide whether a running A/B Test is complete. In the overview you can see all tests and their performance:
To end a test, click End test. This will open a confirmation dialog asking if you want to pick a winner directly.
You might want to discuss the results with a colleague or client. In that case, it makes sense to stop the A/B test, but complete it by picking a winner at a later point.
If you select Stop and complete now the A/B Test is stopped and you can select which variant was the winner:
You can always pick one of the variants or My test did not result in a winner. After you confirm your selected winner the overview will show the picked winner:
The overview of the A/B tests will also not show that the A/B Test is stopped and a winner was selected:
Umbraco Engage provides the ability to continuously monitor the A/B tests you are running on your website. It is recommended to disable tests that perform poorly.
When the A/B test is running it is advised to check the progress regularly. This can be done on the specific page or via the Marketing Section.
If you go to the overview you can see all running tests. The overview includes the following information:
For how long a test has been running?
How many visitors are included in the test?
For how long should the test run to produce relevant results?
You can see all test variants when you access the details on a test. You can preview the variants, or disable them. If for example, the conversion rate has decreased in a variant, it could be smart to disable that variant.
The algorithm also signals the leading variant based on the Minimal Detectable Effect (MDE) which uses the 95% confidence level.
To setup implicit personalization within Umbraco Engage you can setup a specific customer journey for your website.
This can be done by going to the Engage section in your Umbraco installation and the sub-section "Personalization". There you can navigate to the tab "Journeys".
Setting up the customer journey works the same as .
The biggest difference with personas is that there is a specific order of customer journey steps within a customer journey. It is possible to add new customer journey steps between existing steps. You can also reorder the steps by dragging and dropping them in the correct order.
When installing Umbraco Engage we add one customer journey based on the Google customer journey with the steps See, Think, Do and Care.
When installing Umbraco Engage we add one customer journey based on the Google customer journey with the steps See, Think, Do and Care.
Personalization is one of the key features within Umbraco Engage. In a fully integrated way you can personalize the experience of each of your visitors within Umbraco.
The first thing you need to do is create a segment. A segment is a group of visitors within your website. When setting up a segment you can define which visitors are in a segment.
Once you've created a segment you can personalize the experience of your visitor. This can be done on a specific page, on multiple pages, or per Document Type.
Umbraco Engage allows you to personalize your Umbraco website via implicit or explicit personalization. To grasp the way Umbraco Engage handles implicit personalization read the implicit personalization scoring article. Another option is to see it in action in the cockpit view at the front end of your Umbraco website.
If you want to take your personalization to the next level you can always extend the way the personalization in Umbraco Engage works by default. Contact the technical team and refer to the Personalization section for Developers.
This article explains how to use the Umbraco Engage cockpit to verify tracking and understand personalization in your analytics.
Umbraco Engage includes a cockpit feature to help verify the tracking of analytics and understand personalization behavior. The cockpit adds a button to the front end, giving real-time insights:
Clicking the button provides detailed information:
To add the cockpit to your website:
Render the HTML partial provided by Umbraco Engage.
The partial view is located at /Views/Partials/uMarketings/Cockpit.cshtml
.
Insert the following code before the closing </body>
tag:
The cockpit will only be rendered if the user is logged into Umbraco.
Umbraco Engage uses both the concept of implicit and explicit personalization.
This is the "easiest" concept to grasp. For every explicit parameter Umbraco Engage is true or false. For example, the browser parameter is an example of an explicit parameter. Suppose the visitor is using a Chrome browser, or not. There cannot be much debate about this and the parameter returns "true
" or "false
".
Most parameters within Umbraco Engage are explicit and true or false.
The unique part of Umbraco Engage is that it also uses implicit personalization. Based on the behavior of a specific visitor Umbraco Engage can assume that a visitor is a specific persona or customer journey phase.
This article teaches you how to set up or . As soon as you have set these up you can use the segment parameters for the customer journey and the personas.
In the , you can use these implicit parameters the same way you would apply any other segment parameter.
By clicking personas you will see an overview of all the personas that you have set up within your installation.
In our case we see the persona groups "Profiles" and "Companies" and the personas "Data & Privacy Officer", "Developer", "Marketer", "Agency", "Company" and "Umbraco HQ". If we want to create a segment for all personas that are "Data & Privacy officer" add that persona as a parameter to the segment.
From now on you can use this segment to personalize the experience of your visitors.
You can mix and match implicit and explicit segment parameters. If you want to create a segment for the persona "Marketer" which is using the browser "Firefox" and is logged in, that is perfectly fine!
Discover how to create and manage segments to personalize the website experience for specific visitor groups.
To start personalizing the website experience of your visitor, you need to define groups of visitors, called Segments in the Umbraco Engage.
You must first define these segments and then you can start personalizing the website experience.
Segments are created via the Umbraco Engage segment builder, located under the Personalization and the Segments tab.
To create a new segment, follow these steps:
Navigate to the segment builder section.
Click Add new segment.
Give the new segment a Name and a short Description.
Select a segment type:
Core segments are the fundamental building blocks of your personalization strategy
Temporary segments are segments with an end date. If some sort of campaign is running and you want to overrule existing segments you can create a temporary segment. To do this you need to specify an end date
By default, Umbraco Engage provides the following parameters:
Persona
Journey
Browser
Device type
Time of day
Number of sessions
Logged in members
Reached goals
Campaigns
By clicking on the tile you will set up a parameter for the segment. For example, you can implement a segment where you group all visitors that use Firefox after 15:00 in one segment. To do that:
Create a new segment with the name My first segment.
Click the Browser tile and include all visitors using the browser Firefox.
You will see all browsers that have visited the website. So if you're missing a specific browser, that is because a visitor to your site has yet to use that browser.
Save the parameter and the segment will show the parameter that is part of this segment.
Add a parameter for Time of day to select all visitors after "15:00". Enter 15:00 in From and leave Until empty.
Save this parameter and add the segment.
We have now created a first segment and you will find that segment in the overview of your segments:
You can edit or delete segments using the icons next to each segment in the overview. Segments can only be deleted if there is no personalization applied to the segment. The third column shows how often the segment is used:
By hovering over the icon you can see what kind of personalization is applied:
If you try to delete this segment, a popup notifies that personalization is applied and it is impossible to delete the segment at this moment.
The popup shows which pages the personalization is applied and you can click directly on these pages.
The order of the segments is really important because only one segment can be applied per visitor. So if a visitor falls into multiple segments the segment with the highest priority is applied. It is only the case if there is an actual personalization available. If the highest-ranking segment does not have any personalization applied, it will go to the next available segment that has personalization applied. If none of the segments has personalization applied, it will fall back to the default content.
The ordering of segments is based on:
Temporary versus Core segments: Temporary segments are always applied first. Only if the temporary segments do not apply the core segments are being used.
Priority within each segment type: Within the temporary and core segments the given priority is being used. The highest segment will be applied first.
You can adjust the segment order using the arrows in the segment overview.
If you want to see how the algorithm works read the documentation or see it in action on your website with the .
To specify which visitors are part of this segment you can set up one or more segment parameters. Umbraco Engage comes with out-of-the-box parameters, but you can also .
Now that your segment is created, you can start .
Learn how to extract client IP addresses in Umbraco Engage by implementing a custom IP address extractor for specific server environments.
By default, Umbraco Engage extracts the IP address from the request by inspecting the UserHostAddress and the X-Forwarded-For header. The latter is commonly used if your website operates behind a load balancer. In most scenarios, this will correctly resolve the client's IP address.
If IP addresses are not being resolved accurately, your website may be behind a load balancing server or another protected environment. It might not forward the original client IP in the default X-Forwarded-For header or could exclude it entirely.
In this case, you may need to provide a custom implementation of the IHttpContextIpAddressExtractor to handle your specific requirements.
The default extractor looks like this:
To override this behavior, implement your own IHttpContextIpAddressExtractor and instruct Umbraco to use your extractor instead of the default extractor:
It is important that your UserComposer adjusts the service registration after Umbraco Engage has initialized.
This can be enforced using the ComposeAfterAttribute. Failing to add this attribute may result in Umbraco running your IUserComposer before the Umbraco Engage composer, causing your changes to be overwritten.
Additionally, ensure you use RegisterUnique<...>()
instead of Register<...>()
. While you can use Register when multiple implementations of a single service exist, in this case, you want your own extractor to be resolved exclusively. Therefore, RegisterUnique will overwrite the Umbraco Engage extractor.
After implementing both classes and running your project, your extractor should be called to resolve IP addresses. You can verify the output of your extractor by inspecting the umbracoEngageAnalyticsIpAddress database table. The last portion of the IP address may be anonymized (set to 0) if this option is enabled in the Umbraco Engage configuration file.
This article is not part of the RC Documentation.
Campaigns are one of the ways to create a implicit scoring for personalization. By setting up campaigns correctly you can assign points to personas or customer journeys.
Campaigns are automatically scored by using utm-parameters, that you may be already using for your marketing campaigns. You can add 5 different parameters to your URL:
utm_source: Identify the advertiser, site, publication, etc. that is sending traffic to your property, for example, Google, newsletter4, billboard.
utm_medium: The advertising or marketing medium, for example, CPC, banner, email newsletter.
utm_campaign: The individual campaign name, slogan, and promo code for a product.
utm_term: Identify paid search keywords. If you are manually tagging paid keyword campaigns, you should also use utm_term to specify the keyword.
utm_content: Used to differentiate similar content, or links within the same ad. For example, if you have two call-to-action links within the same email message, you can use utm_content and set different values for each so you can tell which version is more effective.
Each parameter must be paired with a value that you assign. Each parameter-value pair then contains campaign-related information.
For example, if you want to link from a newsletter to the pricing page of the umbraco.com, you can use the following parameters:
utm_source = newsletter-july-2024 to identify that this visitor came from this specific newsletter
utm_medium = newsletter to show that the medium was a newsletter
utm_campaign = more_signups because that newsletter was part of a bigger campaign
utm_content = bottom_button to identify a specific link in the newsletter
If you want to use these parameters you'll need to set the URL as:
Now that you've created URLs for campaigns they will automatically be tracked by Umbraco Engage and you can score them for implicit personalization purposes.
going to Personalization -> Campaign scoring you will see all the campaign groups, the campaigns you already scored, and the campaigns that need scoring.
First, you need to create one or more campaign groups. Campaign groups allow grouping campaigns so you do not have to set personas and customer journey scoring for each campaign only on a group level.
You can create a group for a set of personas for example and assign scores to the group. Next, you can assign different campaigns to that group and every visitor who comes to the website via that campaign. They then get the points that are referred to the campaign group.
You can add a new campaign group by clicking "Add new group". This will open up a popup where you can specify the name of the campaign group and a short description. After that, you can specify specific points for this group:
In this case, we created a campaign group "A campaign group for developers" and assigned 7 points to the developer persona. This means when visitors come to the website via a URL with utm-parameters part of this campaign group, get 7 points for the developer persona.
Because we haven't assigned any campaigns yet, in this case, the group will never be triggered.
In the tab "Unscored campaigns" you find all campaigns that have not been assigned yet. Remember again that campaigns are created by adding utm-parameters
to your URL. As soon as Umbraco Engage detects a new combination of utm-parameters it will add that combination to the list of Unscored Campaigns.
An example of this tab could look like this:
So here you see that in the last row, for example, the utm_source is "Activate account", the utm_medium is "email" and the utm_content is "click here to activate your account". The URL that the visitor used to get to the website looked something like https://<url>?utm_source=activate account&utm_medium=email&utm_content=click here to activate your account.
Every unscored campaign can be assigned to a campaign group by clicking on the "Assign" button. If you do that a popup will open that allows you to assign the specific campaign to one of your created campaign groups.
By assigning this example to the "A campaign group for developers" from now on every visitor that comes to the website with these utm-parameters
set up will get the points assigned that are set up in the campaign group. In this example, this would be 7 points for developers.
On this tab, you will see all the campaigns that are linked already to a campaign group.
You can assign the campaign to a different campaign group or delete it from the existing campaign group. By deleting it, the campaign will go back to the tab "Unscored campaigns".
To set up implicit personalization within Umbraco Engage you can set up personas for your website.
This can be done by going to the Engage section in your Umbraco installation and the sub-section "Personalization". There you can navigate to the tab "Personas".
Here you can create one or more persona groups, and within each group, you can create one or more personas.
Personas are an important concept for implicit personalization in Umbraco Engage. A persona is an archetypical user whose goals, needs, and characteristics represent a group of visitors to your website. By creating personas you can define behavior on your website and personalize the website experience depending on the persona's needs.
Creating personas is something that you should do for your website. If it's your first time coming up with personas we always advise creating a maximum of 3 personas.
If you want to add many more personas, be aware that each added persona will increase the complexity of finding good personalization strategies. And every extra persona requires extra content.
As an example we have three different personas:
The data & privacy officer. This type of visitor is mainly interested in how Umbraco Engage is safeguarding data storage and GDPR ruling.
The developer. This persona is interested in how to set up Umbraco Engage.
The marketer. This persona is looking for inspiration and functionalities; what has Umbraco Engage to offer.
To learn how you can set up Personas in Umbraco Engage read the How to create a Persona guide.
In Umbraco Engage you can personalize the website experience of any visitor based on implicit scoring.
Ensure that you have set up at least one persona or customer journey step.
Implicit personalization is based on gaining confidence that a visitor shows behavior that can be mapped to a persona or a customer journey step. To gain this confidence it is possible to assign points to specific actions within your website. If a certain threshold of points is reached Umbraco Engage assumes the visitor is this persona or in a specific customer journey step. As soon as that point is reached, you can use that information to personalize the website experience of your visitor.
There are four ways to score the behavior of your visitors:
Score the content that a visitor is viewing. This can be done per node.
Score the campaigns that a visitor is part of.
Implement your own scoring. In this way, the sky is the limit, because you can hook into any external data source you have or behavior that you want to score.
The points of all these different sources are added and this reaches a certain amount of points per persona. As soon as one of the personas or customer journey steps reaches the threshold that is set up, the algorithm assumes that you are this persona or in that specific journey step.
In the example, the visitor collected 40 points for the "Data & Privacy officer", 30 points for the "Marketer", and 0 points for the developer persona:
The threshold in this specific case was set to 25 points. As soon as the "Data & Privacy officer" reached 25 points Umbraco Engage assumed that this visitor was a "Data & Privacy officer".
In this example the "Think" customer journey step is assumed based on the collected amount of points:
The threshold value and the expected difference between two personas or journey steps can be set in the customer journey group and persona group.
Setting up a deviation of at least 35 points between two personas the cockpit will show a different visualization in the previous example:
You can see that the "Data and privacy officer" still has 40 points and the marketer 30 points. Both have also reached the threshold of 25 points, but there is not a minimal deviation of 35 points. Umbraco Engage algorithm now does not assume a persona yet, but will wait until the deviation is big enough (according to the settings) and the "Data & privacy officer" reaches 65 points (30 points of the marketer + a minimal deviation of 35 points).
Explore how the Profiles section helps track visitor sessions, manage profiles, and differentiate between identified and anonymous visitors.
The Profiles section offers an overview of all the visitors that visited your website. Access the profiles section by navigating to the Engage section and then to the Profiles subsection in the topmenu.
This section provides an overview of all visitors:
At the top, the total number of visitors that visited your website (in this case in total 25.521 profiles) is displayed. You can also see how many visitors are identified versus unknown.
The graph in the middle shows the number of new identified visitors over the last 30 days.
Below that there is an overview of the profiles per month.
As long as we have no data of a visitor we will call this profile "Anonymous". If a visitor does not give consent to be identified, they remain "Anonymous".
However, once a visitor logs in (via Umbraco's Members section) or submits an Umbraco form, they become an "Identified Profile." For example: In the above screenshot you see "Jeffrey Schoemaker". We see this name because this visitor has logged in as the member "Jeffrey Schoemaker" at a moment in time.
The overview table displays all visitors to the website, showing:
Whether the visitor was anonymous or identified
The number of sessions the visitor had
The number of pageviews within those session
The first session that the visitor had on the website
The last session that the visitor had
The number of goals triggered by the visitor
The total value the goals had
Finally, you can see a blue or a grey icon at the beginning of the row. A grey icon indicates that Umbraco Engage did not enrich the visitor's experience. A blue icon indicates that Umbraco Engage enriched the visitor's experience by showing an A/B test variant or a personalized version.
It is possible to filter the overview of profiles by clicking the filter button at the top of the profiles overview.
You can filter by:
Anonymous or Identified profiles.
Profiles with a "High potential"
Profiles with more than X conversions
Profiles with more than X total value achieved by triggered goals
Specific date ranges
For more details, click Show profile in a specific profile's row. For more information, see the Profile Detail article.
In this section we explain how you can create Referral groups and score referrers in these groups.
Create a Referral group:
Assign a score to your Personas and/or Journey.
Save your Referral Group
Go to the Unscored referral tab
Assign a referrer to your newly created group.
By default, the score will be assigned when the referrer matches the whole URL (in this case facebook.com/mycompany/products). It is also possible to assign the score on the entire domain (That is facebook.com).
Tick the 'Score on domain only' checkbox.
You have now created Referral groups and score referrers in your groups.
As soon as you have set up a persona and a customer journey step in Umbraco Engage you can start scoring the content of your website.
Each Umbraco node can be scored against personas and the customer journey.
To do this navigate to a node in Umbraco and open the content app "Personalization" on that node:
You can navigate to the tab "Content scoring" to score this Umbraco page. Writting your content for a specific set of personas you can assign a score that will be added to this persona or customer journey step.
Set up the score and save the scoring.
In the example the persona "Data & Privacy officer" will get 10 points and the "Marketer" will get 5 points when they read this Umbraco node.
In this article we are going to set up some personalization for our segments.
Please make sure you have set up. A segment is a group of visitors for which you want to personalize the website experience.
Once that is done we can go to the next step and personalize the experience.
You can apply personalization in two ways:
On a specific page
Via the personalization section
To personalize a specific page you can go the any node within Umbraco. When you open the node you'll find all Umbraco Engage content apps on that specific node. To personalize the page you can go to the "Personalization" content app:
By clicking on the content app you go to an overview of all applied personalizations for this specific page. You can create your first personalization by clicking "Add personalized variant":
In the popup you can specify the segment for which you want to personalize the experience. It also advised to create a descriptive name for the personalization and a short description:
When you've selected the correct segment you can click on "Add variant". This opens up the split-view editor on the left side of the original page. On the right side, there is the option to create a personalized variant.
You can for example specify a different title for this variant:
You can save and preview your applied personalization by clicking "Save & Preview".
You will see an extra querystring parameter in the URL when previewing the personalization:
https://<your url>/?engagePreviewAppliedPersonalization=<id>
This is only the case when previewing your personalization. As soon as you publish the page regular visitors will only see one URL an depending on the segment they will see different content.
If we now publish the website and go to the URL we will see different pages. The visitors who are part of the segment will see the personalized variant. All other visitors will see the default content.
we have now set up our first personalization.
You can also apply personalization to multiple pages at once. This can only be setup via the Marketing section in Umbraco. Within that section you can go to the subsection "Personalization" and click on "Apply new personalization":
Here you can specify to which pages or document types you want to apply the personalization. Also you need to specify for which segment this is triggered.
With multiple pages and Document Types you can either add in some additional CSS
or JavaScript
code or personalize the experience via code. You can add CSS JavaScript
via the button "Include CSS/JavaScript". The CSS
and JavaScript
will automatically be added to the pages where the segment applies.
You might want to exclude the traffic from specific IP addresses.
A good example is that you normally exclude your IP address, so it doesn't impact the digital Analytics reporting. Here you can specify a specific IP address, a list of IP addresses, or a regular expression.
Learn how to set up and implement goals to effectively measure the success of your optimization strategies.
Goals are important in Umbraco Engage. Without goals you cannot determine whether your optimization strategy through or really works.
A/B Testing and/or Personalization is never the goal; the goal is to increase your goals which can be achieved by personalization or A/B testing.
In the Goals menu, you can set up goals and specify their value.
You have a complete overview of all of the goals that are currently set:
From this page, you can edit existing goals or set up new goals.
When you click on Create new goal you can set up a new goal. You have to give it a name and an optional goal value.
You can specify whether it is a micro or macro goal.
A macro goal should be used for the "bigger things" in your website like a purchase or filling in a contact form.
Micro goals are smaller / less important things like "Reaching the contact page" or "Clicking open a FAQ". These micro goals should eventually contribute to macro goals.
In Umbraco Engage, we always keep track of the macro goals, for example during A/B tests. Perhaps your micro goal is increased, but it hurts your macro goal. In that case, Umbraco Engage will give you a warning.
You can specify whether you want to increase or decrease the goal. Most of the time you want to increase your goal. Other times you might want to lower the goal. An example of this could be a goal of "Unsubscribing from a newsletter"
You can specify how the goal will be triggered:
Via a pageview/set of pages that are visited
Via a page event that can be triggered
Via an Umbraco Forms submission
Via some custom code
Discover how to analyze visitor profiles, including insights on engagement metrics, potential, personas, and detailed activity tracking.
In the Profiles section, you can access specific visitor profiles, which contain two sections: Insights and Activity.
The insights section provides an overview of the visitor.
Here, you can see:
The date of the visitor's first session on the website,
The date of the visitor's last activity,
The number of sessions,
The number of page views,
The time spent on the website, and
The total engaged time.
You can also view any goals triggered by this visitor.
Umbraco Engage will also show the potential of the profile based on the engagement time and when the profile was last active.
By default, a profile is considered active if the profile has visited the website in the last 30 days.
By default, a profile is considered engaged when the engagement time of the visitor was higher than 300 seconds in the last 3 sessions.
In the Activity tab, you can view all the activity of this visitor.
For each session, you can see:
An icon indicating whether Umbraco Engage enriched the visitor's experience (blue icon for A/B Test variant or personalized variant; grey icon if not).
The timestamp when the session was recorded.
Which device type was used.
The number of pages that were visited in this session.
The duration of the session.
How long the person was engaged.
The number of goals that were triggered.
The events that were triggered.
On which page the session started.
From which website the visitor came into your website.
By clicking on a row, you can access more detailed information about that session.
You will see:
The visited page.
The time of visit.
The time on page.
The engaged time on page.
The scroll depth on that page.
The number of goals that were triggered.
The number of recorded events.
The variant of the page is displayed to the visitor.
The operating system, browser, and (anonymized) IP address are used.
An icon indicating whether the visitor saw a personalized or A/B tested variant of the page.
Finally, you can drill down into the activity on a specific page:
Here, you can see:
When the visitor started their visit on the page.
When the maximum scroll depth was reached.
When the visit ended.
When goals were triggered.
Explore how to configure and manage various aspects of Umbraco Engage to tailor the platform for marketers and editors.
The Settings section is designed to help you customize your Umbraco Engage environment to achieve optimal performance and security.
Learn how to set up goals to track key performance indicators, ensuring you can measure success effectively.
Learn about IP Filtering to manage traffic and protect your analytics data.
Get an overview of all configured settings of Umbraco Engage.
Explore how to control which Umbraco user groups have access to the Marketing section settings and manage where content apps are displayed.
Umbraco Engage does not provide a built-in way to add additional data to a profile. You can store the data in any format and in any way.
Your system may associate an Umbraco Engage visitor with other data coming from an external system such as a Customer Relation Management (CRM) system.
If you want to use external data in a custom segment you have to write the data access yourself in the custom segment code. Learn more about this in the .
Depending on your segmentation setup of the document types you can edit the specific properties of your Document Type. Please read the section "" to set this up correctly.
Within the profile, you can see all and that you have set up within Umbraco Engage. Each persona and customer journey phase displays a score. You can see if Umbraco Engage has assigned a persona or journey phase to this visitor. In the below example, you see that the Umbraco Engage has assigned the persona "Data & Privacy officer" to this visitor.
The Umbraco Engage package is all about data, data, and more data. To make the most out of this data and do it the most efficient way we have four different stages where the data goes to.
Data collection: This is where the visitor data is collected and stored for a moment in the memory of the server.
Data storage: This is where the data from memory goes to the database.
Data processing: The data is processed at a later moment to make it more efficient and normalized
Data reporting: Finally the data is reported within Umbraco Engage
The concept of this dataflow is the most important concept to grasp when using Umbraco Engage.
The Developer section contains all information you need as a developer to get started with, configure, and use the features in Umbraco Engage.
While many features and functionalities are enabled by default, some things are to be configured before they are ready to use.
As a developer, it is up to you, to know where to configure which features and which settings to set to change certain functionalities.
In the Developer section, you can find all the resources you need to configure Umbraco Engage for your company's requirements.
Learn more about how data is collected, stored, and parsed.
Umbraco Engage uses a cookie to collect visitor data on your Umbraco website. Learn more about how it works in this section.
Performance is an important metric to consider when working with website development. In this article, you can learn more about the performance considerations taken in Umbraco Engage.
Manage content apps and access on Document Types.
You can manage which document types the content apps are shown, and which Umbraco user groups have access to in the Marketing section settings. They can be managed per Document Type and user group
It is possible to disable the individual modules of Umbraco Engage (Analytics, A/B testing, Personalization) through code based on any criteria you want.
You could choose to give visitors control over these settings through a cookie bar on your site.
To do this you have to create an implementation of the Umbraco.Engage.Business.Permissions.ModulePermissions.IModulePermissions
interface and override our default implementation.
This interface defines 3 methods that you will have to implement:
Using these methods you can control per visitor whether or not the modules are active. Your implementation will need to be registered with Umbraco using the RegisterUnique()
method, overriding the default implementation which enables all modules all the time. Make sure your composer runs after the Umbraco Engage composer by using the [ComposeAfter]
attribute.
It could look something like this:
By changing the default module permissions to false a visitor is be tracked until they give their consent to the Analytics module. In that case, the module permission AnalyticsIsAllowed
will be set to true
.
Is the module permission set to true it is required to reload the current page as soon as the visitor has given consent. This needs to happen to track the current page visit the visitor has given consent on.
If no reload is performed the visitor's referrer and/or campaign information will not be tracked.
Calling the window.location.reload();
method is the preferred option, as this will preserve any referrers & query strings supplied in the current request.
This results in Umbraco Engage processing the current page visit & visitor correctly.
An example implementation using Cookiebot can be found in the security and privacy section.
Learn what Umbraco Engage tracks before any additional configuration is added.
If you install Umbraco Engage we will automatically collect a lot of data for you.
Serverside the following data is tracked:
The URL of the visited page (/foobar/
)
The query string of the visited page (?filtering=on¶meter1=2
)
The variant of the page that we serve. This could be a personalized version of the page or one of the A/B-test variants.
The time that the page was visited (31 august 2021, 16:04:22
)
Where the visitor came from before this visit (the so-called referrer). This could be an internal webpage (/my-contentpage/
) or an external URL (www.umbraco.com/the-umbraco-engage-rocks/
)
The browser being used (Firefox), the Operating System used (Windows), and the type of device being used (Desktop). These data points are based on the user-agent string that any browser is sending.
The IP address (213.62.44.123
) or anonymized IP address (213.62.44.0
), depending on your configuration.
Only GET requests which return a 2XX HTTP OK will be tracked in Umbraco Engage.
With the data collected, the Analytics reports in Umbraco Engage can be visualized. It also allows us to calculate other metrics, such as conversion rates, bounce rates, and landing & exit pages.
If you include the clientside collection script as well, you can also capture behavioural data of your visitors.
Information about Data Storage and how to work with and troubleshoot it in Umbraco Engage.
When the data is collected it is temporarily stored in memory. At some point, a threshold is reached and all data is stored in the database.
Two thresholds can be set and reached which will trigger the storage of data. If one of these two is reached the data will be stored in the database.
The first threshold is the 'FlushRateInRecords'.
When this number of records is in memory the data will be stored in the database. An example could be if you set it to 100, the data will be permanently stored after 100 page visits.
The second threshold is the FlushIntervalInSeconds.
After this number of seconds, the data will be sent to the database. If you set it to 30 seconds, for example, every 30 seconds the data will be sent to the database. No matter how many records there are in memory.
Both settings can be set in the configuration file of Umbraco Engage.
The higher the value set for these thresholds, the more memory Umbraco Engage uses on your web server(s) and less of your database connection. Please be aware the memory impact is low because there is not a lot of complex data stored.
The lower the value you set, the less memory Umbraco Engage uses on your web server(s), and the more database calls are made.
The data will be stored as quickly as possible to minimize the needed resources. For this reason, the the data collected from client-side events will be stored in so-called raw tables in a non-normalized. This data will be processed in the next step of the data flow.
The data collected from clientside events is stored in the table umbracoEngageAnalyticsRawClientSideData
.
When the data is stored in these tables the columns processingStarted
, processingFinished
, processingMachine
, and processingFailed
are empty. They will be filled in the parsing step.
Learn how the Umbraco Engage cookie works and how the functionality can be tested.
When visiting a website with Umbraco Engage installed you will get a unique cookie. This cookie allows for relating different page visits or sessions to the same visitor. It will also continuously serve the same variant of an A/B test.
By default the Umbraco Engage cookie has the name umbracoEngageAnalyticsVisitorId
. You can change the name in the configuration file.
The Umbraco Engage cookie:
Is a first-party cookie. This means it is set by the website itself and can only be used by the website itself. The cookie will not track you across the whole internet on all kinds of websites (like Facebook and LinkedIn).
Sets the HttpOnly
flag.
Sets the Secure
flag.
Is initialized with an expiry date of 365 days (depending on the settings in the configuration file) and has a sliding expiration. That means that if you revisit the website after 30 days, the cookie will reset and expire 365 days after that visit.
By default, all modules are initiated at the first page request. If you want to override this behavior, read the documentation about the different module permissions.
On this page you can find information about Data parsing and how to store the data in a normalized and efficiant way.
Now that the data is persisted in the database it is time for the next step.
There is a background process constantly running on the webserver to check whether there are unprocessed pageviews in memory or records in the table umbracoEngageAnalyticsRawClientSideData.
The records in the table umbracoEngageAnalyticsRawClientSideData can be identified because the column processingStarted is NULL
.
If the background process finds unprocessed pageviews in memory or one of these unprocessed records it fetches the rows of data and starts processing it. Once it has finished processing it updates the record in the table by setting values in the columns 'processingFinished' and 'processingMachine'.
When the data is fetched Umbraco Engage will perform some different actions:
All data is stored in a normalized way in the tables with the prefix: umbracoEngageAnalytics.
For example; each browser is only stored once in the table umbracoEngageAnalyticsBrowser and each browser version is stored once in the table umbracoEngageAnalyticsBrowserVersion.
The session is now related to the primary key ID of the browser version instead of storing the full-text string. This way, data can be queried effortlessly and is stored more efficiently (only an integer per browser instead of a text string).
This happens for all data:
Browser and browser version
Operating system
Visitor type
When the data was stored in the raw database tables only the URL was stored. In the parsing step, we try to identify which Umbraco node and which culture is served on this URL. This is an important step to report at a later point what happened on which page within the Umbraco backoffice.
Within Umbraco Engage you can set up goals via a specific page that is reached or an event that has been triggered. When parsing data Umbraco Engage checks whether one of the goals is reached with this record.
How frequently the data is processed can be set in the configuration file. Two parameters can be set:
The IntervalInRecords setting specifies how many unprocessed records should be fetched per parsing process.
The IntervalInSeconds setting specifies how often the background process is triggered and how often the parsing happens.
The higher you set these amounts the less frequent the parsing takes place.
It is possible to specify which web server should execute the processing step. The processing step is the heaviest in the data flow process. Most likely it will not have any impact, but for optimization reasons, you can specify which server is responsible for processing the raw data. This can be one web server, multiple web servers, or even a dedicated web server that does not serve the website itself. This can be set with the setting IsProcessingServer.
If using Umbraco in a load-balanced configuration ensure the front-end servers have the configuration setting for IsProcessingServer set to false. Also, make sure that the backend (Umbraco backoffice) server should only have this setting enabled.
There is probably no or little reason to store this data forever. That is why we have two settings to clean up this data.
The first setting is 'AnonymizeDataAfterDays'. After the set number of days, the data will be anonymized. This means the data will still be shown in aggregate reports like pageviews, used browsers, number of visitors, etcetera, but it can not be related to an individual visitor anymore.
The second setting is 'DeleteDataAfterDays'. With this setting the data will be deleted after a set number of days. The reason is that it does not make sense to store your data for all eternity.
We take performance seriously and performance is always on top of mind when adding new features to Umbraco Engage.
Umbraco Engage is optimized for performance and you configure it to optimize the performance further.
As documented in the dataflow process there are different steps for collecting, storing, parsing, and reporting the data. This is primarily done for performance reasons.
The collection is done in memory of the web server (or webservers if you have multiple web servers in a load-balanced
Storing causes the data to flow from the memory to the database. The memory is free again and can be used for other data. The data is stored in the raw data tables at that moment.
You can also optimize your server infrastructure to tweak the performance. There are a few options that you could apply:
You could set up more web servers in a load-balanced setup. Each web server will collect data from the visitor, but you can specify which web server is responsible for parsing the data in the configuration.
You can also set up one specific server only to parse the data. In that case, the other web servers will have almost no impact on their performance. To set this up you need to set the parameter 'IsProcessingServer
' to 'false
' in your configuration file for all servers that do not need to process the data and set it to 'true
' on the server(s) that is responsible for parsing. If there is no server with this setting set to 'true
' the raw data of Umbraco Engage will take place, but the data will never be processed.
By default, the Umbraco Engage stores its data in the same database as Umbraco. It uses the default connection string of Umbraco (named 'umbracoDbDSN
'). It is possible to specify a separate database for all Umbraco Engage data. This could be another database on the same server or also another database server. To do this you need to specify a new connection string in your application and give that connection string a name. In the configuration file, you can now specify this name in the field 'DatabaseConnectionStringName
'.
Learn more about how Umbraco Engage distinguishes between bots and real visitors.
Engage only tracks 'real' visitors and discard any visit we determine to be from a bot. The data for bots is not stored in Umbraco Engage and cannot be viewed in the Analytics section.
From an Search Engine Optimization (SEO) perspective, bots, search engine crawlers, spiders, and the like, will always see the default content. This means that they will not participate in personalization or A/B tests.
The tracking of a visitor is done via the following steps:
DeviceDetector.NET will assess if the visitor is a bot or a 'real' visitor` using the device ID of the browser.
If it is a 'real' visitor the page will send a POST request to umbraco/engage/pagedata/ping
record a visit.
The page will not add a POST request if the visitor is deemed a bot.
Now that the data is collected, stored, and parsed it's finally time to browse through the reports in the Umbraco backoffice.
The data is visualized in two parts in Umbraco:
The Umbraco Engage section gives an overview of all data that is recorded. The data is visualized for the entire installation and all pages and visitors. These reports give a perfect overview on a top level.
For more detailed reports on an individual page (Umbraco node), you can go to the Analytics Content app.
All the data for the reports are generated nightly at 4:00 AM (configurable). During this process all the relational data is turned into a star scheme for quick reporting in the different Umbraco Engage sections.
Here you have an overview of all configured settings of Umbraco Engage.
It's not possible to change the configuration options directly. This is done in the configuration file on disk. To see how you can configure Umbraco Engage read the Configuration Options article.
Analyzing the data Umbraco Engage collects from your website is a part of learning about your website visitors and improving your content.
The Analytics feature in Umbraco Engage provides an overview of all data collected from your Umbraco website. Depending on your configuration, you can view analytics data for who visits your website, how well your videos and forms are doing, and much more.
In this section, you can learn more about the different aspects of the Analytics feature and how to extend it.
Umbraco Engage tracks different kinds of data by default. Additionally, it can be configured to track even more to help you know where to improve your content.
Umbraco Engage provides a set of scripts to bridge data collected from other analytics tools.
Umbraco Engage is built on Umbraco CMS giving you many options for extending different parts of the product.
Learn how data from Umbraco Forms is tracked with Umbraco Engage.
To track Umbraco Forms submissions, you need to install with a valid license from Umbraco HQ. You also need to install the Umbraco Engage.
Umbraco Engage measures interactions with Umbraco Forms on your website automatically if you include the Umbraco Engage . No additional configuration is needed. The data is visualized in the backoffice in Engage > Analytics > Forms.
The following is measured:
The time a visitor started filling in the form.
The time a visitor finished filling in the form (like when it was submitted).
If the visitor has seen the form, and whether it was in their viewport.
If the form was submitted successfully.
This is based on client-side validation only. If client-side validation passes it is seen as a successful submit.
If the form raised any client-side errors, and how many was raised.
Focus/unfocus events of each field and whether the field was empty or contained data at that time.
It is possible to track a specific visitor to your website and see if they have made any form submissions. To do so, follow these steps:
Edit the Umbraco Form you wish to track visitors for and go to the Design view.
Add a new field to your form called 'Analytics - VisitorId`.
Give the new form field a name such as Visitor ID.
Specify a URL in the settings of the field type called Template:
The URL above is a link to your website, including a visitor ID. By using a URL like this you can click directly through to view the visitor profile from Forms workflows. This includes emails, Slack messages as well as exported Excel data.
By adding the engage-no-tracking
attribute you can disable Umbraco Forms tracking on the form or field level. The attribute needs to be added to either the form tag or to a field tag (like input, select, or textarea).
Bot detection
Capture Location Data
Extending Forms
Video Tracking
Scroll Heatmap
This is the first phase of the data flow. In this stage, the data is collected from the user and stored temporarily in memory.
Umbraco Engage works via serverside collecting meaning that all initial visitor data is collected on the server and not sent via JavaScript for example. When a visitor visits your website Umbraco Engage code checks whether you already have an Umbraco Engage cookie. If not, it creates one and sends it back to you.
At the same time the visitor is making a request the visitor sends all kinds of data to the server:
Which browser the visitors are using
Which URL is requested
If there was any referring page (where did the visitor come from)
At what time the page is requested
Which IP Address is used
Which operation system is used
Which type of device is used
Which cookies are sent
This data is all collected and, because of the efficiency stored for a while in the web server memory. The idea is that storing this data in memory is faster than directly writing it to the database. It is more efficient to store multiple database records at once than to store the database records one at a time.
In the next phase, the data in memory will be stored in the database.
The beauty of server-side collection is that it always works and you're not relying on JavaScript for example. Also, there is no way for clients to block this behavior because this is "how the internet works".
Only page requests are collected in Umbraco Engage. The request needs to be a GET request returning a 200 OK. Requests to images (.png, .jpg ), .css
and .js
files are not tracked. All requests to the /Umbraco/-folder are also ignored by default.
There are different configuration options to adjust the collecting process.
You can limit the amount of data records stored in memory. If you are limited in memory you can adjust these settings to fit your needs.
The IP Address is anonymized by default. There is an option to change this
You can turn off server-side tracking. This can be useful if not every page request reaches your website. This could be the case if you're using CloudFlare for example.
The amount of data that you can collect on the server is limited. Visitors have all kinds of interactions when your website loads. They can scroll, click on the website, watch videos, and click on other pages (inside and outside of your website).
These kinds of requests need to be collected via the client side. To support this we have created a JavaScript that collects a lot of data, and extending this with your own events is possible.
If you install the package you will find this JavaScript file in the folder /Assets/Umbraco.Engage/scripts/.
This JavaScript collects the following data for you:
The maximum scroll depth as a percentage of the whole page and in absolute pixels.
The links you have clicked and at the moment you have clicked these.
The time you have been engaged on the page.
We track the time that you are actively using the page. We see whether you are scrolling, moving your cursor, or typing. As long as you are doing that we track the time.
As soon as you do not do anything of the above we stop the timer until you start doing something again.
Also if you have opened the page in a tab but you are using another website at the moment, that time will not count. We stop measuring time as soon as you have not done anything for 5 seconds.
You need to load the file at the end of your page to enable these events.
Client-side events are collected and sent to the server and stored in memory when visitors exit the page or close the tab/browser.
Looking at your website source code you will see a line of code automatically inserted by Umbraco Engage. It most likely looks like something like this:
This snippet of code ensures loading the umbracoEngage.analytics.js
file, the exact page visit will be automatically linked to the submitted client-side events.
It is also possible to push your own events to Umbraco Engage. It works 80% the same as Google Analytics Event Measurement. Read more about custom events in the Create your own events article.
There is a chance that you've already implemented all kinds of events via Google Analytics with their syntax:
ga('send','event',[eventCategory],[eventAction],[eventLabel],[eventValue],[fieldsObject]);
If that is the case you can include a bridging library we created. This bridging library ensures that all custom events sent to Google Analytics are also sent to Umbraco Engage. These events will now be sent to both systems.
The only thing you will need to do is include the script \Assets\umbracoEngage\Scripts\umbracoEngage.analytics.ga-bridge.js somewhere on your page:
Learn about what scripts can be used to connect with other data-gathering tools.
Umbraco Engage helps you with some additional scripts and views.
They are all stored in the /Assets/Umbraco.Engage/Scripts/
and the /Views/Partials/Umbraco.Engage/
folders.
Find more information about the scripts:
You can also learn how to create your custom events.
Learn how to enhance your website's analytics by adding the Umbraco Engage JavaScript file.
You can add the Umbraco Engage Analytics JavaScript file to your website by placing this code before the closing </body>
tag of your website.
When this file is included, Umbraco Engage sends the following data to the server before the visitor navigates to another page:
Scroll Depth: Tracks the maximum scroll depth in both pixels and percentage of the page. For example, a user might scroll to 93% of the page height, which could equal 967 pixels.
Total Time on Page: The total time on page is measured in milliseconds. It is defined as the time difference between the page load and the moment the user leaves the page.
Engaged Time on Page: This measures the time the user is active on the page and in our opinion is more accurate than the total time on page. This script measures only the time when you are scrolling or clicking on the page in the active tab. It excludes idle time, such as when you are getting coffee or working in another tab. A 5-second grace period is used to define engagement. For more information, see this blogpost.
Clicks Tracked: All clicks to the following URLs are measured:
External domains
.pdf, .doc, or .docx document
An internal onpage link which is defined by an anchor link (#intro)
mailto:
and tel:
links
If the filename remains unchanged, this file will be overwritten each time you update the Umbraco Engage to a newer version.
This article describes what data is tracked from videos on your website.
Umbraco Engage gathers video statistics for the following types of videos:
HTML5 videos (videos provided via the <video>
element)
Embedded YouTube videos
Make sure the embed URL contains ?enablejsapi=1
as part of the full URL to enable tracking. The src
property of the iframe should be something like: https://www.youtube.com/embed/<CODE>?enablejsapi=1
.
The https://www.youtube.com/iframe_api is loaded for this purpose.
Embedded Vimeo videos
The https://player.vimeo.com/api/player.js is loaded for this purpose.
Make sure you have installed the Umbraco Engage analytics JavaScript file.
Discover how to enhance the accuracy of your Umbraco Engage Analytics by replacing specific extractors to collect additional or more accurate data.
Data collection is essential to the Umbraco Engage Analytics feature. When a visitor requests a page on your website, the web request is analyzed for relevant information, which is then stored in the database.
However, there may be times when the data collected is not entirely accurate, or you might have additional data to complement the Umbraco Engage dataset. In the following articles, we will explain how to replace specific extractors that obtain particular pieces of information from a request.
Learn how to implement an IP to location provider.
The localization information is displayed under the Location tab in the Analytics section of Umbraco Engage dashboard.
Umbraco Engage Analytics natively supports storing and reporting localization information for incoming traffic. Localization refers to identifying the (physical) origin of an incoming request. Web requests from a visitor's browser do not contain location information, so you must provide an implementation for this.
Most localization services, such as Maxmind, use IP addresses to perform a (rough) lookup. The information is compiled into a database where lookups can be performed. However IP addresses do not contain any information regarding their (physical) origin, rather they only identify a device on the internet. Localization information for any given IP address is tracked manually and can change overtime. We recommend either using an external service or acquiring a copy of a GeoIP database for localization lookup purposes.
Once you have a service that can provide localization information, integrating it into Umbraco Engage is straightforward.
For this purpose, implement the interface Umbraco.Engage.Business.Analytics.Processing.Extractors.IRawPageviewLocationExtractor. This interface allows the localization information for a pageview, defined as a single visitor's visit to a specific point in time. The pageview contains the property IpAddress which can be used for Geo IP lookup.
First, define a class that implements ILocation, to hold the localization information that will be returned through the interface in our implementation:
Next, implement the location extractor to read and validate the incoming IP address and filter out local IP addresses with the native IsLoopback method. Then, call your Geo IP localization implementation:
Lastly, let the IoC container know to use your implementation for the IRawPageviewLocationExtractor. Umbraco Engage has a default implementation of this service, which only returns null. This default service is registered using Umbraco's RegisterUnique method. To override this service, call RegisterUnique after the Umbraco Engage dependencies have been initialized, which is after the UmbracoEngageApplicationComposer:
After implementing this, Umbraco Engage will begin collecting and displaying localization information for pageviews. This can be viewed in the Analytics section of the Umbraco Engage dashboard.
If the custom implementation returns null, ILocation will display as "Unknown".
The LocationExtractor only processes new pageviews and will not apply retroactively to historical data.
If the pageviews contain location information, the table with countries is displayed:
From the country, you can drill down to the city. This will then filter the displayed graph and table data to only display session and pageview information for the selected country. Even though Umbraco Engage does support the storage for county and province, the UI only supports displaying data by country and city.
Learn how you can use the Scroll Heatmap in Umbraco Engage to gather data on the behavior of your visitors.
The heatmap only collects data if the client-side script is installed on your website.
Learn how to bridge Google Analytics with the data in Umbraco Engage.
We have included a bridging JavaScript file to "catch" all Google Analytics event calls and send them to Umbraco Engage. If you have a website with Google Analytics events defined you do not have to change the code to send them to Umbraco Engage. The only thing you need to do is include our JavaScript bridge.
Add a reference to umbracoEngage.analytics.ga4-bridge.min.js
:
The following built-in GA4 events are excluded by the GA4 bridge:
click
file\download
form\start
form\submit
page\view
scroll
video\complete
video\progress
video\start
view\search\results
This means if any of your custom events use one of the above event names they will also be ignored.
If there are specific events you want to exclude from being sent to Umbraco Engage you can customize the behavior.
Say you want to exclude all events that have category "X" and action "Y". To do that, add the following JavaScript to your website. Make sure umbracoEngage.analytics.js
has been loaded when the code executes.
It is also possible to change the category/action/label/value properties of evt.fields
to modify the values we send to Umbraco Engage.
Learn how to create and add custom events to Umbraco Engage.
You can send custom client-side events to Umbraco Engage. An example could be if somebody pushes a button.
This is done by executing JavaScript using the following format:
The following example sends an event that tracks the category "Tracking", the action "Blocked" and the label "Google Analytics":
You can track all these events in the Events report of the Analytics section.
Learn how to bridge data between Google Tag Manager and Umbraco Engage.
When using Google Tag Manager you can collect all events in Umbraco Engage. This is set up in the same way as .
To include the file add the following code before the closing body
tag in your HTML:
Learn how Umbraco Engage handles visitors who use blocker detection.
When a visitor runs an Adblocker or cookieblocker the visitor is likely not tracked in Google Analytics. With Umbraco Engage you can still track this visitor.
This is made possible by a JavaScript file that you can include before the closing body
-tag in your HTML:
If you include the script one of the following events is sent:
If Google Analytics is blocked in the browser of the visitor: umbEngage("send", "event", "Tracking", "Blocked", "Google Analytics");
Otherwise, the following event is sent: umbEngage("send", "event", "Tracking", "Allowed", "Google Analytics");
To see the statistics of this event go to the Analytics section of Umbraco Engage and open the 'Events' report. Look for the category with the name 'Tracking'.
This is based on - all events tagged (web)
.
Discover how to push A/B testing and personalization variables from Umbraco Engage to the Google Tag Manager (GTM) data layer in Razor templates.
Umbraco Engage provides a partial view that pushes variables related to A/B testing and personalization to the Google Tag Manager (GTM) data layer.
The following variables are pushed:
inabtest: true
- if the visitor participates in an active A/B test on the page; otherwise false.
This will also be true if the visitor is assigned to the "A" variant which is the original page.
abtestname
- The name of the A/B test the visitor is participating in. If there is no active A/B test, the value will be null
abtestvariant
- The name of the A/B test variant assigned to the visitor. If there is no active A/B test, the value will be null
personalized: true
- If personalization is applied to the page for the visitor; otherwise false.
personalizationname
- The name of the active personalization. If there is no active personalization, the value will be null.
To render the partial view in your Razor template, use the following line:
This partial will render the following output:
Sometimes you need more fine-grained personalization for your website. For this purpose the Umbraco Engage exposes a service called the IAnalyticsStateProvider.
This service provides access to all analytics-related information for the current request, and the segment information. When you need to execute custom code specifically tied to the personalization, you can use this service.
To get started you need an instance of anIAnalyticsStateProvider
, which can be resolved through Dependency Injection. For example consider the following case, where we use route hijacking to execute custom code for our content type called "Home
":
Umbraco will automatically resolve the service, without having to write any code. We can now use the service in our request, by calling the .GetState()
method to get the current state for the current request. Which in turn exposes the PageView containing the concrete information we are looking for.
The PageView
lies at the heart of Umbraco Engage Analytics feature and exposes a lot of interesting information. For now, we will focus on reading all segments for the current pageview. Depending on your configuration, a visitor can fall into multiple segments, as we can see by enumerating overall PageViewSegments
.
Consider the following example (continued from above) where the content of content type "Home
" was requested. We will now tell Umbraco to execute this custom code whenever the template HomeTemplate
is requested:
We can for example check if the current visitor falls into a segment called "MySegment". Keep in mind that a visitor can fall into any number of segments (zero, one, or all). A segment alone don't anything and can be regarded as purely informational, or as a "Flag" or "Label".
The personalization used by the Umbraco Engage to modify the appearance of a page is called Applied Personalization.
A page request can have only one active Applied Personalization. Based on the current segments (and their sort order), Umbraco Engage picks the first applicable Applied Personalization. This could be a multi-doctype or multi-page personalization (Marketing section) or single-page personalization (content).
To inspect the resolved Applied Personalization, we can use the property AppliedPersonalization on the state's PageView:
Be aware that no personalization may have been resolved for the current request. Make sure to do a null check before reading the AppliedPersonalization
property. The property SegmentId
will tell you which active segment was responsible for triggering the Applied Personalization.
A Segment may be used by different Applied personalizations, but only one personalization will ever be resolved and displayed.
This implies some different important things:
The Applied Personalization can only trigger on currently active segments (as found on Pageview.PageviewSegments
)
Not having any active segments automatically means there will never be any Applied Personalizations active. So configuring correct segments is essential.
Having a maximum of one active Applied Personalization per request means that you might find an unexpected personalization was activated. Always make sure to check the segment sorting order.
When testing it is a good idea to inspect the Cockpit information in your front end requests so you can see which segments are active.
Explore how to retrieve active A/B test variants for visitors using the Umbraco Engage C# API.
You can retrieve the active A/B test variants for a visitor in different ways depending on your specific scenario:
IAbTestingService.GetCurrentVisitorActiveAbTestVariants()
Namespace: Umbraco.Engage.Web.AbTesting
Returns the active variants for the current visitor on the current page.
Can only be used with an active request context
IAbTestingVisitorService.GetVisitorAbTestVariants(visitorExternalId, pageId, culture, contentTypeId)
Namespace: Umbraco.Engage.Business.AbTesting
Retrieves active A/B test variants on a specific page, without requiring a request context.
The visitor external id can be retrieved using IAnalyticsVisitorExternalIdHandler.GetExternalId()
IAbTestVisitorToVariantManager.GetActiveVisitorVariants(visitorExternalId)
Namespace: Umbraco.Engage.Business.AbTesting
Retrieves all active A/B test variants for the given visitor throughout the website.
The visitor external id can be retrieved using IAnalyticsVisitorExternalIdHandler.GetExternalId()
To use these services, inject the specified service into your code. The example below uses IAbTestingService.GetCurrentVisitorActiveAbTestVariants() by injecting the service into a controller:
Umbraco Engage has different built-in segment parameters to build segments, such as "Customer Journey" and "Time of Day".
You may want to build segments with custom rules not part of the Umbraco Engage by default. You can add your custom segment parameters to Umbraco Engage.
In the following guide, we will show how this is done. There are 3 steps:
C# definition
AngularJS definition
(optional) Cockpit visualization
This guide will use code samples to add a "Day of week" segment parameter where you can select a single day of the week. If a pageview happens on that day the segment parameter will be satisfied.
You can download the following code to add this parameter directly to your solution.
Your custom segment parameter must be defined in C# for the Umbraco Engage to use it. In code, we refer to a segment parameter as a segment rule.
A segment rule is:
A unique rule identifier, e.g. "DayOfWeek".
A configuration object, e.g. "{ dayOfWeek: 3 }".
This is optional, but most rules will have some sort of configuration that the user can alter in the Segment Builder. In our example, the user can configure the specific day of the week.
A method that specifies whether the rule is satisfied by the current page view.
You will have to implement the following interfaces for a new custom parameter:
Umbraco.Engage.Business.Personalization.Segments.Rules.ISegmentRule
You can extend the existing BaseSegmentRule
to simplify the implementation.
It is important to implement the bool IsSatisfied(IPersonalizationProfile context)
method.
Umbraco.Engage.Business.Personalization.Segments.Rules.ISegmentRuleFactory
Register your implementation of the segment rule factory with Lifetime.Transient
in a composer.
For the "Day of week" example, the code looks like this:
And the factory which is used to create an instance of this rule:
We are using the class DayOfWeekSegmentRuleConfig as a representation of the configuration of the rule, which is not strictly necessary but makes it easier. The configuration is stored as a string in the database but in code, we like to have IntelliSense so we parse the stored configuration to this class:
The segment rule factory needs to be registered so Umbraco Engage can use it. The code below registers the factory in a new composer, you can use an existing composer for this if you like:
In the above example, we have shown how you can define custom segment parameters using C#. Next we look into enabling and configuring our segment in the Umbraco Engage segment builder.
We implemented the business logic for the segment parameter in the previous step, however, the parameter cannot be added to your backoffice segments yet. In this step, we will add some JavaScript and HTML to enable you to add and configure your segments in the Umbraco Engage segment builder.
This step will show concrete code samples that belong to our demo parameter "Day of week".
You need to create a folder in the App_Plugins folder of your project that will hold the new files.
For this example name it "day-of-week". The folder and content look like this:
App_Plugins\day-of-week
package.manifest
Instructs Umbraco to load your JavaScript files
segment-rule-day-of-week-display.html
View for displaying the configuration of your segment parameter
segment-rule-day-of-week-display.js
AngularJS component for displaying your segment parameter
segment-rule-day-of-week-editor.html
View for editing the configuration of your segment parameter
segment-rule-day-of-week-editor.js
AngularJS component for editing the configuration of your segment parameter
segment-rule-day-of-week.js
Define your segment parameter and register it in the segment rule repository of Umbraco Engage
You can name the files, however, make sure to reference the JS files in your package.manifest
properly.
The contents for each of the files are below:
segment-rule-day-of-week.js
In this file, you define the segment parameter and register it in the repository of Umbraco Engage.
segment-rule-day-of-week-editor.html
This file contains the view of your parameter editor. Our example editor is a <select> filled with the 7 days of the week.
We write the picked value to the "config.dayOfWeek" property of our rule. You can make the editor as complex as you want, use multiple fields, etc.
For more inspiration, you can look at the built-in rule editors of Umbraco Engage in App_Plugins\Umbraco.Engage\dashboard\segments\builder\rules.
We use the "data.days" property of our rule definition in the editor. The editor gets passed in the rule definition as well as a "config" object which we should update according to the user input.
segment-rule-day-of-week-editor.js
This registers the editor component in the Umbraco Engage module so we can use it.
It should not be necessary to update this file other than update the component name and templateUrl
.
segment-rule-day-of-week-display.html
This is the view file used for the visual representation of the segment parameter. We want to display the picked day to the user:
We store the chosen day of the week as an integer 0-6 ($ctrl.config.dayOfWeek) but in the display component, we want to show the actual day (e.g. "Monday"). Our rule definition defines the mapping in its "data.days" property so we convert it using that and display the name of the day.
segment-rule-day-of-week-display.js
In this file, we register the display component.
package.manifest
To make sure Umbraco loads your JS files we specify them here:
If all goes well you will see your custom parameter editor show up in the segment builder:
The new segment parameter will show up automatically in the Cockpit that is part of our package. The cockpit is a live view of Umbraco Engage data for the current visitor.
This includes active segments of the current visitor, and therefore your new segment parameter can also show up in the cockpit. By default, it will display the raw configuration of the parameter as stored in the database ("{ dayOfWeek: 3 }" in our example).
If you hover over it you will see the rule identifier "DayOfWeek" rather than a friendly name.
If you want to change this to be more readable you can implement the Umbraco.Engage.Web.Cockpit.Segments.ICockpitSegmentRuleFactory interface.
For the DayOfWeek
demo parameter, this is the implementation:
So we transform the JSON into a human-readable representation and we configure an icon to show up in the cockpit. Make sure to register this class in a composer (you can reuse the composer from the first step):
After it has been registered, Umbraco Engage will use the additional information to properly render your segment parameter in the cockpit as well.
The "DayOfWeek test" string is the name of the segment. This segment happens to have only 1 parameter which is the DayOfWeek parameter.
The personalization provided by Umbraco Umbraco Engage is built so users can personalize the content or layout of any page without programming skills from the UI.
One of the most common situations for implementing personalization is because you want to serve specific content to your users.
Groups of visitors are identified through segments, consisting of requirements to be met. This segment information is used to customize the user's experience through Applied Personalization.
The following articles cover common methods for implementing personalized content on your website.
Umbraco Engage offers multiple ways for performaing A/B tests on your website.
Learn more about each option and how to configure them in the Marketing and Editors A/B Testing section.
Profiling collects and analyzes behavior data to customize content. Umbraco Engage allows CRM integration to enhance visitor profiles without built-in methods.
Profiling is tracking and analyzing visitor behavior to build detailed visitor profiles.
This involves collecting data from website interactions to understand user preferences and customize content and marketing strategies accordingly. Profiles are dynamically updated as users interact with the site, allowing for more personalized and targeted marketing efforts over time.
In Umbraco Engage, you can integrate data from external systems with visitor profiles. Although Umbraco Engage does not provide built-in methods for adding this data, you can store it in any format.
The main two pillars of personalization that the Umbraco Engage offers are personas and customer journeys.
The impact of the content page on these can be managed on the Content Score tab in the Personalization app on the top right.
Sometimes you want more fine-grained control over when something does (or doesn't) score. For example, if a user places an order, the user has shifted from the customer journey step "think" to "do".
This might be difficult to accomplish through the Content Scoring UI in Umbraco, but can be done by code.
To manage scoring for personas, we need to get a reference to IPersonaService
. For the customer journey, we will need the ICustomerJourneyService
. Both services can be found under the namespace Umbraco.Engage.Infrastructure.Personalization.Services
.
To implement our example above, we will be using the ICustomerJourneyService
. To modify the customer journey step scoring, we need to know the ID of the step we are trying to score. For your implementation you could hardcode the IDs (since they are unlikely to change), we can also fetch them by name through the ICustomerJourneyGroupRepository
.
To resolve the required services, we will use Dependency Injection:
We will now request Umbraco Engage to provide the customer journey step "Do" from the group "Customer Journey".
This is the default name for the customer journey upon installation.
We can now inspect the step Do variable and find its ID
. To score the step, we provide the ID
and the score to the CustomerJourneyService
:
We have now added a score of 100 to the Customer Journey step "Do". It is also possible to add negative scores. In our example, we can decrease the scores for "See" and "Think".
Since the user is no longer (shifting away) from that step of the Customer Journey the implementation strategy is the same for personas.
Another, more advanced, example could be on how to reset the score of a persona for a given visitor. We can use the same approach as above to fetch the persona instead of the Customer Journey for the current visitor. We can get the visitor's current score based on the Persona ID, and subtract that exact score from said visitor.
Umbraco Engage does not provide a built-in way to add additional data to a profile. You can store the data in any format and in any way.
Your system may associate an Umbraco Engage visitor with other data coming from an external system such as a Customer Relation Management (CRM) system.
If you want to use external data in a custom segment you have to write the data access yourself in the custom segment code.
It is possible to visualize this external data alongside the Umbraco Engage profile in the backoffice by providing a custom AngularJS
component for this purpose.
When this component is registered a new tab will be rendered in the Profiles section when viewing profile details. This will render the custom component that was provided and get passed the Umbraco Engage visitor ID.
To render this External Profile Tab with a custom component, you have to create your component and register it with Umbraco Engage. The following code will show how to do both. Add the below code in a JavaScript file in the App_Plugins
folder and load it using a package.manifest
file. If you have your own custom module, you can use this:
This is all that is required to render your custom component.
Implement your own segment parameters
Retrieve segment information from code
Add custom scoring
Analytics
A/B Testing
Personalization
Settings
Ready to dive in? Check the installation guide to get started.
Get an overview and learn how to set up Umbraco Engage.
Find detailed step-by-step guides for personalization, analytics, A/B testing, and more.