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.constants import ENVIRONMENT_JSON_PATH
@@ -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/migrations/0060_add_targeting_key.py

@@ -0,0 +1,23 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("organisations", "0059_use_no_ssrf_url_field"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="organisation",
+            name="targeting_key",
+            field=models.CharField(
+                blank=True,
+                help_text=(
+                    "Flagsmith-on-Flagsmith targeting key. Immutable; org.<id> "
+                    "is used when unset."
+                ),
+                max_length=64,
+                null=True,
+            ),
+        ),
+    ]

api/organisations/models.py

@@ -90,6 +90,12 @@ class Organisation(LifecycleModelMixin, SoftDeleteExportableModel):  # type: ign
         default=False, help_text="Record feature analytics in InfluxDB"
     )
     force_2fa = models.BooleanField(default=False)
+    targeting_key = models.CharField(
+        max_length=64,
+        null=True,
+        blank=True,
+        help_text="Flagsmith-on-Flagsmith targeting key. Immutable; org.<id> is used when unset.",
+    )
 
     class Meta:
         ordering = ["id"]
@@ -134,7 +140,7 @@ def has_enterprise_subscription(self) -> bool:
     @property
     def openfeature_evaluation_context(self) -> EvaluationContext:
         return EvaluationContext(
-            targeting_key=f"org.{self.id}",
+            targeting_key=self.targeting_key or f"org.{self.id}",
             attributes={
                 "organisation.id": self.id,
                 "organisation.name": self.name,

api/organisations/serializers.py

@@ -56,6 +56,7 @@ class Meta:
             "block_access_to_admin",
             "restrict_project_create_to_admin",
             "force_2fa",
+            "targeting_key",
         )
         read_only_fields = (
             "id",
@@ -65,6 +66,19 @@ class Meta:
             "persist_trait_data",
             "block_access_to_admin",
         )
+        extra_kwargs = {
+            "targeting_key": {"write_only": True},
+        }
+
+    def update(
+        self,
+        instance: Organisation,
+        validated_data: dict[str, typing.Any],
+    ) -> Organisation:
+        # The targeting key pins the organisation's experiment bucketing;
+        # accepting it on update would make experiment arms mutable.
+        validated_data.pop("targeting_key", None)
+        return super().update(instance, validated_data)  # type: ignore[no-any-return]
 
     @extend_schema_field({"type": "string", "nullable": True})
     def get_role(self, instance):  # type: ignore[no-untyped-def]

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,77 @@
+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__org_targeting_key_set__tracks_with_stored_key(
+    environment: Environment,
+    mock_openfeature_client: MagicMock,
+) -> None:
+    # Given
+    organisation = environment.project.organisation
+    organisation.targeting_key = "a" * 32
+    organisation.save(update_fields=["targeting_key"])
+
+    # When
+    record_environment_first_evaluation(environment, "flagsmith-python-sdk")
+
+    # Then
+    call_args = mock_openfeature_client.track.call_args
+    assert call_args.kwargs["evaluation_context"].targeting_key == "a" * 32
+
+
+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