update Nimbus SDK to add and use RecordedContext

Author: jeddai

CHANGELOG.md

@@ -15,6 +15,10 @@
 
 # v126.0 (_2024-04-15_)
 
+### Nimbus SDK ⛅️🔬🔭
+
+- Added `RecordedContext` extendable trait and define its usage in the Kotlin/Swift files ([#6207](https://github.com/mozilla/application-services/pull/6207)).
+
 [Full Changelog](https://github.com/mozilla/application-services/compare/v125.0...v126.0)
 
 # v125.0 (_2024-03-18_)

components/nimbus/android/src/main/java/org/mozilla/experiments/nimbus/Nimbus.kt

@@ -41,6 +41,7 @@ import org.mozilla.experiments.nimbus.internal.MetricsHandler
 import org.mozilla.experiments.nimbus.internal.NimbusClient
 import org.mozilla.experiments.nimbus.internal.NimbusClientInterface
 import org.mozilla.experiments.nimbus.internal.NimbusException
+import org.mozilla.experiments.nimbus.internal.RecordedContext
 import java.io.File
 import java.io.IOException
 
@@ -70,6 +71,7 @@ open class Nimbus(
     deviceInfo: NimbusDeviceInfo,
     private val observer: NimbusInterface.Observer? = null,
     delegate: NimbusDelegate,
+    private val recordedContext: RecordedContext? = null,
 ) : NimbusInterface {
     // An I/O scope is used for reading or writing from the Nimbus's RKV database.
     private val dbScope: CoroutineScope = delegate.dbScope
@@ -166,6 +168,7 @@ open class Nimbus(
 
         nimbusClient = NimbusClient(
             experimentContext,
+            recordedContext,
             coenrollingFeatureIds,
             dataDir.path,
             remoteSettingsConfig,
@@ -492,6 +495,7 @@ open class Nimbus(
                         ),
                     )
                 }
+
                 EnrollmentChangeEventType.DISQUALIFICATION -> {
                     NimbusEvents.disqualification.record(
                         NimbusEvents.DisqualificationExtra(
@@ -500,6 +504,7 @@ open class Nimbus(
                         ),
                     )
                 }
+
                 EnrollmentChangeEventType.UNENROLLMENT -> {
                     NimbusEvents.unenrollment.record(
                         NimbusEvents.UnenrollmentExtra(
@@ -508,6 +513,7 @@ open class Nimbus(
                         ),
                     )
                 }
+
                 EnrollmentChangeEventType.ENROLL_FAILED -> {
                     NimbusEvents.enrollFailed.record(
                         NimbusEvents.EnrollFailedExtra(
@@ -517,6 +523,7 @@ open class Nimbus(
                         ),
                     )
                 }
+
                 EnrollmentChangeEventType.UNENROLL_FAILED -> {
                     NimbusEvents.unenrollFailed.record(
                         NimbusEvents.UnenrollFailedExtra(
@@ -534,20 +541,26 @@ open class Nimbus(
     // If the experiment slug is known, then use that to look up the enrollment.
     @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
     @AnyThread
-    internal fun recordExposureOnThisThread(featureId: String, experimentSlug: String? = null) = withCatchAll("recordFeatureExposure") {
-        nimbusClient.recordFeatureExposure(featureId, experimentSlug)
-    }
+    internal fun recordExposureOnThisThread(featureId: String, experimentSlug: String? = null) =
+        withCatchAll("recordFeatureExposure") {
+            nimbusClient.recordFeatureExposure(featureId, experimentSlug)
+        }
 
     // The malformed feature event is recorded by app developers, if the configuration is
     // _semantically_ invalid or malformed.
     @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
     @AnyThread
-    internal fun recordMalformedConfigurationOnThisThread(featureId: String, partId: String) = withCatchAll("recordMalformedConfiguration") {
-        nimbusClient.recordMalformedFeatureConfig(featureId, partId)
-    }
+    internal fun recordMalformedConfigurationOnThisThread(featureId: String, partId: String) =
+        withCatchAll("recordMalformedConfiguration") {
+            nimbusClient.recordMalformedFeatureConfig(featureId, partId)
+        }
 
     @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
-    internal fun buildExperimentContext(context: Context, appInfo: NimbusAppInfo, deviceInfo: NimbusDeviceInfo): AppContext {
+    internal fun buildExperimentContext(
+        context: Context,
+        appInfo: NimbusAppInfo,
+        deviceInfo: NimbusDeviceInfo,
+    ): AppContext {
         val packageInfo: PackageInfo? = try {
             if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
                 context.packageManager.getPackageInfo(context.packageName, PackageManager.PackageInfoFlags.of(0))

components/nimbus/android/src/main/java/org/mozilla/experiments/nimbus/NimbusBuilder.kt

@@ -10,6 +10,7 @@ import android.net.Uri
 import androidx.annotation.RawRes
 import kotlinx.coroutines.runBlocking
 import org.mozilla.experiments.nimbus.internal.FeatureManifestInterface
+import org.mozilla.experiments.nimbus.internal.RecordedContext
 
 private const val TIME_OUT_LOADING_EXPERIMENT_FROM_DISK_MS = 200L
 
@@ -89,6 +90,11 @@ abstract class AbstractNimbusBuilder<T : NimbusInterface>(val context: Context)
      */
     var sharedPreferences: SharedPreferences? = null
 
+    /**
+     * Additional targeting context that will be recorded to Glean.
+     */
+    var recordedContext: RecordedContext? = null
+
     /**
      * Build a [Nimbus] singleton for the given [NimbusAppInfo]. Instances built with this method
      * have been initialized, and are ready for use by the app.
@@ -222,6 +228,7 @@ class DefaultNimbusBuilder(context: Context) : AbstractNimbusBuilder<NimbusInter
             deviceInfo = createDeviceInfo(),
             delegate = createDelegate(),
             observer = createObserver(),
+            recordedContext = recordedContext,
         )
 
     override fun newNimbusDisabled() = NullNimbus(context)

components/nimbus/android/src/test/java/org/mozilla/experiments/nimbus/NimbusTests.kt

@@ -19,6 +19,7 @@ import mozilla.telemetry.glean.config.Configuration
 import mozilla.telemetry.glean.net.HttpStatus
 import mozilla.telemetry.glean.net.PingUploader
 import mozilla.telemetry.glean.testing.GleanTestRule
+import org.json.JSONObject
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNotNull
@@ -35,6 +36,8 @@ import org.mozilla.experiments.nimbus.GleanMetrics.NimbusEvents
 import org.mozilla.experiments.nimbus.GleanMetrics.NimbusHealth
 import org.mozilla.experiments.nimbus.internal.EnrollmentChangeEvent
 import org.mozilla.experiments.nimbus.internal.EnrollmentChangeEventType
+import org.mozilla.experiments.nimbus.internal.JsonObject
+import org.mozilla.experiments.nimbus.internal.RecordedContext
 import org.robolectric.RobolectricTestRunner
 import java.util.Calendar
 import java.util.concurrent.Executors
@@ -63,23 +66,28 @@ class NimbusTests {
         errorReporter = { message, e -> Log.e("NimbusTest", message, e) },
     )
 
-    private val nimbus = createNimbus()
+    private var nimbus = createNimbus()
 
-    private fun createNimbus(coenrollingFeatureIds: List<String> = listOf()) = Nimbus(
+    private fun createNimbus(
+        coenrollingFeatureIds: List<String> = listOf(),
+        recordedContext: RecordedContext? = null,
+    ) = Nimbus(
         context = context,
         appInfo = appInfo,
         coenrollingFeatureIds = coenrollingFeatureIds,
         server = null,
         deviceInfo = deviceInfo,
         observer = null,
         delegate = nimbusDelegate,
+        recordedContext = recordedContext,
     )
 
     @get:Rule
     val gleanRule = GleanTestRule(context)
 
     @Before
     fun setupGlean() {
+        nimbus = createNimbus()
         val buildInfo = BuildInfo(versionCode = "0.0.1", versionName = "0.0.1", buildDate = Calendar.getInstance())
 
         // Glean needs to be initialized for the experiments API to accept enrollment events, so we
@@ -191,9 +199,15 @@ class NimbusTests {
         )
     }
 
-    @Ignore // until the activation event is enabled by default.
     @Test
     fun `getFeatureVariables records activation telemetry`() {
+        Glean.applyServerKnobsConfig(
+            """{
+                "metrics_enabled": {
+                    "nimbus_events.activation": true
+                }
+            }""",
+        )
         // Load the experiment in nimbus so and optIn so that it will be active. This is necessary
         // because recordExposure checks for active experiments before recording.
         nimbus.setUpTestExperiments(packageName, appInfo)
@@ -719,6 +733,36 @@ class NimbusTests {
         isReadyEvents = NimbusEvents.isReady.testGetValue()!!
         assertEquals("Event count must match", isReadyEvents.count(), 3)
     }
+
+    @Test
+    fun `Nimbus records context if it's passed in`() {
+        class TestRecordedContext : RecordedContext {
+            var recordCount = 0
+
+            override fun record() {
+                recordCount++
+            }
+
+            override fun toJson(): JsonObject {
+                val contextToRecord = JSONObject()
+                contextToRecord.put("enabled", true)
+                return contextToRecord
+            }
+        }
+        val context = TestRecordedContext()
+        val nimbus = createNimbus(recordedContext = context)
+
+        suspend fun getString(): String {
+            return testExperimentsJsonString(appInfo, packageName)
+        }
+
+        val job = nimbus.applyLocalExperiments(::getString)
+        runBlocking {
+            job.join()
+        }
+
+        assertEquals(context.recordCount, 1)
+    }
 }
 
 // Mocking utilities, from mozilla.components.support.test

components/nimbus/examples/experiment.rs

@@ -230,6 +230,7 @@ fn main() -> Result<()> {
     let nimbus_client = NimbusClient::new(
         context.clone(),
         Default::default(),
+        Default::default(),
         db_path,
         Some(config),
         Box::new(NoopMetricsHandler),

components/nimbus/ios/Nimbus/NimbusBuilder.swift

@@ -164,6 +164,20 @@ public class NimbusBuilder {
 
     var commandLineArgs: [String]?
 
+    /**
+     * An optional RecordedContext object.
+     *
+     * When provided, its JSON contents will be added to the Nimbus targeting context, and its value will be published
+     * to Glean.
+     */
+    @discardableResult
+    public func with(recordedContext: RecordedContext?) -> Self {
+        self.recordedContext = recordedContext
+        return self
+    }
+
+    var recordedContext: RecordedContext?
+
     // swiftlint:disable function_body_length
     /**
      * Build a [Nimbus] singleton for the given [NimbusAppSettings]. Instances built with this method
@@ -252,7 +266,8 @@ public class NimbusBuilder {
                           dbPath: dbFilePath,
                           resourceBundles: resourceBundles,
                           userDefaults: userDefaults,
-                          errorReporter: errorReporter)
+                          errorReporter: errorReporter,
+                          recordedContext: recordedContext)
     }
 
     func newNimbusDisabled() -> NimbusInterface {

components/nimbus/ios/Nimbus/NimbusCreate.swift

@@ -84,7 +84,8 @@ public extension Nimbus {
         resourceBundles: [Bundle] = [Bundle.main],
         enabled: Bool = true,
         userDefaults: UserDefaults? = nil,
-        errorReporter: @escaping NimbusErrorReporter = defaultErrorReporter
+        errorReporter: @escaping NimbusErrorReporter = defaultErrorReporter,
+        recordedContext: RecordedContext? = nil
     ) throws -> NimbusInterface {
         guard enabled else {
             return NimbusDisabled.shared
@@ -99,6 +100,7 @@ public extension Nimbus {
         }
         let nimbusClient = try NimbusClient(
             appCtx: context,
+            recordedContext: recordedContext,
             coenrollingFeatureIds: coenrollingFeatureIds,
             dbpath: dbPath,
             remoteSettingsConfig: remoteSettings,

components/nimbus/src/json.rs

@@ -5,6 +5,9 @@
 use serde_json::{Map, Value};
 use std::collections::HashMap;
 
+#[cfg(feature = "stateful")]
+pub type JsonObject = Map<String, Value>;
+
 /// Replace any instance of [from] with [to] in any string within the [serde_json::Value].
 ///
 /// This recursively descends into the object, looking at string values and keys.

components/nimbus/src/nimbus.udl

@@ -106,10 +106,21 @@ enum NimbusError {
     "ParseIntError", "TransformParameterError", "ClientError", "UniFFICallbackError",
 };
 
+[Custom]
+typedef string JsonObject;
+
+[Trait, WithForeign]
+interface RecordedContext {
+    JsonObject to_json();
+
+    void record();
+};
+
 interface NimbusClient {
     [Throws=NimbusError]
     constructor(
         AppContext app_ctx,
+        RecordedContext? recorded_context,
         sequence<string> coenrolling_feature_ids,
         string dbpath,
         RemoteSettingsConfig? remote_settings_config,
@@ -274,9 +285,6 @@ interface NimbusClient {
     void dump_state_to_log();
 };
 
-[Custom]
-typedef string JsonObject;
-
 interface NimbusTargetingHelper {
     // Execute the given jexl expression and evaluate against the existing targeting parameters and context passed to
     // the helper at construction.

components/nimbus/src/stateful/evaluator.rs

@@ -5,7 +5,9 @@
 use crate::{
     enrollment::{EnrollmentStatus, ExperimentEnrollment},
     evaluator::split_locale,
+    json::JsonObject,
     stateful::matcher::AppContext,
+    targeting::RecordedContext,
 };
 use chrono::{DateTime, Utc};
 use serde_derive::*;
@@ -17,6 +19,8 @@ pub struct TargetingAttributes {
     pub app_context: AppContext,
     pub language: Option<String>,
     pub region: Option<String>,
+    #[serde(flatten)]
+    pub recorded_context: Option<JsonObject>,
     pub is_already_enrolled: bool,
     pub days_since_install: Option<i32>,
     pub days_since_update: Option<i32>,
@@ -28,7 +32,6 @@ pub struct TargetingAttributes {
     pub nimbus_id: Option<String>,
 }
 
-#[cfg(feature = "stateful")]
 impl From<AppContext> for TargetingAttributes {
     fn from(app_context: AppContext) -> Self {
         let (language, region) = app_context
@@ -47,6 +50,10 @@ impl From<AppContext> for TargetingAttributes {
 }
 
 impl TargetingAttributes {
+    pub(crate) fn set_recorded_context(&mut self, recorded_context: &dyn RecordedContext) {
+        self.recorded_context = Some(recorded_context.to_json());
+    }
+
     pub(crate) fn update_time_to_now(
         &mut self,
         now: DateTime<Utc>,

components/nimbus/src/stateful/matcher.rs

@@ -35,7 +35,6 @@ use serde_json::{Map, Value};
 /// - `installation_date`: The date the application installed the app
 /// - `home_directory`: The application's home directory
 /// - `custom_targeting_attributes`: Contains attributes specific to the application, derived by the application
-#[cfg(feature = "stateful")]
 #[derive(Deserialize, Serialize, Debug, Clone, Default)]
 pub struct AppContext {
     pub app_name: String,