From 8609ec31d079c64f699641ade22d8b91f132a350 Mon Sep 17 00:00:00 2001 From: Jan-Erik Rediger Date: Mon, 25 Nov 2024 15:59:25 +0100 Subject: [PATCH] start docs for collection-enabled [doc only] --- bin/build-rust-docs.sh | 1 + docs/user/SUMMARY.md | 2 +- docs/user/reference/general/index.md | 2 +- docs/user/reference/general/initializing.md | 2 +- ...tatus.md => toggling-collection-status.md} | 59 ++++++++++++------- .../adding-glean-to-your-project/index.md | 2 +- 6 files changed, 42 insertions(+), 26 deletions(-) rename docs/user/reference/general/{toggling-upload-status.md => toggling-collection-status.md} (55%) diff --git a/bin/build-rust-docs.sh b/bin/build-rust-docs.sh index 948b54c491..b4e9a3bfd3 100755 --- a/bin/build-rust-docs.sh +++ b/bin/build-rust-docs.sh @@ -49,6 +49,7 @@ echo '' > build/docs/book/user/general-api.html echo '' > build/docs/book/user/experiments-api.html +echo '' > build/docs/book/user/reference/general/toggling-upload-status.html # Metrics API mkdir -p build/docs/book/user/metrics/ echo '' > build/docs/book/user/metrics/boolean.html diff --git a/docs/user/SUMMARY.md b/docs/user/SUMMARY.md index 3627181f9b..d4595fedc7 100644 --- a/docs/user/SUMMARY.md +++ b/docs/user/SUMMARY.md @@ -57,7 +57,7 @@ - [Tags](reference/yaml/tags.md) - [General API](reference/general/index.md) - [Initializing](reference/general/initializing.md) - - [Toggling upload status](reference/general/toggling-upload-status.md) + - [Toggling collection status](reference/general/toggling-collection-status.md) - [Annotating experiments](reference/general/experiments-api.md) - [Registering custom pings](reference/general/register-custom-pings.md) - [Shut down](reference/general/shutdown.md) diff --git a/docs/user/reference/general/index.md b/docs/user/reference/general/index.md index 60f067cf8e..dc1fdb89ea 100644 --- a/docs/user/reference/general/index.md +++ b/docs/user/reference/general/index.md @@ -20,7 +20,7 @@ The Glean SDKs provide a general API that supports the following operations. See | Operation | Description | Notes | | --------- | ----------- | ----- | | `initialize` | Configure and initialize the Glean SDK. | [Initializing the Glean SDK](./initializing.md) | -| `setUploadEnabled` | Enable or disable Glean collection and upload. | [Toggling upload status](./toggling-upload-status.md) | +| `setCollectionEnabled` | Enable or disable Glean collection and upload. | [Toggling collection status](./toggling-collection-status.md) | | `registerPings` | Register custom pings generated from `pings.yaml`. | [Custom pings][custom-pings] | | `setExperimentActive` | Indicate that an experiment is running. | [Using the Experiments API][experiments-api] | | `setExperimentInactive` | Indicate that an experiment is no longer running.. | [Using the Experiments API][experiments-api] | diff --git a/docs/user/reference/general/initializing.md b/docs/user/reference/general/initializing.md index e3df475262..3fe04be0a8 100644 --- a/docs/user/reference/general/initializing.md +++ b/docs/user/reference/general/initializing.md @@ -86,7 +86,7 @@ To learn about SDK specific configuration options available, refer to the [Refer > > Always pass the user preference, e.g. `Glean.initialize(uploadEnabled=userSettings.telemetryEnabled)` or the equivalent for your application. > -> Calling `Glean.setUploadEnabled(false)` at a later point will trigger [`deletion-request` pings](../../user/pings/deletion-request.md) and regenerate client IDs. +> Calling `Glean.setCollectionEnabled(false)` at a later point will trigger [`deletion-request` pings](../../user/pings/deletion-request.md) and regenerate client IDs. > This should only be done if the user preference actually changes. {{#include ../../../shared/tab_header.md}} diff --git a/docs/user/reference/general/toggling-upload-status.md b/docs/user/reference/general/toggling-collection-status.md similarity index 55% rename from docs/user/reference/general/toggling-upload-status.md rename to docs/user/reference/general/toggling-collection-status.md index f949a462a0..e6eaa8c92f 100644 --- a/docs/user/reference/general/toggling-upload-status.md +++ b/docs/user/reference/general/toggling-collection-status.md @@ -1,39 +1,49 @@ -# Toggling upload status +# Toggling collection status -The Glean SDKs provide an API for toggling Glean's upload status after initialization. +The Glean SDKs provide an API for toggling Glean's collection status after initialization. Applications instrumented with Glean [are expected to](../../user/adding-glean-to-your-project/index.md#glean-integration-checklist) -provide some form of user interface to allow for toggling the upload status. +provide some form of user interface to allow for toggling the collection status. -## Disabling upload +{{#include ../../../shared/blockquote-info.html}} -When upload is disabled, the Glean SDK will perform the following tasks: +## `setUploadEnabled` is deprecated since Glean v63.0.0 + +> Prior to Glean v63.0.0 this API was called `setUploadEnabled`. +> `setUploadEnabled` is now deprecated and replaced by `setCollectionEnabled`. +> It behaves the same way with respect to built-in pings and custom pings, +> unless those are marked with `follows_collection_enabled: false`. +> See [TODO: the collection-enabled documentation for details](). + +## Disabling collection + +When collection is disabled, the Glean SDK will perform the following tasks: 1. Submit a [`deletion-request`](../../user/pings/deletion-request.md) ping. 2. Cancel scheduled ping uploads. 3. Clear metrics and pings data from the client, except for the [`first_run_date`](../../user/pings/index.html#the-client_info-section) metric. -While upload is disabled, metrics aren't recorded and no data is uploaded. +While collection is disabled, metrics aren't recorded and no data is uploaded. -## Enabling upload +## Enabling collection -When upload is enabled, the Glean SDK will re-initialize its [core metrics](../../user/collected-metrics/metrics.md). +When collection is enabled, the Glean SDK will re-initialize its [core metrics](../../user/collected-metrics/metrics.md). The only core metric that is not re-initialized is the [`first_run_date`](../../user/pings/index.html#the-client_info-section) metric. -While upload is enabled all metrics are recorded as expected +While collection is enabled all metrics are recorded as expected and pings are sent to the telemetry servers. ## API -### `Glean.setUploadEnabled(boolean)` +### `Glean.setCollectionEnabled(boolean)` -Enables or disables upload. +Enables or disables collection. If called prior to initialize this function is a no-op. -If the upload state is not actually changed in between calls to this function, it is also a no-op. +If the collection state is not actually changed in between calls to this function, it is also a no-op. {{#include ../../../shared/tab_header.md}} @@ -48,9 +58,9 @@ open class MainActivity : AppCompatActivity() { uploadSwitch.setOnCheckedChangeListener { _, isChecked -> if (isChecked) { - Glean.setUploadEnabled(true) + Glean.setCollectionEnabled(true) } else { - Glean.setUploadEnabled(false) + Glean.setCollectionEnabled(false) } } } @@ -63,7 +73,7 @@ open class MainActivity : AppCompatActivity() { ```Java import mozilla.telemetry.glean.Glean -Glean.INSTANCE.setUploadEnabled(false); +Glean.INSTANCE.setCollectionEnabled(false); ``` @@ -80,7 +90,7 @@ class ViewController: UIViewController { // ... @IBAction func enableToggled(_: Any) { - Glean.shared.setUploadEnabled(enableSwitch.isOn) + Glean.shared.setCollectionEnabled(enableSwitch.isOn) } } ``` @@ -92,7 +102,7 @@ class ViewController: UIViewController { ```python from glean import Glean -Glean.set_upload_enabled(false) +Glean.set_collection_enabled(false) ``` @@ -101,13 +111,12 @@ Glean.set_upload_enabled(false) ```Rust use glean; -glean::set_upload_enabled(false); +glean::set_collection_enabled(false); ```
- ```js import Glean from "@mozilla/glean/web"; @@ -121,6 +130,12 @@ uploadSwitch.addEventListener("change", event => { }); ``` +{{#include ../../../shared/blockquote-info.html}} + +## Glean.js still uses `setUploadEnabled` + +> Glean.js did not yet switch to the new naming and continues to use `setUploadEnabled` unchanged. +
@@ -128,7 +143,7 @@ uploadSwitch.addEventListener("change", event => { ## Reference -* [Swift API docs](../../../swift/Classes/Glean.html#/s:5GleanAAC16setUploadEnabledyySbF) -* [Python API docs](../../../python/glean/index.html#glean.Glean.set_upload_enabled) -* [Rust API docs](../../../docs/glean/fn.set_upload_enabled.html) +* [Swift API docs](../../../swift/Classes/Glean.html#/s:5GleanAAC16setCollectionEnabledyySbF) +* [Python API docs](../../../python/glean/index.html#glean.Glean.set_collection_enabled) +* [Rust API docs](../../../docs/glean/fn.set_collection_enabled.html) * [JavaScript API docs](https://mozilla.github.io/glean.js/reference/uploaders/#uploadenabled) diff --git a/docs/user/user/adding-glean-to-your-project/index.md b/docs/user/user/adding-glean-to-your-project/index.md index 3460320123..fde08706cb 100644 --- a/docs/user/user/adding-glean-to-your-project/index.md +++ b/docs/user/user/adding-glean-to-your-project/index.md @@ -26,7 +26,7 @@ Additionally, applications (but not libraries) **must**: 6. [Initialize Glean](../../reference/general/initializing.md) as early as possible at application startup. -7. Provide a way for users to turn data collection off (e.g. providing settings to control `Glean.setUploadEnabled()`). The exact method used is application-specific. +7. Provide a way for users to turn data collection off (e.g. providing settings to control `Glean.setCollectionEnabled()`). The exact method used is application-specific. {{#include ../../../shared/blockquote-info.html}}