You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
111 lines
4.8 KiB
Kotlin
111 lines
4.8 KiB
Kotlin
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
package org.mozilla.fenix.ext
|
|
|
|
import mozilla.components.service.nimbus.NimbusApi
|
|
import mozilla.components.support.base.log.logger.Logger
|
|
import org.mozilla.experiments.nimbus.Variables
|
|
import org.mozilla.fenix.experiments.FeatureId
|
|
|
|
/**
|
|
* Gets the branch name of an experiment acting on the feature given `featureId`, and transforms it
|
|
* with given closure.
|
|
*
|
|
* You are probably looking for `withVariables`.
|
|
*
|
|
* If we're enrolled in an experiment, the transform is passed the branch id/slug as a `String`.
|
|
*
|
|
* If we're not enrolled in the experiment, or the experiment is not valid then the transform
|
|
* is passed a `null`.
|
|
*/
|
|
fun <T> NimbusApi.withExperiment(featureId: FeatureId, transform: (String?) -> T): T {
|
|
return transform(withExperiment(featureId))
|
|
}
|
|
|
|
/**
|
|
* The synonym for [getExperimentBranch] to complement [withExperiment(String, (String?) -> T))].
|
|
*
|
|
* Short-hand for ` org.mozilla.experiments.nimbus.NimbusApi.getExperimentBranch`.
|
|
*/
|
|
@Suppress("TooGenericExceptionCaught")
|
|
fun NimbusApi.withExperiment(featureId: FeatureId) =
|
|
try {
|
|
getExperimentBranch(featureId.jsonName)
|
|
} catch (e: Throwable) {
|
|
Logger.error("Failed to getExperimentBranch(${featureId.jsonName})", e)
|
|
null
|
|
}
|
|
|
|
/**
|
|
* Get the variables needed to configure the feature given by `featureId`.
|
|
*
|
|
* @param featureId The feature id that identifies the feature under experiment.
|
|
*
|
|
* @param sendExposureEvent Passing `true` to this parameter will record the exposure event
|
|
* automatically if the client is enrolled in an experiment for the given [featureId].
|
|
* Passing `false` here indicates that the application will manually record the exposure
|
|
* event by calling the `sendExposureEvent` function at the time of the exposure to the
|
|
* feature.
|
|
*
|
|
* See [sendExposureEvent] for more information on manually recording the event.
|
|
*
|
|
* @return a [Variables] object used to configure the feature.
|
|
*/
|
|
fun NimbusApi.getVariables(featureId: FeatureId, sendExposureEvent: Boolean = true) =
|
|
getVariables(featureId.jsonName, sendExposureEvent)
|
|
|
|
/**
|
|
* A synonym for `getVariables(featureId, sendExposureEvent)`.
|
|
*
|
|
* This exists as a complement to the `withVariable(featureId, sendExposureEvent, transform)` method.
|
|
*
|
|
* @param featureId the id of the feature as it appears in `Experimenter`
|
|
* @param sendExposureEvent by default `true`. This logs an event that the user was exposed to an experiment
|
|
* involving this feature.
|
|
* @return a `Variables` object providing typed accessors to a remotely configured JSON object.
|
|
*/
|
|
fun NimbusApi.withVariables(featureId: FeatureId, sendExposureEvent: Boolean = true) =
|
|
getVariables(featureId, sendExposureEvent)
|
|
|
|
/**
|
|
* Get a `Variables` object for this feature and use that to configure the feature itself or a
|
|
* more type safe configuration object.
|
|
*
|
|
* @param featureId the id of the feature as it appears in `Experimenter`
|
|
* @param sendExposureEvent by default `true`. This logs an event that the user was exposed to an experiment
|
|
* involving this feature.
|
|
*/
|
|
fun <T> NimbusApi.withVariables(featureId: FeatureId, sendExposureEvent: Boolean = true, transform: (Variables) -> T) =
|
|
transform(getVariables(featureId, sendExposureEvent))
|
|
|
|
/**
|
|
* Records the `exposure` event in telemetry.
|
|
*
|
|
* This is a manual function to accomplish the same purpose as passing `true` as the
|
|
* `sendExposureEvent` property of the `getVariables` function. It is intended to be used
|
|
* when requesting feature variables must occur at a different time than the actual user's
|
|
* exposure to the feature within the app.
|
|
*
|
|
* - Examples:
|
|
* - If the `Variables` are needed at a different time than when the exposure to the feature
|
|
* actually happens, such as constructing a menu happening at a different time than the
|
|
* user seeing the menu.
|
|
* - If `getVariables` is required to be called multiple times for the same feature and it is
|
|
* desired to only record the exposure once, such as if `getVariables` were called
|
|
* with every keystroke.
|
|
*
|
|
* In the case where the use of this function is required, then the `getVariables` function
|
|
* should be called with `false` so that the exposure event is not recorded when the variables
|
|
* are fetched.
|
|
*
|
|
* This function is safe to call even when there is no active experiment for the feature. The SDK
|
|
* will ensure that an event is only recorded for active experiments.
|
|
*
|
|
* @param featureId string representing the id of the feature for which to record the exposure
|
|
* event.
|
|
*/
|
|
fun NimbusApi.recordExposureEvent(featureId: FeatureId) =
|
|
recordExposureEvent(featureId.jsonName)
|