Skip to content

Commit 8139860

Browse files
eshanrnheshanrnh
committed
cleanup articles and added descriptions
1 parent 14b2d68 commit 8139860

File tree

16 files changed

+242
-83
lines changed

16 files changed

+242
-83
lines changed

‎13/umbraco-ums/developers/ab-testing/csharp-api.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
description: >-
3+
Explore how to retrieve active A/B test variants for visitors using the uMarketingSuite C# API.
4+
---
5+
16
# C# API
27

38
{% hint style="info" %}

‎13/umbraco-ums/developers/ab-testing/extending-the-algorithms.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
description: >-
3+
Learn about the current limitations of implementing custom algorithms in uMarketingSuite.
4+
---
5+
16
# Extending the Algorithms
27

38
Currently, implementing custom algorithms is not straightforward. While future support for this feature is planned, it is not a top priority at this time.

‎13/umbraco-ums/developers/analytics/client-side-events-and-additional-javascript-files/additional-measurements-with-our-ums-analytics-scripts.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
description: >-
3+
Learn how to enhance your website's analytics by adding the uMarketingSuite JavaScript file.
4+
---
5+
16
# Additional Measurements with uMS Analytics Scripts
27

38
You can add the uMarketingSuite Analytics JavaScript file to your website by placing this code before the closing `</body>` tag of your website.

‎13/umbraco-ums/developers/analytics/extending-analytics/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
description: >-
3+
Discover how to enhance the accuracy of your uMarketingSuite Analytics by replacing
4+
specific extractors to collect additional or more accurate data.
5+
---
6+
17
# Extending Analytics
28

39
Data collection is essential to the uMarketingSuite's Analytics feature. When a visitor requests a page on your website, the web request is analyzed for relevant information, which is then stored in the database.

‎13/umbraco-ums/developers/analytics/extending-analytics/getting-the-correct-ip-address.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
description: >-
3+
Learn how to extract client IP addresses in uMarketingSuite by implementing a
4+
custom IP address extractor for specific server environments.
5+
---
6+
17
# Getting the Correct IP Address
28

39
By default, the uMarketingSuite 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.

‎13/umbraco-ums/developers/analytics/extending-analytics/implement-an-ip-to-location-provider.md‎

Lines changed: 66 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,102 @@
1-
# Implement an IP to location provider
1+
---
2+
description: >-
3+
Learn how to implement an IP to location provider in uMarketingSuite to enhance your analytics
4+
with geographical data from incoming traffic.
5+
---
26

3-
The uMarketingSuite Analytics provides native support for storing and reporting localization information for your incoming traffic. When we speak of localization, we refer to the ability to identify the (physical) origin of an incoming request. By design, requests sent to your website from a visitor's browser will never contain a location of origin. As the uMarketingSuite does not contain any localization information, you will have to provide your own implementation that provides this.
7+
# Implement an IP to Location Provider
48

5-
Most localization services, such as provided by Maxmind, use IP addresses to perform a (rough) lookup. The information is compiled into a database where lookups can be performed. However IP addresses do not contain any information regarding their (physical) origin, rather they only identify a device on the internet. Because of this the localization information for any given IP address is tracked manually and can change wildly (and sometimes regularly). We recommend either using an external service or acquiring a copy of a GeoIP database for localization lookup purposes.
9+
The uMarketingSuite Analytics natively supports storing and reporting localization information for incoming traffic. Localization refers to identifying the (physical) origin of an incoming request. Web requests from a visitor's browser do not contain location information, so you must provide an implementation for this.
10+
11+
Most localization services, such as Maxmind, use IP addresses to perform a (rough) lookup. The information is compiled into a database where lookups can be performed. However IP addresses do not contain any information regarding their (physical) origin, rather they only identify a device on the internet. Localization information for any given IP address is tracked manually and can change overtime. We recommend either using an external service or acquiring a copy of a GeoIP database for localization lookup purposes.
612

713
## Implementation
814

9-
Once you have a service that can provide localization information, it is very easy to integrate this into the uMarketingSuite. For this purpose we will be implementing the interface **uMarketingSuite.Business.Analytics.Processing.Extractors.IRawPageviewLocationExtractor**. As the name suggests, this interface defines a service that allows the provision of localization information given a pageview, defined as a single visit from a single visitor on a single page at one specific point in time. The pageview will contain the property **IpAddress** which you can use for the Geo IP lookup.
15+
Once you have a service that can provide localization information, integrating it into uMarketingSuite is straightforward.
1016

11-
First we define a class implementing **ILocation**, which will hold the localization information that will be returned through the interface in our implementation:
17+
For this purpose, implement the interface **uMarketingSuite.Business.Analytics.Processing.Extractors.IRawPageviewLocationExtractor**. This interface allows the localization information for a pageview, defined as a single visitor's visit to a specific point in time. The pageview contains the property **IpAddress** which can be used for Geo IP lookup.
1218

13-
using uMarketingSuite.Business.Analytics.Processed;public class GeoIpLocation : ILocation{
14-
public string Country { get; set; }
15-
public string County { get; set; }
16-
public string Province { get; set; }
17-
public string City { get; set; }
18-
}
19+
First, define a class that implements **ILocation**, to hold the localization information that will be returned through the interface in our implementation:
1920

20-
We are now ready to implement the location extractor. First, we will read and validate the incoming IP address. We also filter out local IP addresses with the native **IsLoopback** method. After this you can call your own Geo IP localization implementation:
21+
```cs
22+
using uMarketingSuite.Business.Analytics.Processed;public class GeoIpLocation : ILocation{
23+
public string Country { get; set; }
24+
public string County { get; set; }
25+
public string Province { get; set; }
26+
public string City { get; set; }
27+
}
28+
```
2129

22-
using uMarketingSuite.Business.Analytics.Processing.Extractors;public class MyCustomLocationExtractor : IRawPageviewLocationExtractor
30+
Next, implement the location extractor to read and validate the incoming IP address and filter out local IP addresses with the native **IsLoopback** method. Then, call your Geo IP localization implementation:
31+
32+
```cs
33+
using uMarketingSuite.Business.Analytics.Processing.Extractors;public class MyCustomLocationExtractor : IRawPageviewLocationExtractor
34+
{
35+
public ILocation Extract(IRawPageview rawPageview)
2336
{
24-
public ILocation Extract(IRawPageview rawPageview)
25-
{
26-
if (!IPAddress.TryParse(rawPageview?.IpAddress, out var ipAddress) || IPAddress.IsLoopback(ipAddress)) return null;
37+
if (!IPAddress.TryParse(rawPageview?.IpAddress, out var ipAddress) || IPAddress.IsLoopback(ipAddress)) return null;
2738

28-
string country, county, province, city;
39+
string country, county, province, city;
2940

30-
//...
31-
// Perform your own GEO IP lookup here
32-
// ...
41+
//...
42+
// Perform your own GEO IP lookup here
43+
// ...
3344
34-
var location = new GeoIpLocation
35-
{
36-
Country = country,
37-
County = county,
38-
Province = province,
39-
City = city
40-
};
45+
var location = new GeoIpLocation
46+
{
47+
Country = country,
48+
County = county,
49+
Province = province,
50+
City = city
51+
};
4152

42-
return location;
43-
}
53+
return location;
4454
}
55+
}
56+
```
4557

46-
Lastly we will need to let the IoC container know to use your implementation for the **IRawPageviewLocationExtractor**. The uMarketingSuite has a default implementation of this service, which only returns null. This default service is registered using Umbraco's **RegisterUnique** method. To override this service we will need to call RegisterUnique **after** the uMarketingSuite dependencies have been initialised, which is **after** the uMarketingSuite's **UMarketingSuiteApplicationComposer**:
58+
Lastly, let the IoC container know to use your implementation for the **IRawPageviewLocationExtractor**. The uMarketingSuite has a default implementation of this service, which only returns null. This default service is registered using Umbraco's **RegisterUnique** method. To override this service, call RegisterUnique **after** the uMarketingSuite dependencies have been initialized, which is **after** the uMarketingSuite's **UMarketingSuiteApplicationComposer**:
4759

48-
using uMarketingSuite.Business.Analytics.Processing.Extractors;
49-
using uMarketingSuite.Common.Composing;
50-
using Umbraco.Core;
51-
using Umbraco.Core.Composing;
60+
```cs
61+
using uMarketingSuite.Business.Analytics.Processing.Extractors;
62+
using uMarketingSuite.Common.Composing;
63+
using Umbraco.Core;
64+
using Umbraco.Core.Composing;
5265

53-
[ComposeAfter(typeof(UMarketingSuiteApplicationComposer))]
54-
public class UMarketingSuiteComposer : IComposer
66+
[ComposeAfter(typeof(UMarketingSuiteApplicationComposer))]
67+
public class UMarketingSuiteComposer : IComposer
68+
{
69+
public void Compose(IUmbracoBuilder builder)
5570
{
56-
public void Compose(IUmbracoBuilder builder)
57-
{
58-
builder.services.AddUnique<IRawPageviewLocationExtractor, MyCustomLocationExtractor>();
59-
}
71+
builder.services.AddUnique<IRawPageviewLocationExtractor, MyCustomLocationExtractor>();
6072
}
73+
}
74+
```
75+
76+
After implementing this, the uMarketingSuite will begin collecting and displaying localization information for pageviews. This can be viewed in the Analytics section of the uMarketingSuite dashboard.
6177

62-
After the service has been implemented correctly, the uMarketingSuite should start collecting and displaying localization information for pageviews. This can be viewed in the Analytics section of the uMarketingSuite dashboard in Umbraco. Note that if your custom implementation returns **null** as **ILocation** this will be displayed in uMarketingSuite as "Unknown".
78+
{% hint style="info" %}
79+
If the custom implementation returns **null**, **ILocation** will display as "Unknown".
80+
{% endhint %}
6381

64-
**Keep in mind that the LocationExtractor is only executed for incoming pageviews and will not retroactively apply to historical data**.
82+
{% hint style="info" %}
83+
The LocationExtractor only processes new pageviews and will not apply retroactively to historical data.
84+
{% endhint %}
6585

66-
## Analytics location report
86+
## Analytics Location Report
6787

68-
The localization information is displayed under the tab Location in the Analytics section of the uMarketingSuite dashboard:
88+
The localization information is displayed under the **Location** tab in the **Analytics** section of the uMarketingSuite dashboard:
6989

7090
![Location tab, located under the Analytics section]()
7191

7292
The graph contains all sessions that were started for the given time period, similar to the tab "**New and returning visitors**". As this information is not location bound this graph is always displayed, even if no localization information is present.
7393

74-
Underneath the graph you may find the table containing session and pageview information per country. If you have not implemented the LocationExtractor service, or if the pageviews for the given date range do not contain location information, the following error is displayed instead of the table:
94+
Underneath the graph you may find the table containing session and pageview information per country. If the LocationExtractor service is not implemented or the pageviews for the given date range do not contain location information, the following error is displayed:
7595

7696
![Location table - missing data error]()
7797

7898
If the pageviews contain location information, the table with countries is displayed:
7999

80100
![Location table with data]()
81101

82-
From country, you can drilldown to city. This will then filter the displayed graph and table data to only display session and pageview information for the selected country. Even though the uMarketingSuite does support the storage for county and province as well, currently the UI only supports displaying data by country and city.
102+
From country, you can drilldown to city. This will then filter the displayed graph and table data to only display session and pageview information for the selected country. Even though the uMarketingSuite does support the storage for county and province as well, currently the UI only supports displaying data by country and city.

‎13/umbraco-ums/developers/analytics/extending-analytics/sending-data-to-the-gtm-datalayer.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
description: >-
3+
Discover how to push A/B testing and personalization variables from uMarketingSuite to the
4+
Google Tag Manager (GTM) data layer in Razor templates.
5+
---
6+
17
# Sending Data to the GTM Data Layer
28

39
The uMarketingSuite provides a partial view that pushes variables related to A/B testing and personalization to the Google Tag Manager (GTM) data layer.
@@ -33,4 +39,4 @@ This partial will render the following output:
3339
personalizationname: "The name of the personalized variant",
3440
});
3541
</script>
36-
```
42+
```

‎13/umbraco-ums/developers/headless/README.md‎

Lines changed: 59 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,76 @@
1-
# headless
1+
---
2+
description: >-
3+
Discover how to integrate the uMarketingSuite.Headless package with Umbraco 12.0+ for a Content Delivery API.
4+
---
25

3-
uMarketingSuite has an optional package that can be installed called **uMarketingSuite.Headless** that hooks into Umbraco 12.0+ Headless Content Delivery API to offer you the power of personalized content with your A/B tests and segmentation.
6+
# Headless
47

5-
### Requirements
8+
The uMarketingSuite has a **uMarketingSuite.Headless** package that can be installed to integrate with Umbraco 12.0+. Headless Content Delivery API, enabling personalized content, A/B tests, and segmentation.
69

7-
The main requirement to install uMarketingSuite Headless is that it depends on **Umbraco v12 and higher** due to integrating with the [content delivery API](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api).
10+
## Requirements
811

9-
This also requires uMarketingSuite 1.25.0 and higher and has the same requirements of needing a SQL Server database and can not be used with SQLite databases.
12+
To install uMarketingSuite.Headless, ensure the following:
1013

11-
In addition to this the [Umbraco content delivery API needs to be enabled with the configuration setting](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#enable-the-content-delivery-api)\
12-
**Umbraco:CMS:DeliveryApi:Enabled** set to true
14+
- Umbraco v12 or higher is required to integrate with the [Content Delivery API](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api).
15+
- uMarketingSuite 1.25.0 or higher
16+
- A SQL Server database is needed; SQLite databases are not supported.
17+
- Enable the [Umbraco Content Delivery API](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#enable-the-content-delivery-api) with the following configuration setting:
1318

14-
```
15-
{ "Umbraco": { "CMS": { "DeliveryApi": { "Enabled": true } } }}
16-
```
19+
```json
20+
{
21+
"Umbraco": {
22+
"CMS": {
23+
"DeliveryApi": {
24+
"Enabled": true
25+
}
26+
}
27+
}
28+
}
29+
```
1730

18-
### Installing uMarketingSuite Headless API
31+
## Installing uMarketingSuite Headless API
1932

20-
**Ensure you already have uMarketingSuite installed and upgraded to 1.25.0**, you can follow the [normal install instructions for uMarketingSuite](../../../../installing-umarketingsuite/). Once this has been upgraded to 1.25.0+
33+
To install uMarketingSuite Headless API, follow these steps:
2134

22-
You can install uMarketingSuite Headless API from Nuget with the package ID [**uMarketingSuite.Headless**](https://www.nuget.org/packages/uMarketingSuite.Headless) this can be installed using IDE (Visual Studio, JetBrains Rider) or via the command line.
35+
1. Ensure uMarketingSuite is upgraded:
2336

24-
If you are using the command line, navigate to your Umbraco website root folder in your terminal and then run the following command
37+
- Verify that uMarketingSuite is installed and upgraded to **1.25.0**. For more information, see the [installation instructions for uMarketingSuite](../../../../installing-umarketingsuite/).
2538

26-
```
27-
dotnet add package uMarketingSuite.Headless
28-
```
39+
2. Install the uMarketingSuite.Headless package:
2940

30-
#### Updating Startup.cs
41+
- **Using an IDE:** Install the [**uMarketingSuite.Headless**](https://www.nuget.org/packages/uMarketingSuite.Headless) package from NuGet in Visual Studio, JetBrains Rider
42+
- **Using the command line:**
3143

32-
The next step requires updating your Startup.cs file to include the following line in the **ConfigureServices** method **.AddMarketingApiDocumentation()** and importantly to be specified after the line **.AddDeliveryApi()** from Umbraco. Your ConfigureServices method may look something like this:
44+
- Navigate to your Umbraco website root folder in your terminal.
45+
- Run the following command:
3346

34-
```
35-
public void ConfigureServices(IServiceCollection services){ services.AddUmbraco(_env, _config) .AddBackOffice() .AddWebsite() .AddDeliveryApi() .AddMarketingApiDocumentation() .AddComposers() .Build();}>
36-
```
47+
```cs
48+
dotnet add package uMarketingSuite.Headless
49+
```
3750

38-
You can now rebuild your site and run it and navigate to **/umbraco/swagger** and from the top right definition dropdown you should be able to see the **uMarketingSuite Marketing API**
51+
## Updating Startup.cs
52+
53+
To update the Startup.cs file, follow these steps:
54+
55+
1. Open your Startup.cs file.
56+
2. Locate the **ConfigureServices** method.
57+
3. Add the line **.AddMarketingApiDocumentation()** after **.AddDeliveryApi()**. Your ConfigureServices method should look like this:
58+
59+
```cs
60+
public void ConfigureServices(IServiceCollection services)
61+
{
62+
services.AddUmbraco(_env, _config)
63+
.AddBackOffice()
64+
.AddWebsite()
65+
.AddDeliveryApi()
66+
.AddMarketingApiDocumentation()
67+
.AddComposers()
68+
.Build();
69+
}
70+
```
71+
72+
4. Rebuild and run your site.
73+
5. Navigate to **/umbraco/swagger** in your browser.
74+
6. From the top right definition dropdown, check for the **uMarketingSuite Marketing API**
3975

4076
![]()

‎13/umbraco-ums/developers/personalization/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
description: >-
3+
Learn how to extend personalization in Umbraco uMS to serve tailored content to specific user groups.
4+
---
5+
6+
17
# Extending personalization
28

39
The personalization provided by Umbraco uMS is built so users can personalize the content or layout of any page without programming skills from the UI.

0 commit comments

Comments
 (0)