Umbraco Engage has the following requirements:

• Umbraco version 13

• SQL Server 2014+, LocalDB, or Azure SQL.

  • SQL CE & SQLite are not supported.

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.

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.

How does it work?

Licenses are sold per backoffice domain. If you have alternative staging/QA environment domains or require one or more subdomains, additional domains can be added to the license on request.

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

What does a license cover?

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.

Configuring your license

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

Add additional domains

To add additional domains to your license, reach out to the sales team with your request and they will manage this process.

Installing your license

Once you have received your license code it needs to be installed on your site.

1. Open the root directory for your project files.

2. Locate and open the appSettings.json file.

3. Add your Umbraco Engage license key to Umbraco:Licenses:Umbraco.Engage:

"Umbraco": {
  "Licenses": {
    "Umbraco.Engage": "YOUR_LICENSE_KEY"
  }
}

"Umbraco_Engage": "YOUR_LICENSE_KEY"

Verify the license installation

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.

When and how to configure an 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:

{
    "Umbraco": {
        "CMS": {
            "WebRouting": {
                "UmbracoApplicationUrl": "https://admin.my-custom-domain.com/"
            }
        }
    }
}

See the Fixed Application URL documentation for more details about this setting.

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.

Looking for support?

Seeking support or guidance? Go to and look for the friendly speech bubble icon in the bottom right corner of your screen. Click on it, and you can open a new support request.

To be able to get all the information about your Umbraco support account, make sure you are logged in before creating a support request.

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 the .

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.

Non-cloud

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

Cloud environments

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.

Umbraco Cloud

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

Umbraco setup

Make sure your Umbraco is set up according to best practices. Please refer to the Umbraco documentation for more details.

Cockpit

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:

"AuthCookieDomain": ".domain.com",

To learn more, read the documentation about the SecuritySettings

Machine Key and Data Protection

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.

Bot detection (ping)

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.

Configuration

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.jsonfile.

Sticky sessions

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.

This article provides information and best practices on using Content Delivery Network (CDN) with Umbraco Engage.

Pages (HTML)

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.

Cache static files (CSS and JavaScript)

It is possible to cache static CSS and JavaScript files. Refer to the documentation of the CDN provider for the best-practice setup.

Media files (Umbraco /media folder, images, and PDFs)

It is possible to cache /media files. Refer to the documentation of the CDN provider for best-practice setup.

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.

Testing A/B variants

To test whether the A/B test is working and distributes the different variants you can use the A/B test preview functionality. 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.

Overriding the default behavior

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.

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&parameter1=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.

Umbraco Engage helps you with some additional scripts and views.

Find more information about the scripts in the Analytics section for Developers.

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.

This article covers two ways to install Umbraco Engage:

• Via NuGet, or

• Via a terminal.

Installation via NuGet

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.

1. Open the project in Visual Studio.

2. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution.

1. Navigate to the Browse tab.

2. Search for the Umbraco.Engage package.

3. Select the package.

4. Choose which project to install it into.

5. Install the package.

Installing using the terminal

You can install Umbraco Engage using a terminal, like the Package Manager Console in Visual Studio. The steps for doing so are outlined below.

1. Open the project in Visual Studio.

2. Find and open the Package Manager Console from the Tools menu.

3. Type the following into the terminal:

PM> install-package Umbraco.Engage

Alternatively, Umbraco Engage can be installed via the console on your operating machine.

1. Open a terminal window on your operating system.

2. Navigate to the folder containing your Umbraco website.

3. Install the Umbraco Engage Nuget package with the following command:

dotnet add package Umbraco.Engage

Next steps

When you have installed Umbraco Engage, build or restart your website, and the Engage 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.

Umbraco Forms

If you have installed Umbraco Forms as well and want to automatically track submissions of Umbraco Forms. Install the package Umbraco.Engage.Forms via NuGet or using your preferred approach as above.

PM> install package Umbraco.Engage.Forms

dotnet add package Umbraco.Engage.Forms

Clientside tracking

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.

<script src="/Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.js"></script>

Cockpit

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

@Html.Partial("Umbraco.Engage/Cockpit")</body>

Learn more what Cockpit is and how you can use it.

Optional Extras

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.

<script src="~/Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.ga4-bridge.min.js"></script>

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

<script src="/Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.blockerdetection.js"></script>

Cookie consent

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.\

Load balancing and CM / CD environments

Are you using a load-balanced setup or separate CM and CD environments? Please check our documentation about this topic.

The first run

When you visit your site locally for the first time, Umbraco Engage will begin tracking page views, visitors, etc. If you go to Engage -> Analytics, you won't see any data until the first reporting run. By default, reporting data will be generated at 04:00 AM automatically.

To generate reporting data manually on your local installation, go to Engage -> Configuration. Scroll down to Reporting section and click the red Regenerate button.

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.

Adding the Cockpit to Your Website

To add the cockpit to your website:

1. Render the HTML partial provided by Umbraco Engage.

2. The partial view is located at /Views/Partials/Umbraco.Engage/Cockpit.cshtml.

3. Insert the following code before the closing </body> tag:

   Copy

   @Html.Partial("Umbraco.Engage/Cockpit")

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:

If the Cockpit is missing and the Umbraco backoffice runs on a different domain, see the Load Balancing and CM/CD Environments article.

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

Access to 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 the Cockpit is missing while the Umbraco backoffice runs on a different domain, contact the technical team. You can also refer to the Load Balancing and CM/CD Environments article.

Data reporting client-side

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.

Data reporting server-side

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

Segments

In the segments section, you can see which segments are configured and which are applied to the current visitor.

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.

The Engage Section

In the Engage section, you will find subsections, each providing insights into a specific feature of Umbraco Engage.

Currently, the available sections are:

• Analytics: The most important feature of Umbraco Engage where all data is collected.

• A/B Testing: Set up new projects and start A/B testing directly.

• Personalization: Implement your marketing strategy and set up your personalizations.

• Profiling: See how visitors engage with your site.

• Reporting: See how your optimizations contribute to your goals.

• Settings: View and configure global settings used throughout Umbraco Engage.

The Dashboard

On the dashboard, you can view the current version of the Umbraco Engage installed and see how the license is configured.

This section covers topics such as an introduction to the platform, its components, personalization, reporting, and more.

The Umbraco Engage Section

Explore the Umbraco Engage section to access Analytics, A/B Testing, Personalization, Profiling, Reporting and global settings.

Content Apps

Discover how the Content Apps enhance each node with different features for improved content management.

The Umbraco Engage Cookie

Umbraco Engage uses a cookie to collect visitor data on your Umbraco website. Learn more about how it works in this section.

Profiling

The Profiling section helps track visitor sessions, manage profiles, and differentiate between identified and anonymous visitors.

Settings

The Settings section provides insights on excluding the traffic from specific IP addresses, setting up and implementing goals, and much more.

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

Campaign Report

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.

Boot failure after initial installation

Description

After installing Umbraco Engage and booting for the first time, an SQL exception might be thrown. This happens when Umbraco Engage fails to run the necessary migrations on startup, and the Umbraco Engage tables are not created.

The most common reasons for this are:

• Database connectivity issues.

• Incompatible SQL Server version.

• No COLUMNS STORE index support on Azure SQL lower than S3.

Exception

Steps to resolve

When having database connectivity issues

1. Remove the row with the Umbraco.Core.Upgrader.State+Umbraco.Engage key from the umbracoKeyValue table in the database if it exists.

2. Remove all existing umbracoEngage* tables from the database if they exist.

3. Restart the site.

When running on Azure SQL tier lower than S3

Azure SQL lower than S3 doesn't support creating COLUMN STORE indexes. To work around this follow these steps:

1. Scale your Azure SQL environment to S3.

2. Restart the site.

3. Scale back to your initial Azure SQL tier.

The COLUMN STORE indexes are created and can be used in a lower tier.

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.

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.

To track Umbraco Forms submissions, you need to install with a valid license. You also need to install the Umbraco Engage .

Summary

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 Report

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, drill down to a specific field to see which type of error was triggered, be it a validation error or a mandatory error.

Tracking a visitor Form submissions

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:

1. Edit the Umbraco Form you wish to track visitors for and go to the Design view.

2. Add a new field to your form called Analytics - VisitorId.

3. Give the new form field a name such as Visitor ID.

4. 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.

Disable Umbraco Forms tracking

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).

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.

Three different types of A/B tests are available:

• to test a specific page within Umbraco.

• A way to test at the same time.

• Test an entire and all of the pages using this type.

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

You can see a difference in statistics (Pageviews, Visitors, etc.) between Google Analytics and Umbraco Engage.

Umbraco Engage will collect pageviews unless Google Analytics (GA)/Google Tag Manager (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.

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 multiple versions of a webpage, content block, or website to different visitors, gathering data on which version performs better for a specific goal.

Why should you A/B test your website?

Your website is always underperforming its potential. Your website will never have a conversion rate of 100% and probably not even near that conversion rate. All visitors do exactly what you want them to do. 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.

A/B Testing in Umbraco

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 lack a key feature that Umbraco Engage offers: full integration 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 the same user-friendly way as Umbraco does, allowing you and your editors to start A/B testing.

• 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 there and you can start testing immediately. Also that means there is no content flickering like in many other tools.

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

Some great resources

Many books explain 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:

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

• Chris Goward. You should test that! Indianapolis, Indiana: John Wiley & Sons, Inc., 2013. Print

• Will Kurt. Bayesian statistics the fun way. San Fransisco, William Pollock, 2019. Print

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.

Umbraco Engage gathers video statistics for the following types of videos:

• HTML5 videos (videos provided via the <video> element)

• Embedded YouTube videos

• Embedded Vimeo videos

The Data

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:

The Report

By collecting this data, you can visualize different reports about the videos. You will find these reports in the Videos tab of the Analytics section.

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.

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.

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.

Split view editing

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.

Setting up the Document Type for split-view editing

Some properties are inactive (visually indicated because they are greyed out). Which properties you can edit is specified in the setup of the properties of your Document Type.

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:

Add CSS or JavaScript

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.

Finish the steps in the Settings up the A/B test article to verify and start your A/B Test.

Content rendering

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.

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 Engage section and in the Content App. 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.

After you have created all variants start your A/B testing as described in the Setting up the A/B test article.

Split URL testing in Umbraco Engage allows you to compare different versions of a page to see which one performs better.

To set up a Split URL test, you must create multiple versions of a page. Each version can have different designs, text, or buttons based on the options setup in Umbraco.

You can start a Split URL test from the Engage section or within the Content App. The type is selected in step 2 of the setup.

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.

Split URL tests are particularly useful for optimizing elements like checkout workflows, where small changes can impact conversions.

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 Engage section.

Set up the test

Open the Umbraco content tree and select the A/B tests Content App on the page.

Make sure that you have access to the Content App. These permissions can be specified per Document Types or User Groups.

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.

Configure the A/B 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.

Launching the A/B 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.

There are different ways to preview your A/B Test variants. In this article, we will discuss all options.

During the setup of your new A/B Test

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:

During a running test

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.

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 Engage 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.

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.

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 section and in the Content App. 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.

After creating all variants, start your A/B testing as written in the Setting up the A/B test article.

Applying personalization

You can apply personalization in two ways:

• On a specific page

• Via the personalization section

Personalizing a specific page

To personalize a specific page:

1. Go to any content node within Umbraco.

2. Open the node. You will find all Umbraco Engage content apps on that specific node.

3. Go to the "Personalization" content app:

1. Clicking the content app takes you to an overview of all applied personalizations for the page.

2. Click Add personalized variant:

1. Select the segment from the dropdown for which you want to personalize the experience in the popup.

2. Provide a descriptive name for the personalization and a short description:

1. Click Add variant.

2. A split-view editor opens up, where you can create a personalized variant on the right side of the original page.

For example, you can specify a different title for this variant:

1. Click Save & Preview to save and preview your applied personalization.

While previewing the personalization, you will see an extra querystring in the URL: https://<your url>/?engagePreviewAppliedPersonalization=<id>

This is only visiblee when previewing your personalization. Once published, visitors will see a single URL, and depending on their segment, they will view different content.

After publishing the website, visitors in the segment will see the personalized variant, while others will see the default content.

Congratulations, you've successfully set up your first personalization.

Applying personalization to multiple pages or per Document Type

You can also apply personalization to multiple pages at once. This can only be setup via the Engage 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.

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

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.

Creating a segment

The first thing you need to do is . A segment is a group of visitors within your website. When setting up a segment you can define which visitors are in a segment.

Personalizing the website for this segment

Once you've created a segment you can . This can be done on a specific page, on multiple pages, or per Document Type.

Explicit and implicit personalization

Umbraco Engage allows you to personalize your Umbraco website via . To grasp the way Umbraco Engage handles implicit personalization read the article. Another option is to see it in action in at the front end of your Umbraco website.

Extending personalization

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 .

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.

Segment Builder

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:

1. Navigate to the segment builder section.

2. Click Add new segment.

3. Give the new segment a Name and a short Description.

4. 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

Segment Parameters

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:

1. Create a new segment with the name My first segment.

2. 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.

1. Save the parameter and the segment will show the parameter that is part of this segment.

1. Add a parameter for Time of day to select all visitors after "15:00". Enter 15:00 in From and leave Until empty.

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

Editing and Deleting 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.

Ordering Segments

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.

The Settings section is designed to help you customize your Umbraco Engage environment to achieve optimal performance and security.

Setting Up Goals

Learn how to set up goals to track key performance indicators, ensuring you can measure success effectively.

IP Filtering

Learn about IP Filtering to manage traffic and protect your analytics data.

The Configuration File

Get an overview of all configured settings of Umbraco Engage.

Permissions

Explore how to control which Umbraco user groups have access to the Engage section settings and manage where content apps are displayed.

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 setting up personas.

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.

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.

Identified versus Anonymous Profiles

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.

Profiles Overview

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.

Filtering the Results

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.

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.

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 Profiling section for Developers.

On the Reporting dashboard in the Engage section, you can monitor the personalization set up on your website.

Segments

You can get an overview of how the segments you have configured for your website are doing.

When you select a segment, you will see an overview of the configuration. As you scroll down, you can monitor its performance.

Learn more about segments and how to set them up in the Personalization section.

Segment Potential

The segment potential depends on how many pageviews, sessions, and profiles are covered within the segment.

In the Reporting dashboard, you can see the coverage of these parameters. You can also see the number of sessions a new profile requires to activate the selected segment.

Segment Personalization

In many cases, it can be interesting to monitor how many of your website's sessions, page views, and profiles have been personalized.

In the Segment Personalization section, you can see how much of the incoming traffic on your website is personalized.

Goal Performance

You can also get an overview of how the goals you have configured are performing. The table in the Goal Performance section compares the goal performance between the control group and the personalized group.

In the Profiles section, you can access specific visitor profiles, which contain two sections: Insights and Activity.

Insights

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.

Profile Potential

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.

Calculated Persona & Customer Journey Phase

Within the profile, you can see all personas and customer journeys 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.

Activity Tab

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.

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:

1. . This can be done per node.

2. .

3. that a visitor is part of.

4. . 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.

Collecting Points

The points of all these different sources are added and this reaches a certain amount of points per persona. Once a persona or journey step reaches the set threshold, the algorithm assigns you to that persona or 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:

Tweaking the Scoring

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. The Umbraco Engage algorithm waits for the deviation to reach the set threshold before assuming a persona. For example: the Data & privacy officer reaches 65 points (30 points of the marketer + a minimal deviation of 35 points).

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.

Setting up a new goal

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

1. : This is where the visitor data is collected and stored for a moment in the memory of the server.

2. : This is where the data from memory goes to the database.

3. : The data is processed at a later moment to make it more efficient and normalized

4. : Finally the data is reported within Umbraco Engage

The concept of this dataflow is the most important concept to grasp when using 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 .

1. Create a Referral group:

1. Assign a score to your Personas and/or Journey.

1. Save your Referral Group

2. Go to the Unscored referral tab

3. 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).

1. Tick the 'Score on domain only' checkbox.

You have now created Referral groups and score referrers in your groups.

Now that the data is persisted in the database it is time for the next step.

Getting the data

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'.

Parsing

When the data is fetched Umbraco Engage will perform some different actions:

Normalize the data

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

Relate data to Umbraco nodes

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.

Goals

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.

Configuration options

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.

Cleaning up the data

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.

In the Engage -> Settings section, you can manage which Document Types the content apps are shown and which Umbraco user groups have access to them. This can be configured per Document Type and user group.

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.

Dataflow Pipeline

Learn more about how data is collected, stored, and parsed.

The Umbraco Engage Cookie

Umbraco Engage uses a cookie to collect visitor data on your Umbraco website. Learn more about how it works in this section.

Performance

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.

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.

Umbraco Engage is optimized for performance and you configure it to optimize the performance further.

Separate processes for storing, parsing, and reporting

As documented in the there are different steps for , , , and 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.

Optimized infrastructure

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 . 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 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 , you can now specify this name in the field 'DatabaseConnectionStringName'.

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.

Overriding the default behavior

By default, all modules are initiated at the first page request. If you want to override this behavior, read the documentation about the different .

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 .

Source of data

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.

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&parameter1=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 as well, you can also capture behavioural data of your 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:

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

Server side collection

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 .

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".

Collected requests

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.

Configuration options

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

Client-side collection

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.

umbracoEngage.analytics.js

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.

Automatic script

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.

Creating custom events

Google Analytics Bridging library

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:

Umbraco Engage gathers video statistics for the following types of videos:

• HTML5 videos (videos provided via the <video> element)

• Embedded YouTube videos

• Embedded Vimeo videos

Make sure you have installed the Umbraco Engage analytics JavaScript file.

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.

Flushing the memory

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.

Data storage

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.

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:

/// <summary>
/// Indicates if A/B testing is allowed for the given request context.
/// If false, the visitor will not be assigned to any A/B tests and will not
/// see any active A/B test content.
/// </summary>
/// <param name="context">Context of the request</param>
/// <returns>True if A/B testing is allowed, otherwise false.</returns>
bool AbTestingIsAllowed(HttpContextBase context);

/// <summary>
/// Indicates if Analytics is allowed for the given request context.
/// If false, the visitor will be treated as the built-in Anonymous visitor
/// and all their activity will be assigned to the Anonymous visitor rather than the specific visitor.
/// No A/B testing or Personalization will be allowed either if this is false regardless of their
/// respective IsAllowed() outcomes.
/// In addition, no cookie will be sent to the visitor when this is set to false.
/// </summary>
/// <param name="context">Context of the request</param>
/// <returns>True if Analytics is allowed, otherwise false.</returns>
bool AnalyticsIsAllowed(HttpContextBase context);

/// <summary>
/// Indicates if Personalization testing is allowed for the given request context.
/// If false, the visitor will not see any personalized content.
/// </summary>
/// <param name="context">Context of the request</param>
/// <returns>True if Personalization is allowed, otherwise false.</returns>
bool PersonalizationIsAllowed(HttpContextBase context);

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:

using Umbraco.Engage.Infrastructure.Permissions.ModulePermissions;
using Umbraco.Engage.Common.Composing;
using Umbraco.Core;
using Umbraco.Core.Composing;

namespace YourNamespace 
{
    [ComposeAfter(typeof(UmbracoEngageApplicationComposer))]
    public class YourComposer : IComposer
    {
        public void Compose(Composition composition)
        {
            composition.RegisterUnique<IModulePermissions, YourCustomModulePermissions>();
        }
    }
}

Tracking a visitor's Initial Pageview

To track Umbraco Forms submissions, you need to install Umbraco Forms with a valid license from Umbraco HQ. You also need to install the Umbraco Engage Forms Addon package from Nuget.

Summary

Umbraco Engage measures interactions with Umbraco Forms on your website automatically if you include the Umbraco Engage analytics JavaScript file. 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.

Tracking a visitor Form submissions

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:

1. Edit the Umbraco Form you wish to track visitors for and go to the Design view.

2. Add a new field to your form called 'Analytics - VisitorId`.

3. Give the new form field a name such as Visitor ID.

4. Specify a URL in the settings of the field type called Template:

https://**yoursite.com**/umbraco/#Engage/profiles/profiles/insights?id=**[[visitor.id]]**`

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.

Disable Umbraco Forms tracking

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).

The heatmap only collects data if the client-side script is installed on your website.

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.

Google Analytics 4 (GA4)

Add a reference to umbracoEngage.analytics.ga4-bridge.min.js:

Excluded events

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

Customize which events are sent

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.

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.

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'.

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 .

• 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

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.

Analytics topics

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.

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 .

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:

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 .

Quick Links

Tutorial Content

Step 1: Set up a local environment

The first step is to migrate from uMarketingSuite to Umbraco Engage in a local environment. This will be done using a copy of your production environment.

1. Backup your database from the production environment.

2. Restore the database locally.

Step 2: Prerequisites Check

In this step, you need to check the Database state to see if the existing data can be migrated to Umbraco Engage.

1. Execute the prerequisites check using the following query:

1. Verify that uMarketingSuite & uMarketingSuite addon version checks return the expected results.

2. Verify that the uMarketingSuite table integrity check returns the expected results.

The result should look like this:

If any of these checks return a failure, please resolve the issue before proceeding with the migration.

Step 3: Replace NuGet packages and dependencies

In this second step, you will replace all existing uMarketingSuite dependencies with Umbraco Engage dependencies.

1. Make a backup of any custom implementation of uMarketingSuite-specific files you want to reuse.

2. Remove the installed uMarketingSuite package from your project

1. Remove the other uMarketingSuite packages (if applicable) from your project:

1. Delete the App_Plugins\* folder for uMarketingSuite (and if applicable uMarketingSuite.UmbracoForms):

1. Delete the Assets\uMarketingSuite folder.

1. Delete the Partials\uMarketingSuite folder.

1. Delete the existing license file in the config\uMarketingSuite folder.

2. Delete the existing appsettings-schema.uMarketingSuite.json file from the root of the project (if exists).

3. Install Umbraco.Engage:

1. Install any Umbraco Engage add-on packages that were previously removed.

Step 4: Update analytics scripts, cockpit, and custom code

Please find below an overview of the changes to the default scripts in a uMarketingSuite installation:

• Rename scripts & Asset Paths containing the uMarketingSuite keyword to:

  • Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.js

  • Assets/Umbraco.Engage/Scripts/umbracoEngage.ga4-bridge.js

  • Assets/Umbraco.Engage/Scripts/umbracoEngage.blockerdetection.js

• The Cockpit partial view has been moved, and any references should be changed to:

  • Partials/Umbraco.Engage/Cockpit

• If you are tracking custom events please make sure to update the calls to the send event method:

  • ums("send", "event", "<Category name>", "<Action>", "<Label>")

    is now:

    umbEngage("send", "event", "<Category name>", "<Action>", "<Label>")

Custom code

Did you build custom segments, add custom goal triggering, change the module permissions (cookie consent), or something similar? Check which namespaces, classes, and entities have been changed in the Key Changes section below.

Key changes

Below you will find the key changes to be aware of.

Project, Package, and Namespace changes

Step 5: Update the database

In this step, you will update the database for Umbraco Engage.

1. Back up your database(s).

2. Rename the uMarketingSuite database tables, keys, constraints, and indexes using the following query:

1. Update the Umbraco database tables with the script below to rename the following uMarketingSuite properties:

   • The uMarketingSuite Media folder,

   • The uMarketingSuite Data Types & Data Type Folder,

   • The uMarketingSuite User Group Permissions,

   • The Migration State KeyValue State for uMarketingSuite, uMarketingSuite.UmbracoForms, and uMarketingSuite.UmbracoCommerce.

1. Validate that no errors occurred and all tables were updated successfully. No queries should return that 0 rows were updated.

Step 6: Finalize the migration

1. Delete any obj/bin folders in your projects to ensure a clean build.

2. Recompile all projects and ensure all dependencies are restored correctly.

3. Contact Umbraco Support for a license key.

   • Click it, and you can open a new support request.

1. Configure Umbraco Engage to use the legacy segment naming scheme:

1. [Optional] Set the Engage:Analytics:VisitorCookie:LegacyCookieName configuration if uMarketingSuite was using a different visitor cookie name setting than the default uMarketingSuiteAnalyticsVisitorId:

1. Run the project.

Step 7: Validate the migration

With the migration complete, there are a few more steps to ensure everything continues to work as expected.

1. Validate the new license:

   • Go to Settings -> Licenses in the backoffice and click Validate.

2. Generate the reporting data:

   • Go to Engage -> Settings -> Configuration in the backoffice and click the Regenerate button. Depending on the number of page views in the database this could take a while.

Step 8: Upgrade additional environments

You have now verified that everything works as expected in the local environment. It is time to upgrade the production environment and any additional environments.

Repeat the steps below for each environment that needs to be migrated.

1. Stop the site.

4. Create a backup of the website.

5. Deploy the updated code from the migrated local environment.

6. Start the site.

7. Validate the new license, if this has not happened already:

   • Go to Settings -> Licenses in the backoffice and click Validate.

8. Generate the reporting data

   • Go to Engage -> Settings -> Configuration in the backoffice and click the Regenerate button. Depending on the number of page views in the database this could take a while.

Custom firewall changes

If the /umbraco/umarketingsuite/ path was previously allowed, this needs to change to /umbraco/engage/.

Further Migrations

uMarketingSuite.UmbracoForms

If you are using the uMarketingSuite.UmbracoForms package, all the submissions linked to visitors have been migrated using the scripts in Step 4.

Existing Forms, including those that use the uMarketingSuite-provided VisitorId field, do not require additional action.

You can install the Umbraco Engage UmbracoForms add-on package using the following command:

uMarketingSuite.Headless

If you are using the uMarketingSuite.Headless package, applications that use the uMarketingSuite API will need to be updated. This needs to happen to be able to use the new Umbraco Engage API, accessible via the /umbraco/engage/api/ routes.

The v1 Engage APIs (v13.0.0 of Umbraco Engage) maintain the same functionality as the v1 uMarketingSuite APIs. For more details on the API, please refer to the Swagger documentation provided by Umbraco Engage.

You can install the Umbraco Engage Headless add-on package using the following command:

uMarketingSuite.Commerce

If you are using the uMarketingSuite.Commerce package, all the commerce data has been migrated to Umbraco Engage using the scripts in Step 4.

You can install the Umbraco Engage Commerce addon package using the following command:

uMarketingSuite.ContentBlocks

The uMarketingSuite.ContentBlocks add-on package has been deprecated since version 2.0.0 of uMarketingSuite and is unavailable for Umbraco Engage.

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:

using System.Web;
using Umbraco.Engage.Business.Analytics.Collection.Extractors;

public string ExtractIpAddress(HttpContextBase context)
{
    if (context?.Request?.ServerVariables["X-Forwarded-For"] is string ipAddresses)
    {
        var ipAddress = ipAddresses.Split(',')[0].Trim();
        if (System.Net.IPAddress.TryParse(ipAddress, out _)) return ipAddress;
    }
    return context?.Request?.UserHostAddress;
}

To override this behavior, implement your own IHttpContextIpAddressExtractor and instruct Umbraco to use your extractor instead of the default extractor:

using Umbraco.Engage.Business.Analytics.Collection.Extractors;
using Umbraco.Core.Composing;
using Umbraco.Core;

[ComposeAfter(typeof(Umbraco.Engage.Business.Analytics.Collection.Extractors.AnalyticsExtractorsComposer))]
public class CustomIpExtractorUserComposer : IUserComposer
{
    public void Compose(Composition composition)
    {
        composition.RegisterUnique<IHttpContextIpAddressExtractor, MyIpAddressExtractor>();
    }
}

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.

Retrieving Active A/B test variants

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()

Example

To use these services, inject the specified service into your code. The example below uses IAbTestingService.GetCurrentVisitorActiveAbTestVariants() by injecting the service into a controller:

using Umbraco.Engage.Business.AbTesting;
using Umbraco.Engage.Web.AbTesting;

public class YourController : SurfaceController
{
    public YourController(IAbTestingService abTestingService)
    {
        var activeVariantsCurrentVisitor = abTestingService.GetCurrentVisitorActiveAbTestVariants();
    }
}

Engage tracks only real visitors, filtering out bot traffic. The data for bots is not stored in Umbraco Engage and is excluded from the Analytics section.

From a Search Engine Optimization (SEO) perspective, bots and crawlers always see the default content, with no personalization or participation in 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 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.

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.

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

@Html.Partial("~/Views/Partials/Umbraco.Engage/GTMDataLayerPush.cshtml")

This partial will render the following output:

<script>
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
        inabtest: true,
        abtestname: "The name of the AB test",
        personalized: true,
        personalizationname: "The name of the personalized variant",
    });
</script>

Learn more about each option and how to configure them in the Marketing and Editors A/B Testing section.

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.

In the Content section of Umbraco, you will 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.

Analytics

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.

A/B Testing

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:

Personalization

The Personalization content app allows you to score a specific page based on the customer journey and persona (for implicit content scoring).

It also allows you to setup personalized variants of each node.

Managing the access to content apps

In the Engage -> Settings section, you can manage which Document Types the content apps are displayed, and which Umbraco user groups can access them. They can be managed per Document Type and per user group

The Umbraco Engage Checklist

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.

1. The Engage section

After logging in to Umbraco, you can see the Engage 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 Engage section.

2. Engage Content Apps

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 Engage section.

3. Cockpit

Is the Umbraco Engage Cockpit tool visible on the front end of your site after logging into Umbraco?

No? Ensure you have added the Cockpit Partial view in your main template.

4. Cockpit Client-Side Data

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.

5. Umbraco Forms

Go to a form and add a new question. Do you see this option?

Go to Engage -> 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.

6. Analytics

Edit a page and go to the Content App marked Analytics or Engage -> 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.

7. Locations for Analytics

Do you only see 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:

8. Setup IP Filters

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.

9. Reload after Cookie consent

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.

Still missing analytical data?

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.

You may want to build segments with custom rules not included in 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 three steps:

1. C# Definition

2. AngularJS Definition

3. [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 files to your project to add the parameter directly to your solution.

1. C# Definition

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:

// Define the segment rule
public class DayOfWeekSegmentRule : BaseSegmentRule
{
    public DayOfWeekSegmentRuleConfig TypedConfig { get; }
    
    public override SegmentRuleValidationMode ValidationMode => SegmentRuleValidationMode.Once;

    public DayOfWeekSegmentRule(long id, long segmentId, string type, string config, 
    bool isNegation, DateTime created, DateTime? updated, DayOfWeekSegmentRuleConfig typedConfig)
        : base(id, segmentId, type, config, isNegation, created, updated)
        => TypedConfig = typedConfig;
    
    public override bool IsSatisfied(IPersonalizationProfile context)
        => context.Pageview.Timestamp.DayOfWeek == TypedConfig.DayOfWeek;
}