Glean

public class Glean

The main Glean API.

This is exposed through the global Glean.shared object.

  • The main Glean object.

    Glean.shared.initialize(uploadEnabled: true)

    Declaration

    Swift

    public static let shared: Glean

  • Initialize the Glean SDK.

    This should only be initialized once by the application, and not by libraries using the Glean SDK. A message is logged to error and no changes are made to the state if initialize is called a more than once.

    A LifecycleObserver will be added to submit pings when the application goes into the foreground and background.

    Declaration

    Swift

    public func initialize(uploadEnabled: Bool, configuration: Configuration = Configuration(), buildInfo: BuildInfo)

    Parameters

    uploadEnabled

    A Bool that enables or disables telemetry. If disabled, all persisted metrics, events and queued pings (except first_run_date) are cleared.
    configuration

    A Glean Configuration object with global settings.
    buildInfo

    A Glean BuildInfo object with build settings.

  • DEPRECATED Enable or disable Glean collection and upload.

    Metric collection is enabled by default.

    When uploading is disabled, metrics aren’t recorded at all and no data is uploaded.

    When disabling, all pending metrics, events and queued pings are cleared.

    When enabling, the core Glean metrics are recreated.

    DEPRECATION NOTICE: This API is deprecated. Use setCollectionEnabled instead.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `setCollectionEnabled` instead.")
public func setUploadEnabled(_ enabled: Bool)

    Parameters

    enabled

    When true, enable metric collection.

  • Enable or disable Glean collection and upload.

    Metric collection is enabled by default.

    When uploading is disabled, metrics aren’t recorded at all and no data is uploaded.

    When disabling, all pending metrics, events and queued pings are cleared.

    When enabling, the core Glean metrics are recreated.

    Declaration

    Swift

    public func setCollectionEnabled(_ enabled: Bool)

    Parameters

    enabled

    When true, enable metric collection.

  • Used to indicate that an experiment is running.

    Glean will add an experiment annotation that is sent with pings. This information is not persisted between runs.

    Declaration

    Swift

    public func setExperimentActive(_ experimentId: String, branch: String, extra: [String : String]?)

    Parameters

    experimentId

    The id of the active experiment (maximum 100 bytes).
    branch

    The branch of the experiment (maximum 100 bytes).
    extra

    Optional metadata to output with the ping.

  • Used to indicate that an experiment is no longer running.

    Declaration

    Swift

    public func setExperimentInactive(_ experimentId: String)

    Parameters

    experimentsId

    The id of the experiment to deactivate.

  • Tests whether an experiment is active, for testing purposes only.

    Declaration

    Swift

    public func testIsExperimentActive(_ experimentId: String) -> Bool

    Parameters

    experimentId

    The id of the experiment to look for.

    Return Value

    true if the experiment is active and reported in pings.

  • PUBLIC TEST ONLY FUNCTION.

    Get recorded experiment data for a given experimentId.

    Declaration

    Swift

    public func testGetExperimentData(_ experimentId: String) -> RecordedExperiment?

    Parameters

    experimentId

    The id of the experiment to look for.

    Return Value

    RecordedExperiment if the experiment is active and reported in pings, nil otherwise.

  • Dynamically set the experimentation identifier, as opposed to setting it through the configuration during initialization.

    Declaration

    Swift

    public func setExperimentationId(_ experimentationId: String)

    Parameters

    experimentationId

    The String identifier to set

  • PUBLIC TEST ONLY FUNCTION.

    Returns the stored experimentation id, for testing purposes only.

    Declaration

    Swift

    public func testGetExperimentationId() -> String?

    Return Value

    the ‘String’ experimentation id if set, and nil otherwise.

  • Register the pings generated from pings.yaml with the Glean SDK.

    Declaration

    Swift

    public func registerPings(_: Any)

    Parameters

    pings

    The Pings object generated for your library or application by the Glean SDK.

  • Set a tag to be applied to headers when uploading pings for debug view. This is only meant to be used internally by the GleanDebugActivity.

    Declaration

    Swift

    @discardableResult
public func setDebugViewTag(_ tag: String) -> Bool

    Parameters

    value

    The value of the tag, which must be a valid HTTP header value.

  • Set the log_pings debug option, when this option is true the pings that are successfully submitted get logged.

    Declaration

    Swift

    public func setLogPings(_ value: Bool)

    Parameters

    value

    The value of the option.

  • Set the source tags to be applied as headers when uploading pings.

    If any of the tags is invalid nothing will be set and this function will return false. If Glean is not initialized yet, tags will not be validated at this point.

    Declaration

    Swift

    public func setSourceTags(_ tags: [String]) -> Bool

    Parameters

    tags

    A list of tags, which must be valid HTTP header values.

  • EXPERIMENTAL: Register a listener to receive notification of event recordings

    Declaration

    Swift

    public func registerEventListener(tag: String, listener: GleanEventListener)

    Parameters

    tag

    String used to identify the listener when unregistering it
    listener

    Implements GleanEventListener protocol

  • EXPERIMENTAL: Unregister a listener to receive notification of event recordings

    Declaration

    Swift

    public func unregisterEventListener(tag: String)

    Parameters

    tag

    String used to identify the listener when it was registered

  • Set configuration to override metrics’ default enabled/disabled state, typically from a remote_settings experiment or rollout.

    Declaration

    Swift

    public func applyServerKnobsConfig(_ json: String)

    Parameters

    json

    Stringified JSON map of metric identifiers (category.name) to a boolean representing wether they are enabled

  • Shuts down Glean in an orderly fashion

    Declaration

    Swift

    public func shutdown()

  • When applications are launched using the custom URL scheme, this helper function will process the URL and parse the debug commands

    There are 3 available commands that you can use with the Glean SDK debug tools

    • logPings: If “true”, will cause pings that are submitted successfully to also be echoed to the device’s log
    • debugViewTag: This command expects a string to tag the pings with and redirects them to the Debug View
    • sendPing: This command expects a string name of a ping to force immediate collection and submission of.

    The structure of the custom URL uses the following format:

    <protocol>://glean?<command 1>=<parameter 1>&<command 2>=<parameter 2> ...

    Where:

    • <protocol>:// is the “Url Scheme” that has been added for the app and doesn’t matter to Glean.
    • glean is required for the Glean SDK to recognize the command is meant for it to process.
    • ? indicating the beginning of the query.
    • <command>=<parameter> are instances of the commands listed above separated by &.

    There are a few things to consider when creating the custom URL:

    • Invalid commands will trigger an error and be ignored.
    • Not all commands are required to be encoded in the URL, you can mix and match the commands that you need.
    • Special characters should be properly URL encoded and escaped since this needs to represent a valid URL.

    Declaration

    Swift

    public func handleCustomUrl(url: URL)

    Parameters

    url

    A URL object containing the Glean debug commands as query parameters

  • PUBLIC TEST ONLY FUNCTION.

    Enable test mode.

    This makes all asynchronous work synchronous so we can test the results of the API synchronously.

    Declaration

    Swift

    public func enableTestingMode()

  • PUBLIC TEST ONLY FUNCTION.

    Resets the Glean state and trigger init again.

    Declaration

    Swift

    public func resetGlean(configuration: Configuration = Configuration(),
                       clearStores: Bool,
                       uploadEnabled: Bool = true)

    Parameters

    configuration

    the Configuration to init Glean with
    clearStores

    if true, clear the contents of all stores
    uploadEnabled

    whether upload is enabled