Umbraco Engage offers the Umbraco.Engage.Headless package for seamless integration with Umbraco 12.0 and later. This package enables access to the Headless Content Delivery API, enabling personalized content, A/B tests, and segmentation.

Requirements

To install Umbraco.Engage.Headless, ensure the following prerequisites:

• Umbraco v13 is required to integrate with the Content Delivery API.

• Enable the Umbraco Content Delivery API by adding the following configuration setting in the appsettings.json file:

{
"Umbraco": {
    "CMS": {
        "DeliveryApi": {
            "Enabled": true
        }
    }
}
}

Installing the Umbraco Engage Headless API

To install the Umbraco Engage Headless API, follow these steps:

1. Install the Umbraco.Engage.Headless package:

• Using an IDE: Install the Umbraco.Engage.Headless package from NuGet in Visual Studio or JetBrains Rider.

• Using the command line:

  • Navigate to your Umbraco website root folder in your terminal.

  • Run the following command:

dotnet add package Umbraco.Engage.Headless

Updating Program.cs

To update the Program.cs file, follow these steps:

1. Open your Program.cs file.

2. Add the line .AddEngageApiDocumentation() after .AddDeliveryApi(). Your CreateUmbracoBuilder method should look like this:

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddEngageApiDocumentation()
    .AddComposers()
    .Build();

1. Rebuild and run your site.

2. Navigate to /umbraco/swagger in your browser.

3. Check for the Umbraco Engage API from the top right definition dropdown.

After setting up the Umbraco Engage Headless API, let us learn how to use it.

Summary

Umbraco Engage segmented content and A/B tests work with Umbraco's Content Delivery API, delivering the correct content. For more details on how to use and query content from Umbraco, see the .

To track user activity and assign segments or personas, make an HTTP POST request to:

/umbraco/engage/api/v1/analytics/pageview/trackpageview/client endpoint

with the following JSON body to indicate what page the user has visited.

This determines if the user meets criteria for segmenting, A/B testing, or applying personalization. Subsequent requests to the Umbraco content API then deliver personalized content.

Umbraco Engage needs to be explicitly notified because a single request to Umbraco's Content Delivery API represents one page visit.

Configuration

Umbraco Engage Headless package settings can be configured through .NET options, including AppSettings JSON file, Environment Variables, or other configuration sources.

An example of configuration in AppSettings.json file:

The settings can be changed at runtime without restarting the website for these changes to take effect.

Analytics

To track a page view, send a POST request to:

/umbraco/engage/api/v1/analytics/pageview/trackpageview/client

• Required: url property of the page that a user has visited in the site

• Optional: reffererUrl can be set to inform Umbraco Engage where the user came from.

/umbraco/engage/api/v1/analytics/pageview/trackpageview/server

• Useful when a frontend JAMStack Server such as a NuxtJS server or similar is being used.

• Can notify Umbraco Engage when a page view has taken place and provide extra information.

• Requests extra metadata like headers, browserUserAgent, remoteClientAddress, and userIdentifier.

Client and Server

Umbraco Engage gathers information about visitors based on their requests, extracting details from your request like HTTPContext.

• Client-side: This version applies when you make an API call directly to Umbraco from your browser. In this case, all the request metadata, such as IP address, cookies, request headers, and so on, comes directly from your browser.

• Server-side: If there is a server between the browser and Umbraco, like a NuxtJS server, the requests tracked are from the server rather than the browser. In this scenario, Umbraco Engage does not receive metadata from the end-client's requests. Instead, you can use the server version to add this additional metadata (headers, IP addresses, and so on) to your pageview tracking between the NuxtJS server and Umbraco.

Page Events

To track events, send a POST request to:

/umbraco/engage/api/v1/analytics/pageevent/trackpageevent

• After tracking a pageview using the Analytics TrackPageview API as mentioned above, you will receive both an externalVisitorId and pageviewId.

• Requires a supplied pageview-Id header and a request body containing a category, action (optional), label (optional), and timestamp (optional).

Optionally, provide an External-Visitor-Id header in order to automatically update the in-memory visitor. This helps to automatically reflect segments involving events for said visitors. Without this parameter, the pageview must be flushed to the database (according to the configuration) before any segment-related information is updated. For example: personalization variants based on events.

Segmentation - Assets

/umbraco/engage/api/v1/segmentation/assets/item/{path} /umbraco/engage/api/v1/segmentation/assets/item/{id}

These requests let you verify if a content page, by ID or Path, has a JavaScript or CSS variant available for page injection.

Segmentation - Content

/umbraco/engage/api/v1/segmentation/content/segments /umbraco/engage/api/v1/segmentation/content/segments/{path} /umbraco/engage/api/v1/segmentation/content/segments/{id}

These requests return details about segments (personalization and A/B testing) configured for a page. This helps determine if content can be changed by Umbraco Engage or cached more aggressively.

Segmentation - Visitor

/umbraco/engage/api/v1/segmentation/content/activesegments/{path} /umbraco/engage/api/v1/segmentation/content/activesegments/{id}

These requests return the segment (personalization and A/B testing) that the current visitor ID of that specific page belongs to based on its cookie.

This article shows how to use the Umbraco Engage Headless API with Umbraco Content Delivery API.

Setting up a Personalization Segment

1. Go to the Engage > Personalization section.

2. Navigate to the Segments tab.

3. Click Add new Segment.

   • Give the segment a name. For example: Morning People.

   • And a description such as For people who like to visit us in the morning.

   • Set the segment type to Core as this is not temporary and is tied to an end date for a campaign.

   • Select the Time of day parameter and configure it to Include times from 00:00 to 12:00 as it is a 24-hour clock.

For more information, see the documentation.

Creating a Document Type for Personalization

1. Navigate to Settings.

2. Click Create a New Document Type.

3. Enable Allow Segmentation under Permissions.

4. Save the Document Type.

5. Add a new property, such as a Header, using a Textstring property editor.

   • Ensure Allow Segmentation is enabled for this property.

6. Create a piece of content using this new Document Type to query and request it using the Umbraco Content Delivery API

   • For this example, create this piece of content at the root.

Creating Personalized Content

1. Open the created content and go to Personalization.

2. Click Add personalized variant.

3. Set the following in the Add a new variant dialog:

   • Choose the segment Morning People we added earlier.

   • Give it a name and a meaningful description such as Home Page for Morning People.

1. After adding the variant we will return to the content node in split-view mode.

2. We can then add a different piece of content we want to return in our Header property specific to morning people such as Hello you early risers.

3. Save and publish the node with the variant content.

Using the Content Delivery API

Let us use the Swagger development tool to make requests to the Umbraco Content Delivery API and Umbraco Engage Headless API.

1. Navigate to the swagger endpoint of your site /umbraco/swagger.

2. Select Umbraco Delivery API from the dropdown.

3. Expand /umbraco/delivery/api/v1/content/item/{path}:

   • Click Try it out.

   • For the path parameter, enter / for the example piece of content we created at the root of our site - alternatively, specify the correct URL path to the content.
4. You should view the JSON result of the content node, including the default header value.

5. Navigate to Umbraco Engage Marketing API from the definitions dropdown.

6. Expand /umbraco/engage/api/v1/analytics/pageview/trackpageview/client:

   • Click Try it out.

   • Modify the JSON body, setting the URL to the page visited earlier. With the content delivery API above, leave the other property referrerUrl empty.

   • Repeat the earlier steps to fetch the content by its path. The JSON of the content node and the header property now contains our personalized content Hello you early risers

     • Remember it will only show different content if we view the page before midday.