You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Learn how to use the Headless API to track page views, personalize content,
4
-
and manage segmentation for visitors.
3
+
Learn how to use the Umbraco Engage API to track page views, personalize
4
+
content, and manage segmentation for visitors.
5
5
---
6
6
7
-
# Using the Marketing API
7
+
# Using the Engage API
8
8
9
-
After setting up the Umbraco Engage Headless API, let us learn how to use it.
9
+
After setting up the Umbraco Engage API, let us learn how to use it.
10
10
11
-
## Summary
11
+
With the installation of `Umbraco.Engage.Headless` you can track visitor page views, personalize content, and manage segmentation for visitors through the Umbraco Engage API. Personalized 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 [Umbraco Documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#enable-the-content-delivery-api).
12
12
13
-
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 [Umbraco Documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#enable-the-content-delivery-api).
13
+
The steps to track & retrieve personalized content are as follows:
14
14
15
-
To track user activity and assign segments or personas, make an HTTP POST request to:
15
+
1. A new visitor visits their first page. An HTTP POST request is made to the `analytics/pageview/trackpageview/client` endpoint with the requested URL. This returns an External Visitor ID unique to this visitor.
16
+
2. Content is retrieved for that visitor through the Umbraco Content Delivery API. The External Visitor ID is used as the `External-Visitor-Id` header to retrieve content for that specific visitor.
17
+
3. The page is rendered using the retrieved content and returned to the visitor.
18
+
4. The same visitor visits another page. An HTTP POST request is made to the `analytics/pageview/trackpageview/client` endpoint with the requested URL **and** the _External-Visitor-Id_ header. This pageview will be attributed to the same visitor.
_Without providing the_`External-Visitor-Id`_header, each registered pageview will be considered as a new visitor._
22
+
{% endhint %}
18
23
19
-
with the following JSON body to indicate what page the user has visited.
24
+
5. Repeat these steps for each page visit for a new or existing visitor.
20
25
21
-
```json
22
-
{ "url": "https://localhost:44374"}
23
-
```
24
-
25
-
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.
26
+
By tracking visitor behavior, Engage 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.
26
27
27
28
Umbraco Engage needs to be explicitly notified because a single request to Umbraco's Content Delivery API represents one page visit.
28
29
29
30
## Configuration
30
31
31
32
Umbraco Engage Headless package settings can be configured through .NET options, including AppSettings JSON file, Environment Variables, or other configuration sources.
32
33
33
-
An example of configuration in AppSettings.json file:
34
+
An example of configuration in `AppSettings.json` file:
34
35
35
36
```json
36
37
"Engage": {
@@ -45,7 +46,7 @@ An example of configuration in AppSettings.json file:
45
46
}
46
47
```
47
48
48
-
The settings can be changed at runtime without restarting the website for these changes to take effect.
49
+
The settings can be changed at runtime without restarting the website for these changes to take effect. These configurations will toggle whether Umbraco Engage will apply segmentation to the various Content Delivery API endpoints when applicable.
The `externalVisitorId` is unique to this visitor and is to be used in subsequent API calls for this visitor, and this visitor only. The pageviewId is unique to this specific pageview and used in specific API's like tracking events on pageviews.
83
+
84
+
#### **Client and Server**
73
85
74
86
Umbraco Engage gathers information about visitors based on their requests, extracting details from your request like HTTPContext.
75
87
@@ -89,20 +101,113 @@ Optionally, provide an External-Visitor-Id header in order to automatically upda
These requests let you verify if a content page, by ID or Path, has a **JavaScript** or **CSS** variant available for page injection.
108
+
These requests let you verify if a content page has a **JavaScript** or **CSS** variant available for page injection for this specific visitor. This endpoint requires the External-Visitor-Id header to function. This returns the following response:
109
+
110
+
```json
111
+
{
112
+
"javascript": [
113
+
"alert('hello world')"
114
+
],
115
+
"css": [
116
+
"body { background-color:red; }"
117
+
]
118
+
}
119
+
```
95
120
96
121
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.
131
+
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. The information returned by the APIs is visitor agnostic and reflects all the segments as configured in Umbraco. This returns the following response:
These requests return the segment (personalization and A/B testing) that the current visitor ID of that specific page belongs to. This endpoint requires the External-Visitor-Id header to function. 
Umbraco Engage in a non-headless setup uses cookies to track returning visitors. This, however, has proven difficult to work with in a headless setup for most clients. Therefore, it is not a recommended way of working with the Engage API. 
203
+
204
+
Each API endpoint that allows for tracking analytics, segmentation, and retrieving content has support for adding the External Visitor ID header. This is a unique ID for an individual visitor and is to be used instead of the cookie. When tracking pageviews, a new External Visitor ID will be generated and is to be used for subsequent API calls corresponding to that visitor.
205
+
206
+
{% hint style="info" %}
207
+
A visitor will be considered an **existing visitor** when either of the following applies to the request:
208
+
209
+
* An `umbracoEngageAnalyticsVisitorId` cookie is present.
210
+
* An `External-Visitor-Id` Header is provided.
107
211
108
-
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.
212
+
If neither applies, the requests will be considered coming from a new visitor.
0 commit comments