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, and manage segmentation for visitors.
4
+
---
2
5
3
-
Now you have installed and setup the uMarketingSuite Headless API we can jump in and learn about how to use it.
6
+
# Using the Marketing API
4
7
5
-
### Summary
8
+
After setting up the uMarketingSuite Headless API, let us learn how to use it.
6
9
7
-
Out of the box uMarketingSuite segmented content and A/B tests will work out of the box with Umbraco's Content Delivery API and return the correct content to the user and we suggest you refer to [Umbraco's official documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#enable-the-content-delivery-api) in order to understand how to use and query content from Umbraco.
10
+
## Summary
8
11
9
-
In order to track a user to the site and potentially place them into a segment and associate a persona, we will need to track which pages the visitor is viewing and this needs to be done by making a HTTP POST request to the **/umbraco/umarketingsuite/api/v1/analytics/pageview/trackpageview/client** endpoint with the following JSON body to indicate what page the user has visited.
12
+
uMarketingSuite's 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).
10
13
11
-
```
14
+
To track user activity and assign segments or personas, make an HTTP POST request to:
with the following JSON body to indicate what page the user has visited.
19
+
20
+
```json
12
21
{ "url": "https://localhost:44374"}
13
22
```
14
23
15
-
The logic in uMarketingSuite will determine if the user has met any thresholds to put them into a segment, into an A/B test or any personalization should be applied and subsequent requests to the Umbraco content API can then deliver the personalised content.
16
-
17
-
**Why does uMarketingSuite need to be explicitly notified?**
24
+
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.
18
25
19
-
As we can't assume a single request to the Umbraco Content Delivery API means one page visit.
26
+
uMarketingSuite needs to be explicitly notified because a single request to Umbraco's Content Delivery API represents one page visit.
20
27
21
-
###Configuration
28
+
## Configuration
22
29
23
-
The settings for uMarketingSuite Headless package can be configured via .NET Options be it with an AppSettings JSON file, Environment Variables or some other configuration source.
30
+
uMarketingSuite Headless package settings can be configured through .NET options, including AppSettings JSON file, Environment Variables, or other configuration sources.
24
31
25
-
Below is an example of configuration values used in AppSettings.json which if you use a modern IDE such as Visual Studio or JetBrains Rider then you will get auto completions on the available settings uMarketingSuite.Headless package offers you.
32
+
An example of configuration in AppSettings.json file:
The values are watched by .NET so these can be changed at runtime without having the website to be restarted for these changes to configuration to take effect.
47
+
The settings can be changed at runtime without restarting the website for these changes to take effect.
**/umbraco/umarketingsuite/api/v1/analytics/pageview/trackpageview/client**This request is used to track a page view and requires the **url** property of the page that a user has visited in the site, optionally the **reffererUrl** can be set to inform uMarketingSuite where the user came from.
62
+
- Required: `url` property of the page that a user has visited in the site
63
+
- Optional: `reffererUrl` can be set to inform uMarketingSuite where the user came from.
43
64
44
-
**/umbraco/umarketingsuite/api/v1/analytics/pageview/trackpageview/server**This is used as the same above, but is useful when a frontend JAMStack Server such as a NuxtJS server or similar is being used and can notify uMarketingSuite when a page view has taken place and provide us extra information; request **headers**, **browserUserAgent**, **remoteClientAddress** and **userIdentifier**
- Useful when a frontend JAMStack Server such as a NuxtJS server or similar is being used.
68
+
- Can notify uMarketingSuite when a page view has taken place and provide extra information.
69
+
- Requests extra metadata like `headers`, `browserUserAgent`, `remoteClientAddress`, and `userIdentifier`.
45
70
46
71
**Client and Server**
47
72
48
-
uMarketingSuite tries to get a bunch of information about you as a visitor based on your request. It does so by extracting said information from your request, e.g. HTTPContext.
73
+
uMarketingSuite gathers information about visitors based on their requests, extracting details from your request like HTTPContext.
74
+
75
+
-**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.
49
76
50
-
The Client side version is you were to make an API call directly to Umbraco straight from your browser, meaning that all the meta-data about the request is just... your request. Your IP address, your cookies, your request headers, etc...
77
+
-**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, uMarketingSuite 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.
51
78
52
-
The Server side version is if you were to have a server in between your browser & Umbraco, like a NuxtJS server, to do the rendering and handling of requests. Because of such a server, each request coming to Umbraco isn't the end-client, but our NuxtJS server, meaning that we wouldn't be tracking the headers, IP addresses etc. from those requests, but from the server instead. Therefor you can use the Server version to add that additional meta-data to your pageview tracking in between the Next.JS server & Umbraco.
Introduced in version 2.3.0, this request is used to track events. After tracking a pageview using the Analytics TrackPageview API as mentioned above, you will receive both an externalVisitorId & **pageviewId**. In order to track events, the request requires a supplied pageview-Id header, and a request body containing a **category**, **action**_(optional)_, **label**_(optional)_ and **timestamp**_(optional)._
85
+
- After tracking a pageview using the Analytics TrackPageview API as mentioned above, you will receive both an externalVisitorId and `pageviewId`.
86
+
- Requires a supplied pageview-Id header and a request body containing a `category`, `action`_(optional)_, `label`_(optional)_, and `timestamp`_(optional)_.
59
87
60
-
Optionally you can also provide an External-Visitor-Id header in order to automatically update the in-memory visitorto automatically reflect segments involving events for said visitors. Without supplying this parameter, the pageview has to be flushed to the database (as per configuration) before any segment information gets updated (e.g. personalization variants using segments based on events).
88
+
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.
These two requests allow you to see if the content page by its ID or Path has a variant with **Javascript or CSS**that has been added for you to inject into your page for a
95
+
These requests let you verify if a content page, by ID or Path, has a **JavaScript** or **CSS**variant available for page injection.
These requests return information about which segments (personalization & A/B testing) are configured to be on a page in general. This could be used to know if a page could have content that could change by uMarketingSuite and if not it could perhaps be cached more aggressively.
105
+
These requests return details about segments (personalization and A/B testing) configured for a page. This helps determine if content can be changed by uMarketingSuite or cached more aggressively.
Discover how to create and manage segments to personalize the website experience for specific visitor groups.
4
+
---
5
+
1
6
# Creating a segment
2
7
3
-
To start personalizing the website experience of your visitor you need to define groups of visitors that you want to give a personalized experience. These groups of visitors are called '**segments**' in the uMarketingSuite.
8
+
To start personalizing the website experience of your visitor, you need to define groups of visitors, called **Segments** in the uMarketingSuite.
4
9
5
-
The first step is to define these segments and from there you can start personalizing the website experience.
10
+
You must first define these segments and then you can start personalizing the website experience.
6
11
7
-
## Segment builder
12
+
## Segment Builder
8
13
9
-
Segments are created via the unique uMarketingsuite segment builder. This segment builder can be found in the subsection "**Personalization**" and the tab "**Segments**".
14
+
Segments are created via the uMarketingsuite segment builder, located under the **Personalization** and the **Segments** tab.
10
15
11
16
![]()
12
17
13
-
You can create a segment by clicking "**Add new segment**" in the segment builder section. This will open up a popup.
18
+
To create a new segment, follow these steps:
19
+
20
+
1. Navigate to the segment builder section.
21
+
2. Click **Add new segment**.
14
22
15
23
![]()
16
24
17
-
First you have to give the new segment a name and a short description. You also have the option to specify the segment type:
25
+
3. Give the new segment a **Name** and a short **Description**.
26
+
4. Select a segment type:
18
27
19
-
-**Core segments** are the fundamental building blocks of your personalization strategy
20
-
-**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. For doing this you need to specify an end date
28
+
-**Core segments** are the fundamental building blocks of your personalization strategy
29
+
-**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. For doing this you need to specify an end date
21
30
22
-
### Segment parameters
31
+
### Segment Parameters
23
32
24
-
To specify which visitors are part of this segment you can setup one or more segment parameters. The uMarketingSuite comes with several out-of-the-box parameters, but you can also [implement your own segment parameters](/personalization/extending-personalization/implement-your-own-segment-parameters/).
33
+
To specify which visitors are part of this segment you can setup one or more segment parameters. uMarketingSuite comes with out-of-the-box parameters, but you can also [implement your own segment parameters](/personalization/extending-personalization/implement-your-own-segment-parameters/).
25
34
26
-
By default the uMarketingSuite gives you the following parameters:
35
+
By default, uMarketingSuite provides the following parameters:
27
36
28
37
- Persona
29
38
- Journey
@@ -35,10 +44,10 @@ By default the uMarketingSuite gives you the following parameters:
35
44
- Reached goals
36
45
- Campaigns
37
46
38
-
By clicking on the tile you will setup a parameter for the segment. You can for example want to implement a segment where you group "**All visitors that use firefox after 15:00**" in one segment. To do that you
47
+
By clicking on the tile you will setup a parameter for the segment. For example, to implement a segment where you group **All visitors that use firefox after 15:00** in one segment. To do that:
39
48
40
-
1. Create a new segment with the name "**My first segment**"
41
-
2. Click on the "**Browser**" tile and "**include**" all visitors with the browser "**Firefox**"
49
+
1. Create a new segment with the name **My first segment**.
50
+
2. Click the **Browser** tile and **include** all visitors using the browser **Firefox**.
42
51
43
52
![]()
44
53
@@ -47,43 +56,43 @@ You see all browsers that have visited the website. So if you're missing a speci
47
56
You can save the parameter and the segment will show the parameter that is part of this segment.
48
57
49
58
![]()
50
-
3.Now you can add a parameter for "**Time of day**" because we want to select all visitors after "**15:00**". By clicking on the segment tile "**Time of day**" we can setup the parameter. We put "**15:00**" in **From** and leave "**Until**" empty.
59
+
3.Add a parameter for **Time of day**to select all visitors after "**15:00**". Enter **15:00** in **From** and leave **Until** empty.
51
60
52
61
![]()
53
62
54
63
Now we can save this parameter and add the segment.
55
64
56
-
We've now created a first segment and you will find that segment in the overview of your segments:
65
+
We have now created a first segment and you will find that segment in the overview of your segments:
57
66
58
67
![]()
59
68
60
-
## Editing and deleting segments
69
+
## Editing and Deleting Segments
61
70
62
-
By clicking on the icons at the end of the segment line you can edit the segment or delete the segment. **Please be aware that segments only can be deleted if there is no personalization applied for this segment.** You can see how often the segment is used in the 3rd column:
71
+
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:
63
72
64
73
![]()
65
74
66
-
By hovering over the icon you see what kind of personalization is applied:
75
+
By hovering over the icon you can see what kind of personalization is applied:
67
76
68
77
![]()
69
78
70
-
If you would try to delete this segment the uMarketingSuite will tell you that personalization is applied and that makes it impossible to delete the segment at this moment.
79
+
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.
71
80
72
81
![]()
73
82
74
-
In the popup, it shows on which pages the personalization is applied and you can click directly to these pages.
83
+
The popupshows which pages the personalization is applied and you can click directly to these pages.
75
84
76
-
## Ordering your segments
85
+
## Ordering Segments
77
86
78
-
The **order of your segments is really important**, because the uMarketingSuite will **only apply one segment per visitor**. So if a visitor falls into multiple segments the segment with the highest priority is applied. Please be aware that is only the case if there's an actual personalization available! If the highest ranking segment does not have any personalization applied, the uMarketingSuite will go to the next available segment that has personalization applied. If none of the segments has personalizaton applied the uMarketingSuite will fallback to the default content.
87
+
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 personalizaton applied, it will fallback to the default content.
79
88
80
89
The ordering of segment is based on:
81
90
82
-
-**Temporary versus Core segments**. Temporary segments are always applied first. Only if the temporary segments do not apply the core segments are being used.
83
-
- Within the temporary and core segments the given priority is being used. The **highest segment** will be applied first.
91
+
-**Temporary versus Core segments**: Temporary segments are always applied first. Only if the temporary segments do not apply the core segments are being used.
92
+
-**Priority within each segment type**: Within the temporary and core segments the given priority is being used. The **highest segment** will be applied first.
84
93
85
-
The priority can be changed by using the arrows in the segment overview:
94
+
You can adjust the segment order using the arrows in the segment overview.
86
95
87
96
![]()
88
97
89
-
Now that we've created our segment we can start [personalizing the website experience of our visitors](/personalization/setting-up-personalization/)!
98
+
Now that your segment is created, you can start [personalizing the website experience for visitors](/personalization/setting-up-personalization/).
0 commit comments