Glean

public class Glean

Undocumented

  • 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())

    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.

  • 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 setUploadEnabled(_ enabled: Bool)

    Parameters

    enabled

    When true, enable metric collection.

  • Get whether or not Glean is allowed to record and upload data.

    Caution: the result is only correct if Glean is already initialized.

    THIS METHOD IS DEPRECATED. Applications should not rely on Glean’s internal state. Upload enabled status should be tracked by the application and communicated to Glean if it changes.

    Declaration

    Swift

    @available(*, deprecated, message: "Upload enabled should be tracked by the application and communicated to Glean if it changes")
    public func getUploadEnabled() -> Bool
  • 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 wheter 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) -> RecordedExperimentData?

    Parameters

    experimentId

    The id of the experiment to look for.

    Return Value

    RecordedExperimentData if the experiment is active and reported in pings, 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.

  • 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>=<paramter 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 requred 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.

    Returns true if a ping by this name is in the ping registry.

    Declaration

    Swift

    public func testHasPingType(_ pingName: String) -> Bool
  • 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