Using the experiments API
The Glean SDK supports tagging all its pings with experiments annotations. The annotations are useful to report that experiments were active at the time the measurement were collected. The annotations are reported in the optional experiments
entry in the ping_info
section of all the Glean SDK pings.
Important: the experiment annotations set through this API are not persisted by the Glean SDK. The application or consuming library is responsible for setting the relevant experiment annotations at each run.
API
// Annotate Glean pings with experiments data.
Glean.setExperimentActive(
experimentId = "blue-button-effective",
branch = "branch-with-blue-button",
extra: mapOf(
"buttonLabel" to "test"
)
)
// After the experiment terminates, the annotation
// can be removed.
Glean.setExperimentInactive("blue-button-effective")
Important: Experiment IDs and branches don't need to be pre-defined in the Glean SDK registry files. Please also note that the
extra
map is a non-nested arbitraryString
toString
map. It also has limits on the size of the keys and values defined below.
There are test APIs available too:
// Was the experiment annotated in Glean pings?
assertTrue(Glean.testIsExperimentActive("blue-button-effective"))
// Was the correct branch reported?
assertEquals(
"branch-with-blue-button", Glean.testGetExperimentData("blue-button-effective")?.branch
)
// Annotate Glean pings with experiments data.
Glean.shared.setExperimentActive(
experimentId: "blue-button-effective",
branch: "branch-with-blue-button",
extra: ["buttonLabel": "test"]
)
// After the experiment terminates, the annotation
// can be removed.
Glean.shared.setExperimentInactive(experimentId: "blue-button-effective")
Important: Experiment IDs and branch don't need to be pre-defined in the Glean SDK registry files. Please also note that the
extra
is a non-nestedDictionary
of type[String: String]
.
There are test APIs available too:
// Was the experiment annotated in Glean pings?
XCTAssertTrue(Glean.shared.testIsExperimentActive(experimentId: "blue-button-effective"))
// Was the correct branch reported?
XCTAssertEqual(
"branch-with-blue-button",
Glean.testGetExperimentData(experimentId: "blue-button-effective")?.branch
)
from glean import Glean
# Annotate Glean pings with experiments data.
Glean.set_experiment_active(
experiment_id="blue-button-effective",
branch="branch-with-blue-button",
extra={
"buttonLabel": "test"
}
)
# After the experiment terminates, the annotation
# can be removed.
Glean.set_experiment_inactive("blue-button-effective")
Important: Experiment IDs and branch don't need to be pre-defined in the Glean SDK registry files. Please also note that the
extra
dict is non-nested arbitrarystr
tostr
mapping.
There are test APIs available too:
from glean import Glean
# Was the experiment annotated in Glean pings?
assert Glean.test_is_experiment_active("blue-button-effective")
# Was the correct branch reported?
assert (
"branch-with-blue-button" ==
Glean.test_get_experiment_data("blue-button-effective").branch
)
// Annotate Glean pings with experiments data.
GleanInstance.SetExperimentActive(
experimentId: "blue-button-effective",
branch: "branch-with-blue-button",
extra: new Dictionary<string, string>() {
{ "buttonLabel", "test"}
}
);
// After the experiment terminates, the annotation
// can be removed.
GleanInstance.SetExperimentInactive("blue-button-effective");
Important: Experiment IDs and branches don't need to be pre-defined in the Glean SDK registry files. Please also note that the
extra
map is a non-nested arbitrarystring
tostring
dictionary. It also has limits on the size of the keys and values defined below.
There are test APIs available too:
// Was the experiment annotated in Glean pings?
Assert.True(GleanInstance.TestIsExperimentActive("blue-button-effective"));
// Was the correct branch reported?
Assert.Equal(
"branch-with-blue-button", GleanInstance.TestGetExperimentData("blue-button-effective").Branch
);
Limits
experimentId
,branch
, and the keys and values of the 'extra' field are fixed at a maximum length of 100 bytes. Longer strings used as ids, keys, or values are truncated to their respective maximum length. (Specifically, this is measured in the number of bytes when the string is encoded in UTF-8.)extra
map is limited to 20 entries. If passed a map which contains more elements than this, it is truncated to 20 elements. WARNING Which items are truncated is nondeterministic due to the unordered nature of maps and what's left may not necessarily be the first elements added.
NOTE: Any truncation that occurs when recording to the Experiments API will result in an invalid_value
error being recorded. See Error Reporting for more information about this type of error.