NOTE: Apart from
(and even then it's questionable, I'm Scottish). These are machine translated in languages I don't read. If they're terrible please contact me.
You can see how this translation was done in this article.
Sunday, 18 August 2024
//6 minute read
In a previous post we added a client for fetching Umami analytics data. In this post we will add a client for sending tracking data to Umami from a C# application. Umami is a lightweight analytics service that can be self-hosted. It is a great alternative to Google Analytics and is privacy focused. However by default it only has a Node client for tracking data (and even then it's not GREAT). So I decided to write a C# client for tracking data.
Install Umami you can see how I do this here.
You can see all the source code for the client here.
This uses settings I have defined in my appsettings.json file.
"Analytics":{
"UmamiPath" : "https://umamilocal.mostlylucid.net",
"WebsiteId" : "32c2aa31-b1ac-44c0-b8f3-ff1f50403bee",
"UmamiScript" : "getinfo"
},
As the track API is not authenticated I have not added any authentication to the client.
In order to setup the client I've added my customary extension method with is called from your Program.cs file.
services.SetupUmamiClient(config);
This provides a simple way to hook in the UmamiClient to your application.
The code below shows the setup method.
public static void SetupUmamiClient(this IServiceCollection services, IConfiguration config)
{
var umamiSettings= services.ConfigurePOCO<UmamiClientSettings>(config.GetSection(UmamiClientSettings.Section));
if(string.IsNullOrEmpty( umamiSettings.UmamiPath)) throw new Exception("UmamiUrl is required");
if(string.IsNullOrEmpty(umamiSettings.WebsiteId)) throw new Exception("WebsiteId is required");
services.AddTransient<HttpLogger>();
services.AddHttpClient<UmamiClient>((serviceProvider, client) =>
{
umamiSettings = serviceProvider.GetRequiredService<UmamiClientSettings>();
client.DefaultRequestHeaders.Add("User-Agent", $"Mozilla/5.0 Node/{Environment.Version}");
client.BaseAddress = new Uri(umamiSettings.UmamiPath);
}).SetHandlerLifetime(TimeSpan.FromMinutes(5)) //Set lifetime to five minutes
.AddPolicyHandler(GetRetryPolicy())
#if DEBUG
.AddLogger<HttpLogger>();
#else
;
#endif
services.AddHttpContextAccessor();
}
static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy()
{
return HttpPolicyExtensions
.HandleTransientHttpError()
.OrResult(msg => msg.StatusCode == HttpStatusCode.ServiceUnavailable)
.WaitAndRetryAsync(6, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));
}
As you can see this does the following:
The UmamiClient is fairly simple. It has one core method Send which sends the tracking data to the Umami server.
public async Task<HttpResponseMessage> Send(UmamiPayload payload, string type = "event")
{
var jsonPayload = new { type, payload };
logger.LogInformation("Sending data to Umami {Payload}", JsonSerializer.Serialize(jsonPayload, options));
var response= await client.PostAsJsonAsync("/api/send", jsonPayload, options);
if(!response.IsSuccessStatusCode)
{
logger.LogError("Failed to send data to Umami {Response}, {Message}", response.StatusCode, response.ReasonPhrase);
}
else
{
var content = await response.Content.ReadAsStringAsync();
logger.LogInformation("Successfully sent data to Umami {Response}, {Message} {Content}", response.StatusCode, response.ReasonPhrase, content);
}
return response;
}
As you'll see this uses an object called UmamiPayload which contains all the possible parameters for tracking requests in Umami.
public class UmamiPayload
{
public string Website { get; set; }=string.Empty;
public string Hostname { get; set; }=string.Empty;
public string Language { get; set; }=string.Empty;
public string Referrer { get; set; }=string.Empty;
public string Screen { get; set; }=string.Empty;
public string Title { get; set; } =string.Empty;
public string Url { get; set; } =string.Empty;
public string Name { get; set; } =string.Empty;
public UmamiEventData? Data { get; set; }
}
public class UmamiEventData : Dictionary<string, object> { }
The only required field is Website which is the website id. The rest are optional (but Url is really useful!).
In the client I have a method called GetPayload() which sends populates this payload object automatically with information from the request (using the injected IHttpContextAccessor).
public class UmamiClient(HttpClient client, ILogger<UmamiClient> logger, IHttpContextAccessor accessor, UmamiClientSettings settings)...
private UmamiPayload GetPayload(string? url = null, UmamiEventData? data = null)
{
// Initialize a new UmamiPayload object
var payload = new UmamiPayload
{
Website = settings.WebsiteId,
Data = data ?? new UmamiEventData(),
Url = url ?? "" // Default URL to empty string if null
};
// Check if HttpContext is available
if (accessor.HttpContext != null)
{
var context = accessor.HttpContext;
var headers = context.Request.Headers;
// Fill payload details from HttpContext and headers
payload.Hostname = context?.Request.Host.Host ?? ""; // Default to empty string if null
payload.Language = headers?["Accept-Language"].ToString() ?? ""; // Safely retrieve Accept-Language header
payload.Referrer = headers?["Referer"].ToString() ?? ""; // Safely retrieve Referer header
payload.Screen = headers?["User-Agent"].ToString() ?? ""; // Safely retrieve User-Agent header
payload.Title = headers?["Title"].ToString() ?? ""; // Safely retrieve Title header
payload.Url = string.IsNullOrEmpty(url) ? context.Request.Path.ToString() : url; // Use the passed URL or fallback to the request path
}
return payload;
}
This is then used by further utility methods which give a nicer interface for this data.
public async Task<HttpResponseMessage> TrackUrl(string? url="", string? eventname = "event", UmamiEventData? eventData = null)
{
var payload = GetPayload(url);
payload.Name = eventname;
return await Track(payload, eventData);
}
public async Task<HttpResponseMessage> Track(string eventObj, UmamiEventData? eventData = null)
{
var payload = new UmamiPayload
{
Website = settings.WebsiteId,
Name = eventObj,
Data = eventData ?? new UmamiEventData()
};
return await Send(payload);
}
public async Task<HttpResponseMessage> Track(UmamiPayload eventObj, UmamiEventData? eventData = null)
{
var payload = eventObj;
payload.Data = eventData ?? new UmamiEventData();
payload.Website = settings.WebsiteId;
return await Send(payload);
}
public async Task<HttpResponseMessage> Identify(UmamiEventData eventData)
{
var payload = new UmamiPayload
{
Website = settings.WebsiteId,
Data = eventData ?? new()
};
return await Send(payload, "identify");
}
This allows you to track events, URLs and identify users.
In future I plan to make this into a NuGet package. Testing for that I have an entry in the Umami.Client.csproj file which generates a new versioned 'preview' package when built in debug mode.
<Target Name="NugetPackAutoVersioning" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
<!-- Delete the contents of the target directory -->
<RemoveDir Directories="$(SolutionDir)nuget" />
<!-- Recreate the target directory -->
<MakeDir Directories="$(SolutionDir)nuget" />
<!-- Run the dotnet pack command -->
<Exec Command="dotnet pack -p:PackageVersion=$([System.DateTime]::Now.ToString("yyyy.MM.dd.HHmm"))-preview -p:V --no-build --configuration $(Configuration) --output "$(SolutionDir)nuget"" />
<Exec Command="dotnet nuget push $(SolutionDir)nuget\*.nupkg --source Local" />
<Exec Command="del /f /s /q $(SolutionDir)nuget\*.nupkg" />
</Target>
This is added right before end </Project> tag in the .csproj file.
It depends on a nuget location called 'local' which is defined in the Nuget.config file. Which I have mapped to a local folder on my machine.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="Local" value="e:\nuget" />
<add key="Microsoft Visual Studio Offline Packages" value="C:\Program Files (x86)\Microsoft SDKs\NuGetPackages\" />
</packageSources>
</configuration>
In future I plan to make this a NuGet package. I use this in the blog now, for example to track how long translations take
var translationTask = tasks.FirstOrDefault(t => t.TaskId == taskId);
if (translationTask == null) return TypedResults.BadRequest("Task not found");
await umamiClient.Send(new UmamiPayload(){ Name = "Get Translation"}, new UmamiEventData(){{"timetaken", translationTask.TotalMilliseconds}, {"language",translationTask.Language}});