feat(onboarding): Org-level onboarding experiment events

api/app/settings/common.py

@@ -1303,6 +1303,9 @@
 FLAGSMITH_ON_FLAGSMITH_SERVER_API_URL = env(
     "FLAGSMITH_ON_FLAGSMITH_SERVER_API_URL", default=FLAGSMITH_ON_FLAGSMITH_API_URL
 )
+FLAGSMITH_ON_FLAGSMITH_SERVER_EVENTS_API_URL = env(
+    "FLAGSMITH_ON_FLAGSMITH_SERVER_EVENTS_API_URL", default=None
+)
 
 FLAGSMITH_ON_FLAGSMITH_FEATURE_EXPORT_ENVIRONMENT_ID = env.int(
     "FLAGSMITH_ON_FLAGSMITH_FEATURE_EXPORT_ENVIRONMENT_ID",

api/environments/onboarding/services.py

@@ -1,8 +1,11 @@
 import structlog
 from django.utils import timezone
+from openfeature.evaluation_context import EvaluationContext
+from openfeature.track import TrackingEventDetails
 
 from app_analytics.types import KnownSDK
 from environments.models import Environment
+from integrations.flagsmith.client import get_openfeature_client
 
 logger = structlog.get_logger("onboarding")
 
@@ -29,4 +32,14 @@ def record_environment_first_evaluation(
 
     Environment.write_environment_documents(environment_id=environment.id)
 
+    get_openfeature_client().track(
+        "environment.first_evaluated",
+        evaluation_context=EvaluationContext(
+            targeting_key=environment.project.organisation.openfeature_evaluation_context.targeting_key,
+        ),
+        tracking_event_details=TrackingEventDetails(
+            attributes={"sdk_label": sdk_label},
+        ),
+    )
+
     log.info("environment.first_evaluated")

api/integrations/flagsmith/client.py

@@ -18,8 +18,10 @@
 import openfeature.api as openfeature_api
 from django.conf import settings
 from flagsmith import Flagsmith
+from flagsmith.analytics import EventProcessorConfig
 from flagsmith.offline_handlers import LocalFileHandler
 from openfeature.client import OpenFeatureClient
+from openfeature_flagsmith.hooks import FlagsmithExposureHook
 from openfeature_flagsmith.provider import FlagsmithProvider
 
 from integrations.flagsmith.exceptions import FlagsmithIntegrationError
@@ -47,6 +49,7 @@ def initialise_provider(
     flagsmith_client = Flagsmith(**kwargs)
     provider = FlagsmithProvider(client=flagsmith_client)
     openfeature_api.set_provider(provider, domain=domain)
+    openfeature_api.add_hooks([FlagsmithExposureHook(provider)])
 
 
 def get_provider_kwargs() -> dict[str, typing.Any]:
@@ -61,11 +64,17 @@ def get_provider_kwargs() -> dict[str, typing.Any]:
         settings.FLAGSMITH_ON_FLAGSMITH_SERVER_KEY
         and settings.FLAGSMITH_ON_FLAGSMITH_SERVER_API_URL
     ):
-        return {
+        kwargs = {
             "environment_key": settings.FLAGSMITH_ON_FLAGSMITH_SERVER_KEY,
             "api_url": settings.FLAGSMITH_ON_FLAGSMITH_SERVER_API_URL,
             **common_kwargs,
         }
+        if events_api_url := settings.FLAGSMITH_ON_FLAGSMITH_SERVER_EVENTS_API_URL:
+            kwargs["enable_events"] = True
+            kwargs["event_processor_config"] = EventProcessorConfig(
+                events_api_url=events_api_url,
+            )
+        return kwargs
 
     raise FlagsmithIntegrationError(
         "Must either use offline mode, or provide "

api/organisations/serializers.py

@@ -11,6 +11,7 @@
     get_subscription_data_from_hosted_page,
 )
 from organisations.invites.models import Invite
+from organisations.services import OnboardingVariant, get_onboarding_variant
 from users.models import FFAdminUser, UserPermissionGroup
 
 from .models import (
@@ -40,6 +41,7 @@ def get_has_active_billing_periods(self, obj):  # type: ignore[no-untyped-def]
 class OrganisationSerializerFull(serializers.ModelSerializer):  # type: ignore[type-arg]
     subscription = SubscriptionSerializer(required=False)
     role = serializers.SerializerMethodField()
+    onboarding_variant = serializers.SerializerMethodField()
 
     class Meta:
         model = Organisation
@@ -56,6 +58,7 @@ class Meta:
             "block_access_to_admin",
             "restrict_project_create_to_admin",
             "force_2fa",
+            "onboarding_variant",
         )
         read_only_fields = (
             "id",
@@ -72,6 +75,10 @@ def get_role(self, instance):  # type: ignore[no-untyped-def]
             user = self.context["request"].user
             return user.get_organisation_role(instance)
 
+    @extend_schema_field({"type": "string", "enum": ["control", "single_page"]})
+    def get_onboarding_variant(self, instance: Organisation) -> OnboardingVariant:
+        return get_onboarding_variant(instance)
+
 
 class OrganisationSerializerBasic(serializers.ModelSerializer):  # type: ignore[type-arg]
     class Meta:

api/organisations/services.py

@@ -0,0 +1,17 @@
+import typing
+
+from integrations.flagsmith.client import get_openfeature_client
+from organisations.models import Organisation
+
+OnboardingVariant = typing.Literal["control", "single_page"]
+
+
+def get_onboarding_variant(organisation: Organisation) -> OnboardingVariant:
+    details = get_openfeature_client().get_boolean_details(
+        "onboarding_quickstart_flow",
+        default_value=False,
+        evaluation_context=organisation.openfeature_evaluation_context,
+    )
+    if not details.value or details.variant == "control":
+        return "control"
+    return "single_page"

api/pyproject.toml

@@ -67,9 +67,9 @@ dependencies = [
     "pydantic>=2.12.0,<3.0.0",
     "pydantic-collections>=0.6.0,<0.7.0",
     "pyngo>=2.4.1,<2.5.0",
-    "flagsmith>=5.3.0,<6.0.0",
+    "flagsmith>=6.2.0,<7.0.0",
     "openfeature-sdk>=0.9.0,<0.10.0",
-    "openfeature-provider-flagsmith>=0.2.0",
+    "openfeature-provider-flagsmith>=1.0.0,<2.0.0",
     "python-gnupg>=0.5.1,<0.6.0",
     "django-redis>=5.4.0,<6.0.0",
     "pygithub>=2.8,<2.9.0",
@@ -244,10 +244,10 @@ override-dependencies = [
     "executing==2.2.1",
     "fancycompleter==0.9.1",
     "filelock==3.20.3",
-    "flagsmith==5.3.0",
+    "flagsmith==6.2.0",
     # flagsmith-common version is set via the [project] dependency spec which
     # also carries the extras; an override here would strip the extras.
-    "flagsmith-flag-engine==10.1.0",
+    "flagsmith-flag-engine==10.2.0",
     "freezegun==1.5.5",
     "genson==1.2.2",
     "google-api-core==2.29.0",
@@ -294,7 +294,7 @@ override-dependencies = [
     "nodeenv==1.9.1",
     "oauth2client==4.1.3",
     "oauthlib==3.2.2",
-    "openfeature-provider-flagsmith==0.2.0",
+    "openfeature-provider-flagsmith==1.0.0",
     "openfeature-sdk==0.9.0",
     "opentelemetry-api==1.40.0",
     "opentelemetry-exporter-otlp-proto-common==1.40.0",

api/tests/unit/environments/onboarding/test_unit_environments_onboarding_services.py

@@ -0,0 +1,60 @@
+from unittest.mock import MagicMock, Mock
+
+import pytest
+from django.utils import timezone
+from pytest_mock import MockerFixture
+
+from environments.models import Environment
+from environments.onboarding.services import record_environment_first_evaluation
+
+
+@pytest.fixture(autouse=True)
+def write_environment_documents(mocker: MockerFixture) -> Mock:
+    return mocker.patch.object(Environment, "write_environment_documents")
+
+
+@pytest.fixture()
+def mock_openfeature_client(mocker: MockerFixture) -> MagicMock:
+    mock_client: MagicMock = mocker.MagicMock()
+    mocker.patch(
+        "environments.onboarding.services.get_openfeature_client",
+        return_value=mock_client,
+    )
+    return mock_client
+
+
+def test_record_environment_first_evaluation__first_evaluation__tracks_conversion_event(
+    environment: Environment,
+    mock_openfeature_client: MagicMock,
+) -> None:
+    # Given
+    organisation_id = environment.project.organisation_id
+
+    # When
+    record_environment_first_evaluation(environment, "flagsmith-python-sdk")
+
+    # Then
+    mock_openfeature_client.track.assert_called_once()
+    call_args = mock_openfeature_client.track.call_args
+    assert call_args.args == ("environment.first_evaluated",)
+    assert (
+        call_args.kwargs["evaluation_context"].targeting_key == f"org.{organisation_id}"
+    )
+    assert call_args.kwargs["tracking_event_details"].attributes == {
+        "sdk_label": "flagsmith-python-sdk",
+    }
+
+
+def test_record_environment_first_evaluation__already_evaluated__does_not_track(
+    environment: Environment,
+    mock_openfeature_client: MagicMock,
+) -> None:
+    # Given
+    environment.first_evaluated_at = timezone.now()
+    environment.save(update_fields=["first_evaluated_at"])
+
+    # When
+    record_environment_first_evaluation(environment, "flagsmith-python-sdk")
+
+    # Then
+    mock_openfeature_client.track.assert_not_called()

api/tests/unit/integrations/flagsmith/test_unit_flagsmith_client.py

@@ -2,6 +2,7 @@
 
 import openfeature.api as openfeature_api
 import pytest
+from flagsmith.analytics import EventProcessorConfig
 from flagsmith.offline_handlers import LocalFileHandler
 from openfeature.provider.in_memory_provider import InMemoryProvider
 from openfeature.provider.metadata import Metadata
@@ -155,11 +156,22 @@ def test_initialise_provider__offline_mode_disabled__initialises_with_server_key
     settings.FLAGSMITH_ON_FLAGSMITH_SERVER_API_URL = api_url
     settings.FLAGSMITH_ON_FLAGSMITH_SERVER_OFFLINE_MODE = False
 
-    mock_flagsmith_class = mocker.patch("integrations.flagsmith.client.Flagsmith")
+    mock_flagsmith_class = mocker.patch(
+        "integrations.flagsmith.client.Flagsmith",
+        autospec=True,
+    )
     mock_provider_class = mocker.patch(
-        "integrations.flagsmith.client.FlagsmithProvider"
+        "integrations.flagsmith.client.FlagsmithProvider",
+        autospec=True,
+    )
+    mock_exposure_hook_class = mocker.patch(
+        "integrations.flagsmith.client.FlagsmithExposureHook",
+        autospec=True,
+    )
+    mock_openfeature_api = mocker.patch(
+        "integrations.flagsmith.client.openfeature_api",
+        autospec=True,
     )
-    mock_openfeature_api = mocker.patch("integrations.flagsmith.client.openfeature_api")
 
     # When
     initialise_provider(**get_provider_kwargs())
@@ -181,6 +193,11 @@ def test_initialise_provider__offline_mode_disabled__initialises_with_server_key
         domain=DEFAULT_OPENFEATURE_DOMAIN,
     )
 
+    mock_exposure_hook_class.assert_called_once_with(mock_provider_class.return_value)
+    mock_openfeature_api.add_hooks.assert_called_once_with(
+        [mock_exposure_hook_class.return_value]
+    )
+
     mock_local_file_handler_class.assert_called_once_with(ENVIRONMENT_JSON_PATH)
 
 
@@ -193,11 +210,18 @@ def test_initialise_provider__offline_mode_enabled__initialises_with_offline_han
     # Given
     settings.FLAGSMITH_ON_FLAGSMITH_SERVER_OFFLINE_MODE = True
 
-    mock_flagsmith_class = mocker.patch("integrations.flagsmith.client.Flagsmith")
+    mock_flagsmith_class = mocker.patch(
+        "integrations.flagsmith.client.Flagsmith",
+        autospec=True,
+    )
     mock_provider_class = mocker.patch(
-        "integrations.flagsmith.client.FlagsmithProvider"
+        "integrations.flagsmith.client.FlagsmithProvider",
+        autospec=True,
+    )
+    mock_openfeature_api = mocker.patch(
+        "integrations.flagsmith.client.openfeature_api",
+        autospec=True,
     )
-    mock_openfeature_api = mocker.patch("integrations.flagsmith.client.openfeature_api")
 
     # When
     initialise_provider(**get_provider_kwargs())
@@ -230,3 +254,60 @@ def test_get_provider_kwargs__missing_server_key__raises_error(
     # When / Then
     with pytest.raises(FlagsmithIntegrationError):
         get_provider_kwargs()
+
+
+def test_get_provider_kwargs__events_api_url_set__enables_events(
+    settings: SettingsWrapper, mock_local_file_handler_class: MagicMock
+) -> None:
+    # Given
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_OFFLINE_MODE = False
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_KEY = "ser.some-key"
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_API_URL = "https://my.flagsmith.api/api/v1/"
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_EVENTS_API_URL = (
+        "https://events.my.flagsmith.api/"
+    )
+
+    # When
+    kwargs = get_provider_kwargs()
+
+    # Then
+    assert kwargs["enable_events"] is True
+    assert kwargs["event_processor_config"] == EventProcessorConfig(
+        events_api_url="https://events.my.flagsmith.api/",
+    )
+
+
+def test_get_provider_kwargs__no_events_api_url__events_not_enabled(
+    settings: SettingsWrapper, mock_local_file_handler_class: MagicMock
+) -> None:
+    # Given
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_OFFLINE_MODE = False
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_KEY = "ser.some-key"
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_API_URL = "https://my.flagsmith.api/api/v1/"
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_EVENTS_API_URL = None
+
+    # When
+    kwargs = get_provider_kwargs()
+
+    # Then
+    assert "enable_events" not in kwargs
+    assert "event_processor_config" not in kwargs
+
+
+def test_get_provider_kwargs__offline_mode_with_events_api_url__events_not_enabled(
+    settings: SettingsWrapper, mock_local_file_handler_class: MagicMock
+) -> None:
+    # Given
+    # The SDK never initialises events in offline mode; don't pretend otherwise.
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_OFFLINE_MODE = True
+    settings.FLAGSMITH_ON_FLAGSMITH_SERVER_EVENTS_API_URL = (
+        "https://events.my.flagsmith.api/"
+    )
+
+    # When
+    kwargs = get_provider_kwargs()
+
+    # Then
+    assert kwargs["offline_mode"] is True
+    assert "enable_events" not in kwargs
+    assert "event_processor_config" not in kwargs

api/tests/unit/organisations/test_unit_organisations_serializers.py

@@ -2,7 +2,29 @@
 from pytest_mock import MockerFixture
 
 from organisations.models import Organisation
-from organisations.serializers import UpdateSubscriptionSerializer
+from organisations.serializers import (
+    OrganisationSerializerFull,
+    UpdateSubscriptionSerializer,
+)
+
+
+def test_organisation_serializer_full__onboarding_org__serialises_onboarding_variant(
+    organisation: Organisation,
+    mocker: MockerFixture,
+) -> None:
+    # Given
+    get_onboarding_variant_mock = mocker.patch(
+        "organisations.serializers.get_onboarding_variant",
+        return_value="single_page",
+        autospec=True,
+    )
+
+    # When
+    data = OrganisationSerializerFull(instance=organisation).data
+
+    # Then
+    assert data["onboarding_variant"] == "single_page"
+    get_onboarding_variant_mock.assert_called_once_with(organisation)
 
 
 def test_update_subscription_serializer__create__updates_subscription(