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.
Copy file name to clipboardExpand all lines: 13/umbraco-ui-builder/known-issues.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ Umbraco UI Builder tries its best to mimic the content pipeline as closely as po
8
8
9
9
## Property Editors
10
10
11
-
### Tags
11
+
### Tags
12
12
13
13
Whilst we have support for persisting the tag's value, we don't currently have the ability to write these tags to the `cmsTags` DB table. This is all handled via a `tagsRepository` which is internal so we currently can't save to it as core does.
14
14
@@ -19,3 +19,7 @@ When using a Multi-Node Tree Picker with an XPath filter, only filters starting
19
19
### RTE Macros
20
20
21
21
Macros in Rich Text Editors don't appear to work properly due to the preview mechanism. They save and run on the front end, but you'll get an error notification in the backoffice as it tries to render a preview.
22
+
23
+
### Block Editors
24
+
25
+
The Block Editors (Block List/Block Grid) are not supported due to an `undefined` error with `umbVariantContent` in the `$scope` chain.
* Fixes a bug where inherited group members were not always mapped to the parent user group. This resulted in an incorrect warning message being displayed in the Backoffice [#92](https://github.com/umbraco/Umbraco.Workflow.Issues/issues/92)
22
29
* Fixes a bug where group permissions were not reset when removing a group from a Document Type approval flow. This caused an exception when attempting to initiate a workflow using the Document Type flow, as no permissions would be found for the first approval stage [#93](https://github.com/umbraco/Umbraco.Workflow.Issues/issues/93)
Copy file name to clipboardExpand all lines: 14/umbraco-cms/customizing/umbraco-package.md
+5-4Lines changed: 5 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,6 @@ Before Umbraco 14, the manifest was declared in a `package.manifest` file instea
20
20
"id": "My.Nuget.Package",
21
21
"name": "Sir Trevor",
22
22
"version": "1.0.0-beta",
23
-
"allowPackageTelemetry": true,
24
23
"extensions": [
25
24
{
26
25
"type": "propertyEditorUi",
@@ -48,7 +47,7 @@ The `umbraco-package` accept these fields:
48
47
"id": "",
49
48
"name": "",
50
49
"version": "",
51
-
"allowPackageTelemetry": true,
50
+
"allowTelemetry": true,
52
51
"allowPublicAccess": false,
53
52
"importmap": {
54
53
"imports": {
@@ -74,11 +73,13 @@ Allows you to specify a friendly name for your package that will be used for tel
74
73
75
74
The version of your package, if this is not specified there will be no version-specific information for your package. This is used for telemetry and to help users understand what version of your package they are using. It is also used for package migrations. The version should follow the [Semantic Versioning](https://semver.org/) format.
76
75
77
-
### Allow Package Telemetry
76
+
### Allow Telemetry
78
77
79
78
With this field, you can control the telemetry of this package, this will provide Umbraco with the knowledge of how many installations use this package.
0 commit comments