feat: collect and track utms at signup (#5630)

Co-authored-by: Matthew Elwell <matthew.elwell@flagsmith.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

api/integrations/lead_tracking/hubspot/client.py

@@ -57,8 +57,12 @@ def get_contact(self, user: "FFAdminUser") -> None | dict[str, Any]:
         return results[0]  # type: ignore[no-any-return]
 
     def create_lead_form(
-        self, user: "FFAdminUser", hubspot_cookie: str | None = None
+        self,
+        user: "FFAdminUser",
+        hubspot_cookie: str | None = None,
+        utm_data: dict[str, str] | None = None,
     ) -> dict[str, Any]:
+        utm_data = utm_data or {}
         logger.info(
             f"Creating Hubspot lead form for user {user.email} with hubspot cookie {hubspot_cookie}"
         )
@@ -72,6 +76,10 @@ def create_lead_form(
             {"objectTypeId": "0-1", "name": "lastname", "value": user.last_name},
         ]
 
+        fields.extend(
+            {"objectTypeId": "0-1", "name": k, "value": v} for k, v in utm_data.items()
+        )
+
         context = {}
         if hubspot_cookie:
             context = {

api/integrations/lead_tracking/hubspot/lead_tracker.py

@@ -67,8 +67,15 @@ def update_company_active_subscription(
 
     def create_user_hubspot_contact(self, user: FFAdminUser) -> str | None:
         tracker = HubspotTracker.objects.filter(user=user).first()
-        tracker_cookie = tracker.hubspot_cookie if tracker else None
-        self.client.create_lead_form(user=user, hubspot_cookie=tracker_cookie)
+        create_lead_form_kwargs: dict[str, Any] = {"user": user}
+        if tracker:
+            create_lead_form_kwargs.update(
+                {
+                    "hubspot_cookie": tracker.hubspot_cookie,
+                    "utm_data": tracker.utm_data,
+                }
+            )
+        self.client.create_lead_form(**create_lead_form_kwargs)
 
         # Create lead form creates a contact asynchronously in hubspot but does not return the contact id
         # We need to get the contact id separately and retry 3 times

api/integrations/lead_tracking/hubspot/services.py

@@ -8,19 +8,29 @@
     HUBSPOT_COOKIE_NAME,
 )
 from users.models import FFAdminUser, HubspotTracker
+from users.serializers import UTMDataSerializer
 
 logger = logging.getLogger(__name__)
 
 
-def register_hubspot_tracker(request: Request, user: FFAdminUser | None = None) -> None:
+def register_hubspot_tracker(
+    request: Request,
+    user: FFAdminUser | None = None,
+) -> None:
     hubspot_cookie = request.data.get(HUBSPOT_COOKIE_NAME)
+    raw_utm_data = request.data.get("utm_data")
     track_user = user if user else request.user
-    if not hubspot_cookie:
-        logger.info(f"Request did not included Hubspot data for user {track_user.id}")
+
+    serializer = UTMDataSerializer(data=raw_utm_data)
+    utm_data = serializer.validated_data if serializer.is_valid() else None
+
+    if not (hubspot_cookie or utm_data):
+        logger.info(f"Request did not include Hubspot data for user {track_user.id}")
         return
 
     if (
-        HubspotTracker.objects.filter(hubspot_cookie=hubspot_cookie)  # type: ignore[misc]
+        hubspot_cookie
+        and HubspotTracker.objects.filter(hubspot_cookie=hubspot_cookie)  # type: ignore[misc]
         .exclude(user=track_user)
         .exists()
     ):
@@ -34,6 +44,7 @@ def register_hubspot_tracker(request: Request, user: FFAdminUser | None = None)
         user=track_user,
         defaults={
             "hubspot_cookie": hubspot_cookie,
+            "utm_data": utm_data,
         },
     )
     logger.info(

api/tests/unit/integrations/lead_tracking/hubspot/test_unit_hubspot_client.py

@@ -60,9 +60,17 @@ def test_create_lead_form(
         status=status.HTTP_200_OK,
         json={"inlineMessage": "Thanks for submitting the form."},
     )
-
+    utms_data = {
+        "utm_source": "test_source",
+        "utm_medium": "test_medium",
+        "utm_campaign": "test_campaign",
+        "utm_content": "test_content",
+        "utm_term": "test_term",
+    }
     # When
-    response = hubspot_client.create_lead_form(staff_user, hubspot_cookie_body)
+    response = hubspot_client.create_lead_form(
+        staff_user, hubspot_cookie_body, utms_data
+    )
 
     # Then
     assert len(responses.calls) == 1
@@ -85,6 +93,29 @@ def test_create_lead_form(
         "value": staff_user.last_name,
     } in fields
 
+    # Test UTMs
+    assert {
+        "objectTypeId": "0-1",
+        "name": "utm_source",
+        "value": "test_source",
+    } in fields
+    assert {
+        "objectTypeId": "0-1",
+        "name": "utm_medium",
+        "value": "test_medium",
+    } in fields
+    assert {
+        "objectTypeId": "0-1",
+        "name": "utm_campaign",
+        "value": "test_campaign",
+    } in fields
+    assert {
+        "objectTypeId": "0-1",
+        "name": "utm_content",
+        "value": "test_content",
+    } in fields
+    assert {"objectTypeId": "0-1", "name": "utm_term", "value": "test_term"} in fields
+
     context = request_body.get("context", {})
     assert context == expected_context
 

api/tests/unit/integrations/lead_tracking/hubspot/test_unit_hubspot_lead_tracking.py

@@ -189,7 +189,7 @@ def test_create_organisation_lead_creates_contact_when_not_found(
     assert hubspot_lead.hubspot_id == HUBSPOT_USER_ID
 
     assert mock_client.get_contact.call_count == 2
-    mock_client.create_lead_form.assert_called_once_with(user=user, hubspot_cookie=None)
+    mock_client.create_lead_form.assert_called_once_with(user=user)
     mock_client.create_company.assert_called_once_with(
         name=organisation.name,
         active_subscription="free",
@@ -234,7 +234,7 @@ def test_create_organisation_lead_creates_contact_for_existing_org(
     assert HubspotLead.objects.filter(user=user, hubspot_id=HUBSPOT_USER_ID).exists()
     mock_client.create_company.assert_not_called()
     assert mock_client.get_contact.call_count == 2
-    mock_client.create_lead_form.assert_called_once_with(user=user, hubspot_cookie=None)
+    mock_client.create_lead_form.assert_called_once_with(user=user)
     mock_client.associate_contact_to_company.assert_called_once_with(
         contact_id=HUBSPOT_USER_ID,
         company_id=HUBSPOT_COMPANY_ID,

api/users/migrations/0042_add_utm_data_json_field.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.22 on 2025-07-02 13:35
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("users", "0041_add_onboarding_field"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="hubspottracker",
+            name="utm_data",
+            field=models.JSONField(blank=True, default=None, null=True),
+        ),
+    ]

api/users/migrations/0043_make_hubspot_cookie_optional.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.22 on 2025-06-19 14:28
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("users", "0042_add_utm_data_json_field"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="hubspottracker",
+            name="hubspot_cookie",
+            field=models.CharField(blank=True, max_length=100, null=True, unique=True),
+        ),
+    ]

api/users/models.py

@@ -18,6 +18,7 @@
 from django_lifecycle.conditions import (  # type: ignore[import-untyped]
     WhenFieldHasChanged,
 )
+from pydantic import BaseModel
 
 from integrations.lead_tracking.hubspot.tasks import (
     create_hubspot_contact_for_user,
@@ -44,6 +45,15 @@
 from users.constants import DEFAULT_DELETE_ORPHAN_ORGANISATIONS_VALUE
 from users.exceptions import InvalidInviteError
 
+
+class UTMDataModel(BaseModel):
+    utm_source: typing.Optional[str] = None
+    utm_medium: typing.Optional[str] = None
+    utm_campaign: typing.Optional[str] = None
+    utm_term: typing.Optional[str] = None
+    utm_content: typing.Optional[str] = None
+
+
 if typing.TYPE_CHECKING:
     from environments.models import Environment
     from organisations.invites.models import (
@@ -463,12 +473,29 @@ class HubspotLead(models.Model):
     updated_at = models.DateTimeField(auto_now=True)
 
 
+class HubspotTrackerUTMData(typing.TypedDict, total=False):
+    utm_source: str
+    utm_medium: str
+    utm_campaign: str
+    utm_term: str
+    utm_content: str
+
+
 class HubspotTracker(models.Model):
     user = models.OneToOneField(
         FFAdminUser,
         related_name="hubspot_tracker",
         on_delete=models.CASCADE,
     )
-    hubspot_cookie = models.CharField(unique=True, max_length=100, null=False)
+    hubspot_cookie = models.CharField(
+        unique=True,
+        max_length=100,
+        null=True,
+        blank=True,
+    )
+    utm_data: HubspotTrackerUTMData = models.JSONField(
+        default=None, blank=True, null=True
+    )  # type: ignore[assignment]
+
     created_at = models.DateTimeField(auto_now_add=True)
     updated_at = models.DateTimeField(auto_now=True)

api/users/serializers.py

@@ -224,3 +224,11 @@ class Meta(DjoserUserSerializer.Meta):  # type: ignore[misc]
 
 class ListUsersQuerySerializer(serializers.Serializer):  # type: ignore[type-arg]
     exclude_current = serializers.BooleanField(default=False)
+
+
+class UTMDataSerializer(serializers.Serializer[None]):
+    utm_source = serializers.CharField(required=False)
+    utm_medium = serializers.CharField(required=False)
+    utm_campaign = serializers.CharField(required=False)
+    utm_term = serializers.CharField(required=False)
+    utm_content = serializers.CharField(required=False)

frontend/common/types/requests.ts

@@ -22,6 +22,7 @@ import {
   StageTrigger,
   StageActionType,
 } from './responses'
+import { UtmsType } from './utms'
 
 export type PagedRequest<T> = T & {
   page?: number
@@ -70,6 +71,7 @@ export type RegisterRequest = {
   superuser?: boolean
   organisation_name?: string
   marketing_consent_given?: boolean
+  utm_data?: UtmsType
 }
 
 export interface StageActionRequest {