#88 Umami.Net: impossible to specify unique_id / DistinctId / Id by Shaddix · Pull Request #90 · scottgal/mostlylucidweb

Shaddix · 2026-03-13T08:14:50Z

Copilot

Pull request overview

This PR addresses issue #88 by adding support for passing an Umami distinct/unique identifier through the .NET client so users can be consistently identified across sessions.

Changes:

Adds a new distinctId parameter to Identify/IdentifyAndDecode flows and forwards it into UmamiPayload.
Introduces a new payload property (Id) and ensures PayloadService propagates it during payload population.
Updates a background-sender test call site to use a named argument due to the new parameter position.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
Umami.Net/UmamiClient.cs	Adds `distinctId` support to identify APIs and forwards it into the payload.
Umami.Net/UmamiBackgroundSender.cs	Adds `distinctId` support for background identify/session identify enqueueing.
Umami.Net/PayloadService.cs	Propagates the new payload identifier property when populating payloads.
Umami.Net/Models/UmamiPayload.cs	Adds a new payload property (`Id`) intended to represent the distinct/unique identifier.
Umami.Net.Test/UmamiBackgroundSender_Tests.cs	Adjusts a call site to account for the updated method signature.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-20T17:01:39Z

        if (payload.SessionId != null)
            newPayload.SessionId = payload.SessionId;

+        if (payload.Id != null)
+            newPayload.Id = payload.Id;

        newPayload.UserAgent = payload.UserAgent ?? DefaultUserAgent;



PayloadService.PopulateFromPayload now propagates payload.Id, but there’s no test coverage validating that this propagation works end-to-end (i.e., a provided distinct/unique id survives population and is sent). Consider adding a test that sets UmamiPayload.Id (or the renamed property) and verifies it is present in the final request JSON.

Copilot · 2026-03-20T17:01:39Z

    public async Task<HttpResponseMessage> Identify(string? email = null, string? username = null,
-        string? sessionId = null, string? userId = null, UmamiEventData? eventData = null)
+        string? sessionId = null, string? userId = null, string? distinctId = null, UmamiEventData? eventData = null)
    {


Adding the new optional parameter distinctId before eventData is a source/binary breaking change for any callers using positional arguments (e.g., Identify(..., eventData) will no longer compile). To maintain backward compatibility, keep the existing parameter order and add an overload (or move distinctId to the end) so existing positional call sites remain valid.

Copilot · 2026-03-20T17:01:39Z

+        string? distinctId = null,
+        UmamiEventData? eventData = null)


IdentifyAndDecode(string sessionId, ...) now inserts distinctId before eventData, which breaks positional callers that previously passed eventData as the next argument. Consider preserving the original signature and introducing a new overload that includes distinctId, or move distinctId to the end to avoid a breaking API change.

Suggested change

string? distinctId = null,

UmamiEventData? eventData = null)

UmamiEventData? eventData = null,

string? distinctId = null)

Copilot · 2026-03-20T17:01:40Z

+        string? sessionId = null, string? userId = null, string? distinctId = null, UmamiEventData? eventData = null,
        bool useDefaultUserAgent = false)


The new distinctId optional parameter is inserted before eventData, which is a breaking change for callers that pass eventData positionally (it will now try to bind to distinctId). Prefer keeping the existing parameter order and adding an overload (or placing distinctId at the end) to avoid breaking consumers.

Suggested change

string? sessionId = null, string? userId = null, string? distinctId = null, UmamiEventData? eventData = null,

bool useDefaultUserAgent = false)

string? sessionId = null, string? userId = null, UmamiEventData? eventData = null,

bool useDefaultUserAgent = false, string? distinctId = null)

Copilot · 2026-03-20T17:01:40Z

+    public async Task IdentifySession(string sessionId, string? distinctId = null, UmamiEventData? eventData = null,
        bool useDefaultUserAgent = false)
    {


IdentifySession adds distinctId as the second parameter, which breaks existing positional calls like IdentifySession(sessionId, eventData) (the second argument no longer matches). To avoid a breaking change, keep the original signature and add an overload accepting distinctId, or move distinctId to the end after eventData/useDefaultUserAgent.

Suggested change

public async Task IdentifySession(string sessionId, string? distinctId = null, UmamiEventData? eventData = null,

bool useDefaultUserAgent = false)

{

public Task IdentifySession(string sessionId, UmamiEventData? eventData = null,

bool useDefaultUserAgent = false)

{

// Preserve backward-compatible signature and forward to the extended overload

return IdentifySession(sessionId, null, eventData, useDefaultUserAgent);

}

public async Task IdentifySession(string sessionId, string? distinctId, UmamiEventData? eventData = null,

bool useDefaultUserAgent = false)

{

Copilot · 2026-03-20T17:01:40Z

    public string? SessionId { get; set; }
+
+    public string? Id { get; set; }



UmamiPayload.Id is very generic and doesn’t communicate that it represents Umami’s distinct/unique identifier (issue #88). Consider renaming this to something explicit like DistinctId/UniqueId and mapping it to the expected JSON field name via [JsonPropertyName("id")] (or the exact key Umami expects), so the public API is self-describing without relying on the global naming policy.

Copilot · 2026-03-20T17:01:41Z

        var payload = new UmamiPayload
        {
            SessionId = sessionId,
+            Id = distinctId,
            Data = emailData
        };


New behavior: distinctId is now forwarded into the payload (Id = distinctId), but there are no assertions in the test suite that this value is actually serialized/sent when provided. Add/extend tests (client and/or background sender) to pass a non-null distinctId and assert it appears in the outgoing payload, so regressions are caught.

scottgal

Thanks for this PR @Shaddix — the feature is needed and the implementation is clean. A few items to address before merging:

Required Changes

Add [JsonPropertyName("id")] to UmamiPayload.Id (UmamiPayload.cs)
While LowerCaseNamingPolicy produces the correct "id" today, other properties (e.g. IpAddress → [JsonPropertyName("ip")]) use explicit attributes. Please add one for consistency and safety:
```
[JsonPropertyName("id")]
public string? Id { get; set; }
```
Add distinctId to UmamiClient.IdentifySession (UmamiClient.cs:201)
UmamiBackgroundSender.IdentifySession has the new distinctId parameter, but UmamiClient.IdentifySession does not — this is an inconsistency in the public API surface.

Suggestions (optional)

Add a test that verifies distinctId flows through to the serialized payload's id field
Consider length validation — Umami docs state the id field has a 50-character limit
The Track/TrackPageView methods don't expose distinctId as a convenience parameter (users can set Id on a raw UmamiPayload). This is fine for now but worth considering in a follow-up.

Overall this is a well-scoped, clean change — just needs the consistency fixes above. 👍

Shaddix · 2026-04-02T02:27:27Z

everything is done here, could you please check @scottgal ?

Shaddix · 2026-04-17T04:11:13Z

It'd be great if you approve or comment on what needs to be changed :)

Aero9999 · 2026-05-14T11:22:56Z

+1 would be great to get this merged in.

scottgal · 2026-05-14T11:33:16Z

Thanks all, merged. I need to do a bigger pass / (if anone fancies it) on the new playback features too. I don't currently have time to maintain this.

scottgal · 2026-05-14T11:35:42Z

Will be in Umami.net 1.0.1

Aero9999 · 2026-05-14T11:36:42Z

Thanks Scott. I've just started using Umami so alas my knowledge of replays isnt there yet!

looking forward to 1.0.1 👍

Aero9999 · 2026-05-14T11:38:44Z

(looks like the publish fell over though)

scottgal · 2026-05-14T11:40:35Z

Just fixed it, will be around shortly :)

Shaddix added 2 commits March 13, 2026 13:11

scottgal#88 Umami.Net: impossible to specify unique_id / DistinctId / Id

bf64947

scottgal#88

fix tests

cfd611f

scottgal requested a review from Copilot March 20, 2026 16:57

Copilot started reviewing on behalf of scottgal March 20, 2026 16:57 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

scottgal requested changes Mar 20, 2026

View reviewed changes

fix PR comments

b0a1990

scottgal merged commit fabea63 into scottgal:main May 14, 2026

		string? sessionId = null, string? userId = null, string? distinctId = null, UmamiEventData? eventData = null,
		bool useDefaultUserAgent = false)

		public string? SessionId { get; set; }

		public string? Id { get; set; }

Conversation

Shaddix commented Mar 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

scottgal left a comment

Choose a reason for hiding this comment

Required Changes

Suggestions (optional)

Uh oh!

Shaddix commented Apr 2, 2026

Uh oh!

Shaddix commented Apr 17, 2026

Uh oh!

Aero9999 commented May 14, 2026

Uh oh!

scottgal commented May 14, 2026

Uh oh!

scottgal commented May 14, 2026

Uh oh!

Aero9999 commented May 14, 2026

Uh oh!

Aero9999 commented May 14, 2026

Uh oh!

scottgal commented May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants