Merge pull request #259 from spoo-me/feat/click-dimensions

feat(analytics): add device and UTM click dimensions

Author: Zingzy

routes/redirect_routes.py

@@ -246,6 +246,11 @@ async def redirect_url(
             cf_city=cf_city,
             resolved_country=resolved_country,
             geo_matched=geo_matched,
+            # Raw capture only — ClickEvent sanitises and bounds these
+            # structurally, same as the password-hash strip.
+            utm_source=request.query_params.get("utm_source"),
+            utm_medium=request.query_params.get("utm_medium"),
+            utm_campaign=request.query_params.get("utm_campaign"),
             redirect_ms=int((time.perf_counter() - start_time) * 1000),
         )
         try:

schemas/dto/requests/_descriptions.py

@@ -41,10 +41,15 @@
     "- `time` — group by time buckets (day/week/month, auto-selected based on range)\n"
     "- `browser` — group by browser name (e.g., Chrome, Firefox, Safari)\n"
     "- `os` — group by operating system (e.g., Windows, macOS, Linux)\n"
+    "- `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n"
     "- `country` — group by country\n"
     "- `city` — group by city\n"
     "- `referrer` — group by referrer URL\n"
-    "- `short_code` — group by URL alias (only with `scope=all`)\n\n"
+    "- `short_code` — group by URL alias (only with `scope=all`)\n"
+    "- `utm_source` — group by the `utm_source` tag on the short link "
+    "(untagged clicks appear as `(none)`)\n"
+    "- `utm_medium` — group by the `utm_medium` tag\n"
+    "- `utm_campaign` — group by the `utm_campaign` tag\n\n"
     "Multiple dimensions can be combined: `time,browser` returns time series "
     "broken down by browser."
 )
@@ -69,11 +74,14 @@
     "**Available filter dimensions:**\n\n"
     "- `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge)\n"
     "- `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android)\n"
+    "- `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`)\n"
     "- `country` — Filter by country name (e.g., United States, Canada, Germany)\n"
     "- `city` — Filter by city name (e.g., New York, London, Mumbai)\n"
     "- `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com)\n"
     "- `short_code` — Filter by URL alias (e.g., mylink, promo2024) — "
-    "**not allowed** with `scope=anon`\n\n"
+    "**not allowed** with `scope=anon`\n"
+    "- `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; "
+    "`(none)` matches untagged clicks\n\n"
     "**Value format:** Array of strings for each dimension.\n\n"
     "**Important:** Filter values are case-sensitive. Use exact capitalization "
     "as stored in the database.\n\n"
@@ -133,6 +141,24 @@
     "**Note:** Both `filters` JSON and individual parameters can be combined."
 )
 
+STATS_DEVICE_DESC = (
+    "**Method 2: Individual Filter Parameter**\n\n"
+    "Comma-separated device types. Alternative to using the `filters` JSON "
+    "parameter.\n\n"
+    "**Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also "
+    "matches clicks recorded before device tracking existed.\n\n"
+    "**Note:** Both `filters` JSON and individual parameters can be combined."
+)
+
+STATS_UTM_DESC = (
+    "**Method 2: Individual Filter Parameter**\n\n"
+    "Comma-separated campaign tag values. Alternative to using the `filters` "
+    "JSON parameter.\n\n"
+    "**Important:** Values are case-sensitive. `(none)` matches clicks with "
+    "no tag.\n\n"
+    "**Note:** Both `filters` JSON and individual parameters can be combined."
+)
+
 
 # ── ListUrlsQuery ────────────────────────────────────────────────────────────
 

schemas/dto/requests/stats.py

@@ -25,6 +25,7 @@
     STATS_BROWSER_DESC,
     STATS_CITY_DESC,
     STATS_COUNTRY_DESC,
+    STATS_DEVICE_DESC,
     STATS_END_DATE_DESC,
     STATS_FILTERS_DESC,
     STATS_GROUP_BY_DESC,
@@ -35,6 +36,7 @@
     STATS_SHORT_CODE_DESC,
     STATS_START_DATE_DESC,
     STATS_TIMEZONE_DESC,
+    STATS_UTM_DESC,
 )
 from schemas.enums.stats import (
     ALLOWED_EXPORT_FORMATS,
@@ -128,6 +130,12 @@ class StatsQuery(RequestBase):
         description=STATS_OS_DESC,
         examples=["Windows,macOS"],
     )
+    device: str | None = Field(
+        default=None,
+        max_length=200,
+        description=STATS_DEVICE_DESC,
+        examples=["mobile,desktop"],
+    )
     country: str | None = Field(
         default=None,
         max_length=1000,
@@ -146,6 +154,24 @@ class StatsQuery(RequestBase):
         description=STATS_REFERRER_DESC,
         examples=["https://google.com,https://twitter.com"],
     )
+    utm_source: str | None = Field(
+        default=None,
+        max_length=1000,
+        description=STATS_UTM_DESC,
+        examples=["newsletter,twitter"],
+    )
+    utm_medium: str | None = Field(
+        default=None,
+        max_length=1000,
+        description=STATS_UTM_DESC,
+        examples=["email,social"],
+    )
+    utm_campaign: str | None = Field(
+        default=None,
+        max_length=1000,
+        description=STATS_UTM_DESC,
+        examples=["summer-launch"],
+    )
 
     # --- Parsed/validated results (private — not exposed as query params) ---
     _parsed_group_by: list[str] = PrivateAttr(default_factory=list)
@@ -201,7 +227,18 @@ def _parse_multi_value_fields(self) -> StatsQuery:
                         parsed_filters[key] = _parse_comma_separated(value)
 
         # Individual dimension filter params
-        for dim in ("browser", "os", "country", "city", "referrer", "short_code"):
+        for dim in (
+            "browser",
+            "os",
+            "device",
+            "country",
+            "city",
+            "referrer",
+            "short_code",
+            "utm_source",
+            "utm_medium",
+            "utm_campaign",
+        ):
             raw = getattr(self, dim, None)
             if raw:
                 # short_code filter is blocked when scope=anon (bypass prevention)

schemas/dto/responses/public_stats.py

@@ -49,6 +49,6 @@ class PublicStatsResponse(ResponseBase):
             "The modern stats wire shape (same as GET /api/v1/stats): "
             "summary, metrics keyed '{metric}_by_{dimension}', time_range, "
             "time_bucket_info, computed_metrics. v1 links carry a "
-            "'clicks_by_bots' dimension and no 'city'; v2 the reverse."
+            "'clicks_by_bots' dimension and no 'city'/'device'; v2 the reverse."
         ),
     )

schemas/enums/stats.py

@@ -24,10 +24,14 @@ class StatsDimension(str, Enum):
     TIME = "time"
     BROWSER = "browser"
     OS = "os"
+    DEVICE = "device"
     COUNTRY = "country"
     CITY = "city"
     REFERRER = "referrer"
     SHORT_CODE = "short_code"
+    UTM_SOURCE = "utm_source"
+    UTM_MEDIUM = "utm_medium"
+    UTM_CAMPAIGN = "utm_campaign"
 
 
 class StatsMetric(str, Enum):
@@ -53,10 +57,14 @@ class ExportFormat(str, Enum):
     {
         StatsDimension.BROWSER,
         StatsDimension.OS,
+        StatsDimension.DEVICE,
         StatsDimension.COUNTRY,
         StatsDimension.CITY,
         StatsDimension.REFERRER,
         StatsDimension.SHORT_CODE,
+        StatsDimension.UTM_SOURCE,
+        StatsDimension.UTM_MEDIUM,
+        StatsDimension.UTM_CAMPAIGN,
     }
 )
 ALLOWED_EXPORT_FORMATS = frozenset(ExportFormat)

schemas/models/click.py

@@ -51,3 +51,12 @@ class ClickDoc(MongoBaseModel):
     redirect_ms: int
     referrer: str | None = None  # sanitised referrer domain, nullable
     bot_name: str | None = None  # nullable
+    # Nullable like meta.domain: clicks recorded before these fields existed
+    # keep their original shape forever (time-series buckets can't be
+    # backfilled). device is "mobile" | "tablet" | "desktop" | "unknown".
+    device: str | None = None
+    # UTM tags captured from the short link's own query string, sanitised
+    # at event construction (services.click.events).
+    utm_source: str | None = None
+    utm_medium: str | None = None
+    utm_campaign: str | None = None

services/click/consumers/stats.py

@@ -46,6 +46,9 @@ async def consume(self, payload: Any) -> None:
                 user_agent=event.user_agent,
                 referrer=event.referrer,
                 cf_city=event.cf_city,
+                utm_source=event.utm_source,
+                utm_medium=event.utm_medium,
+                utm_campaign=event.utm_campaign,
             )
         except ValidationError:
             log.info(

services/click/events.py

@@ -20,6 +20,7 @@
 
 from __future__ import annotations
 
+import re
 from datetime import datetime, timezone
 from typing import Any
 
@@ -37,6 +38,12 @@
 EVENT_TYPE_CLICK = "click.recorded"
 _WIRE_VERSION = "1"
 
+# UTM values are visitor-controlled query-string input — bound their size so
+# a crafted link can't bloat stream payloads, and strip control characters
+# before they reach Mongo/logs.
+_UTM_MAX_LEN = 100
+_CONTROL_CHARS_RE = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
 
 class ClickEvent(BaseModel):
     """Immutable fact: a redirect was served and its click should be tracked."""
@@ -59,9 +66,24 @@ class ClickEvent(BaseModel):
     # Defaults keep pre-existing stream payloads decodable.
     resolved_country: str | None = None
     geo_matched: bool = False
+    # Campaign tags from the short link's query string. Defaults keep
+    # pre-existing stream payloads decodable.
+    utm_source: str | None = None
+    utm_medium: str | None = None
+    utm_campaign: str | None = None
     redirect_ms: int
     enqueued_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
 
+    @field_validator("utm_source", "utm_medium", "utm_campaign")
+    @classmethod
+    def _sanitize_utm(cls, value: str | None) -> str | None:
+        """Enforced structurally (like the password-hash strip below) so
+        every producer inherits the bound instead of remembering it."""
+        if value is None:
+            return None
+        value = _CONTROL_CHARS_RE.sub("", value).strip()[:_UTM_MAX_LEN]
+        return value or None
+
     @field_validator("url")
     @classmethod
     def _strip_password_hash(cls, url: UrlCacheData) -> UrlCacheData:

services/click/handlers.py

@@ -12,6 +12,7 @@
 
 import tldextract
 from bson import ObjectId
+from ua_parser import Result
 from ua_parser import parse as ua_parse
 
 from errors import ForbiddenError, ValidationError
@@ -31,6 +32,40 @@
 
 _tld_extractor = tldextract.TLDExtract(cache_dir=None)
 
+_DESKTOP_OS_FAMILIES = frozenset(
+    {"Windows", "Mac OS X", "Linux", "Chrome OS", "Ubuntu", "Fedora"}
+)
+_MOBILE_OS_FAMILIES = frozenset({"Windows Phone", "KaiOS", "Firefox OS"})
+
+
+def classify_device(ua: Result, user_agent: str) -> str:
+    """Bucket a parsed UA into ``mobile`` / ``tablet`` / ``desktop`` / ``unknown``.
+
+    ua-parser reports device family/brand/model but deliberately no type;
+    this is the token fallback chain Matomo's DeviceDetector itself uses
+    when its model regexes don't decide. The signals survive Chrome's UA
+    reduction (the "Mobile" token and OS family are preserved; the device
+    model is frozen to "K"). Known, accepted limit: iPad Safari sends a
+    Mac UA since iPadOS 13 and lands in ``desktop`` — indistinguishable
+    server-side, counted the same way by GA4/Adobe/Matomo.
+    """
+    os_family = ua.os.family if ua.os else ""
+    device_family = ua.device.family if ua.device else ""
+    if os_family == "iOS":
+        return "tablet" if "iPad" in device_family else "mobile"
+    if os_family == "Android":
+        # Chrome on Android carries "Mobile" on phones only; tablets omit it
+        return "mobile" if "Mobile" in user_agent else "tablet"
+    if os_family in _DESKTOP_OS_FAMILIES:
+        return "desktop"
+    if os_family in _MOBILE_OS_FAMILIES:
+        return "mobile"
+    if device_family == "Generic Smartphone":
+        return "mobile"
+    if device_family == "Generic Tablet":
+        return "tablet"
+    return "unknown"
+
 
 class V2ClickHandler:
     """Records a click for a v2 URL in the time-series clicks collection."""
@@ -85,6 +120,7 @@ async def handle(self, context: ClickContext) -> None:
 
         os_name = ua.os.family
         browser = ua.user_agent.family
+        device = classify_device(ua, user_agent)
 
         # Referrer sanitization (v2 style)
         sanitized_referrer: str | None = None
@@ -139,6 +175,10 @@ async def handle(self, context: ClickContext) -> None:
             redirect_ms=redirect_ms,
             referrer=sanitized_referrer,
             bot_name=bot_name,
+            device=device,
+            utm_source=context.utm_source,
+            utm_medium=context.utm_medium,
+            utm_campaign=context.utm_campaign,
         )
 
         await self._click_repo.insert(click_doc.to_mongo())
@@ -153,6 +193,7 @@ async def handle(self, context: ClickContext) -> None:
                 city=city or "Unknown",
                 browser=browser,
                 os=os_name,
+                device=device,
                 is_bot=is_bot,
                 bot_name=bot_name,
                 referrer_domain=sanitized_referrer,

services/click/protocol.py

@@ -21,6 +21,11 @@ class ClickContext:
     referrer: str | None
     is_emoji: bool = False
     cf_city: str | None = None
+    # Campaign tags from the short link's query string (already sanitised
+    # by ClickEvent). Recorded by the v2 handler; legacy ignores them.
+    utm_source: str | None = None
+    utm_medium: str | None = None
+    utm_campaign: str | None = None
 
 
 class ClickHandler(Protocol):