Add opt-in Matomo cid visitor IDs

[stefan01]

Optionally send the visitor id as cid instead of _id

[Copilot]

Pull request overview

Adds an opt-in configuration to send the configured visitor ID using Matomo’s cid request parameter instead of _id, enabling explicit visitor matching behavior while preserving the existing default.

Changes:

• Introduces VisitorIdParameter (id vs cid) and exposes it on MatomoTracker / initialize(...).
• Updates request serialization (MatomoAction.toMap) to emit either _id or cid based on configuration.
• Adds tests, README documentation, and changelog entry for the new option (including validation for cid requiring 16 hex chars).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/src/matomo_test.dart	Adds initialization and validation tests for visitorIdParameter: cid.
test/src/matomo_action_test.dart	Ensures tracking payload uses cid instead of _id when configured; updates mocks accordingly.
test/src/dispatch_settings_test.dart	Updates mocks to stub visitorIdParameter for non-nullable getter use.
test/ressources/utils/get_initialized_mamoto_tracker.dart	Adds visitorIdParameter plumbing to test initializer helper.
README.md	Documents how/when to use Matomo cid and its constraints.
lib/src/visitor.dart	Defines the VisitorIdParameter enum and updates visitor ID docs.
lib/src/matomo.dart	Adds visitorIdParameter to tracker initialization and validates cid IDs as 16-hex.
lib/src/matomo_action.dart	Switches the outgoing visitor-id query key between _id and cid.
CHANGELOG.md	Adds an “Unreleased” entry for cid support.

---

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

[TesteurManiak]

@stefan01 thanks for the contribution, before reviewing it can you link the documentation from Matomo that says the cid can replace the _id? I'm also seeing in the documentation that using the uid parameter (which is already supported) is preferred to the cid:

cid — defines the visitor ID for this request. You must set this value to exactly a 16 character hexadecimal string (containing only characters 01234567890abcdefABCDEF). We recommended setting the User ID via uid rather than use this cid.

Source

[stefan01]

Thanks for raising this. The documentation does not explicitly use the wording that cid “replaces” _id, so my original description was too strong.

The Tracking API reference documents both parameters as visitor IDs:

• _id: the unique visitor ID
• cid: “defines the visitor ID for this request”

Matomo’s tracker implementation makes their relationship clearer: getVisitorId() first checks cid as the forced visitor ID and only falls back to _id if no forced ID was found. Thus, a request can supply cid instead of _id; both ultimately provide Matomo’s internal idvisitor, although cid has explicit/forced semantics.

I agree regarding uid, but it represents a different concept. uid identifies a known, normally authenticated user and can link that user’s activity, whereas _id/cid identify a visitor or device and can also be used for anonymous visitors. This PR is therefore not intended as an alternative to the existing uid support.

The change is opt-in: _id remains the package default, while callers with a specific need for Matomo’s forced cid behavior can select it. The PR also validates the documented 16-character hexadecimal requirement and mentions that uid remains preferred for authenticated user identity.

I’m happy to adjust the wording in the PR further so it says that cid is an opt-in forced visitor-ID parameter rather than implying Matomo generally recommends replacing _id with it.