firefox-suggest-telemetry.rst (57054B)
1 Firefox Suggest Telemetry 2 ========================= 3 4 This document describes the telemetry that Firefox records for the Firefox 5 Suggest feature. That is, it describes Firefox Suggest telemetry recorded on the 6 client. It also discusses the data that Firefox sends to the Merino service. 7 8 This document only covers Legacy telemetry, not Glean telemetry. 9 Glean metrics are self-documenting and can be looked up in the Glean dictionary. 10 11 For information on other telemetry related to the address bar, see the general 12 address bar :doc:`telemetry` document. For information on all telemetry in 13 Firefox, see the toolkit :doc:`/toolkit/components/telemetry/index` document. 14 15 .. contents:: 16 :depth: 2 17 18 19 Histograms 20 ---------- 21 22 The following histograms are recorded for Firefox Suggest. For general 23 information on histogram telemetry in Firefox, see the 24 :doc:`/toolkit/components/telemetry/collection/histograms` document. 25 26 FX_URLBAR_MERINO_LATENCY_MS 27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 28 29 This histogram records the latency in milliseconds of the Merino source for 30 suggestions, or in other words, the time from Firefox's request to the Merino 31 server to the time Firefox receives a response. It is an exponential histogram 32 with 50 buckets and values between 0 and 30000 (0s and 30s). 33 34 Changelog 35 Firefox 93.0 36 Introduced. [Bug 1727799_] 37 38 Firefox 137.0 39 Removed. [Bug 1946922_] 40 41 .. _1727799: https://bugzilla.mozilla.org/show_bug.cgi?id=1727799 42 .. _1946922: https://bugzilla.mozilla.org/show_bug.cgi?id=1946922 43 44 FX_URLBAR_MERINO_LATENCY_WEATHER_MS 45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47 This histogram records the latency in milliseconds of weather suggestions from 48 Merino. It is updated in addition to ``FX_URLBAR_MERINO_LATENCY_MS`` and has the 49 same properties. It is an exponential histogram with 50 buckets and values 50 between 0 and 30000 (0s and 30s). 51 52 Changelog 53 Firefox 110.0 54 Introduced. [Bug 1804536_] 55 56 Firefox 137.0 57 Removed. [Bug 1946922_] 58 59 .. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536 60 .. _1946922: https://bugzilla.mozilla.org/show_bug.cgi?id=1946922 61 62 FX_URLBAR_MERINO_RESPONSE 63 ~~~~~~~~~~~~~~~~~~~~~~~~~ 64 65 This categorical histogram records a summary of each fetch from the Merino 66 server. It has the following categories: 67 68 :0 "success": 69 The fetch completed without any error before the timeout elapsed and it 70 included at least one suggestion. (Before Firefox 110.0, this category meant 71 simply that the fetch completed without any error before the timeout elapsed 72 regardless of whether it included any suggestions.) 73 :1 "timeout": 74 The timeout elapsed before the fetch completed or otherwise failed. 75 :2 "network_error": 76 The fetch failed due to a network error before the timeout elapsed. e.g., the 77 user's network or the Merino server was down. 78 :3 "http_error": 79 The fetch completed before the timeout elapsed but the server returned an 80 error. 81 :4 "no_suggestion": 82 The fetch completed without any error before the timeout elapsed and it did 83 not include any suggestions. 84 85 Changelog 86 Firefox 94.0.2 87 Introduced. [Bug 1737923_] 88 89 Firefox 110.0 90 Added the ``no_suggestion`` category. The meaning of the ``success`` 91 category was changed from "The fetch completed without any error before the 92 timeout elapsed" to "The fetch completed without any error before the 93 timeout elapsed and it included at least one suggestion." [Bug 1804536_] 94 95 Firefox 137.0 96 Removed. [Bug 1946922_] 97 98 .. _1737923: https://bugzilla.mozilla.org/show_bug.cgi?id=1737923 99 .. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536 100 .. _1946922: https://bugzilla.mozilla.org/show_bug.cgi?id=1946922 101 102 FX_URLBAR_MERINO_RESPONSE_WEATHER 103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 104 105 This categorical histogram records a summary of each fetch for weather 106 suggestions from the Merino server. It is updated in addition to 107 ``FX_URLBAR_MERINO_RESPONSE`` and has the same categories. 108 109 :0 "success": 110 The fetch completed without any error before the timeout elapsed and it 111 included at least one suggestion. 112 :1 "timeout": 113 The timeout elapsed before the fetch completed or otherwise failed. 114 :2 "network_error": 115 The fetch failed due to a network error before the timeout elapsed. e.g., the 116 user's network or the Merino server was down. 117 :3 "http_error": 118 The fetch completed before the timeout elapsed but the server returned an 119 error. 120 :4 "no_suggestion": 121 The fetch completed without any error before the timeout elapsed and it did 122 not include any suggestions. 123 124 Changelog 125 Firefox 110.0 126 Introduced. [Bug 1804536_] 127 128 Firefox 137.0 129 Removed. [Bug 1946922_] 130 131 .. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536 132 .. _1946922: https://bugzilla.mozilla.org/show_bug.cgi?id=1946922 133 134 FX_URLBAR_QUICK_SUGGEST_REMOTE_SETTINGS_LATENCY_MS 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 136 137 This histogram records the latency in milliseconds of the remote settings source 138 for suggestions, or in other words, the time from when Firefox starts fetching a 139 suggestion from remote settings to the time the suggestion is retrieved. It is 140 an exponential histogram with 50 buckets and values between 0 and 30000 (0s and 141 30s). 142 143 Note that unlike Merino, fetches from remote settings happen entirely on the 144 client, so remote settings latencies are expected to be much smaller than Merino 145 latencies. 146 147 Changelog 148 Firefox 94.0.2 149 Introduced. [Bug 1737651_] 150 151 Firefox 135.0 152 Removed. [Bug 1932502_] 153 154 .. _1737651: https://bugzilla.mozilla.org/show_bug.cgi?id=1737651 155 .. _1932502: https://bugzilla.mozilla.org/show_bug.cgi?id=1932502 156 157 Scalars 158 ------- 159 160 The following scalars are recorded for Firefox Suggest. For general information 161 on scalar telemetry in Firefox, see the 162 :doc:`/toolkit/components/telemetry/collection/scalars` document. 163 164 browser.ui.interaction.preferences_paneSearch 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 166 167 This keyed scalar is incremented each time the user clicks a Firefox Suggest 168 checkbox or toggle switch in the preferences UI. 169 170 Note: These are also recorded in different forms under the 171 ``contextual.services.quicksuggest.*`` telemetry described below. 172 173 Keys are the following: 174 175 :firefoxSuggestBestMatch: 176 This key is incremented when the "Top pick" checkbox is clicked. In 120 this 177 UI was removed, so this key is no longer recorded. 178 :firefoxSuggestBestMatchLearnMore: 179 This key is incremented when opening the learn more link for best match. In 180 120 this UI was removed, so this key is no longer recorded. 181 :firefoxSuggestDataCollectionToggle: 182 This key is incremented when the toggle switch for data collection 183 is clicked. 184 :firefoxSuggestNonsponsored: 185 This key is incremented when the toggle switch for non-sponsored suggestions 186 is clicked. 187 :firefoxSuggestSponsored: 188 This key is incremented when the toggle switch for sponsored suggestions 189 is clicked. 190 191 Changelog 192 Firefox 94.0.2 193 Introduced ``firefoxSuggestDataCollectionToggle``, 194 ``firefoxSuggestNonsponsoredToggle`` and ``firefoxSuggestSponsoredToggle``. 195 [Bug 1735976_] 196 197 Firefox 99.0 198 Introduced ``firefoxSuggestBestMatch``. [Bug 1755100_] 199 Introduced ``firefoxSuggestBestMatchLearnMore``. [Bug 1756917_] 200 201 Firefox 120.0 202 Removed ``firefoxSuggestBestMatch`` and 203 ``firefoxSuggestBestMatchLearnMore``. [Bug 1857391_] 204 205 Firefox 123.0 206 Recording moved from ``browser.ui.interaction.preferences_panePrivacy`` to 207 ``browser.ui.interaction.preferences_paneSearch``. [Bug 1852048_] 208 ``firefoxSuggestNonsponsoredToggle`` was renamed to ``firefoxSuggestNonsponsored`` 209 ``firefoxSuggestSponsoredToggle`` was renamed to ``firefoxSuggestSponsored`` 210 `` 211 212 .. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976 213 .. _1755100: https://bugzilla.mozilla.org/show_bug.cgi?id=1755100 214 .. _1756917: https://bugzilla.mozilla.org/show_bug.cgi?id=1756917 215 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 216 .. _1852048: https://bugzilla.mozilla.org/show_bug.cgi?id=1852048 217 218 contextual.services.quicksuggest.block_dynamic_wikipedia 219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 220 221 This keyed scalar is incremented each time the user dismisses ("blocks") a 222 dynamic wikipedia suggestion. Each key is the index at which a suggestion 223 appeared in the results (1-based), and the corresponding value is the number 224 of dismissals at that index. 225 226 Changelog 227 Firefox 109.0 228 Introduced. [Bug 1800993_] 229 230 Firefox 133.0 231 Removed. [Bug 1925355_] 232 233 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 234 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 235 236 contextual.services.quicksuggest.block_nonsponsored 237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 238 239 This keyed scalar is incremented each time the user dismisses ("blocks") a 240 non-sponsored suggestion, including both best matches and the usual 241 non-best-match suggestions. Each key is the index at which a suggestion appeared 242 in the results (1-based), and the corresponding value is the number of 243 dismissals at that index. 244 245 Changelog 246 Firefox 101.0 247 Introduced. [Bug 1761059_] 248 249 Firefox 133.0 250 Removed. [Bug 1925355_] 251 252 .. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059 253 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 254 255 contextual.services.quicksuggest.block_nonsponsored_bestmatch 256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 257 258 This keyed scalar was removed in Firefox 120. Prior to that, it is incremented 259 each time the user dismisses ("blocks") a non-sponsored best match. Each key is 260 the index at which a suggestion appeared in the results (1-based), and the 261 corresponding value is the number of dismissals at that index. 262 263 Changelog 264 Firefox 101.0 265 Introduced. [Bug 1761059_] 266 267 Firefox 120.0 268 Removed. [Bug 1857391_] 269 270 .. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059 271 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 272 273 contextual.services.quicksuggest.block_sponsored 274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 275 276 This keyed scalar is incremented each time the user dismisses ("blocks") a 277 sponsored suggestion, including both best matches and the usual non-best-match 278 suggestions. Each key is the index at which a suggestion appeared in the results 279 (1-based), and the corresponding value is the number of dismissals at that 280 index. 281 282 Changelog 283 Firefox 101.0 284 Introduced. [Bug 1761059_] 285 286 Firefox 133.0 287 Removed. [Bug 1925355_] 288 289 .. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059 290 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 291 292 contextual.services.quicksuggest.block_sponsored_bestmatch 293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 294 295 This keyed scalar was removed in Firefox 120. Prior to that, it is incremented 296 each time the user dismisses ("blocks") a sponsored best match. Each key is the 297 index at which a suggestion appeared in the results (1-based), and the 298 corresponding value is the number of dismissals at that index. 299 300 Changelog 301 Firefox 101.0 302 Introduced. [Bug 1761059_] 303 304 Firefox 120.0 305 Removed. [Bug 1857391_] 306 307 .. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059 308 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 309 310 contextual.services.quicksuggest.block_weather 311 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 312 313 This keyed scalar is incremented each time the user dismisses ("blocks") a 314 Firefox Suggest weather suggestion. Each key is the index at which a suggestion 315 appeared in the results (1-based), and the corresponding value is the number of 316 dismissals at that index. 317 318 Changelog 319 Firefox 110.0 320 Introduced. [Bug 1804536_] 321 322 Firefox 133.0 323 Removed. [Bug 1925355_] 324 325 .. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536 326 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 327 328 contextual.services.quicksuggest.click 329 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 330 331 This keyed scalar is incremented each time the user picks a suggestion. Each key 332 is the index at which a suggestion appeared in the results (1-based), and the 333 corresponding value is the number of clicks at that index. 334 335 Changelog 336 Firefox 87.0 337 Introduced. [Bug 1693927_] 338 339 Firefox 109.0 340 Removed. [Bug 1800993_] 341 342 .. _1693927: https://bugzilla.mozilla.org/show_bug.cgi?id=1693927 343 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 344 345 contextual.services.quicksuggest.click_dynamic_wikipedia 346 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 347 348 This keyed scalar is incremented each time the user picks a dynamic 349 wikipedia suggestion. Each key is the index at which a suggestion appeared 350 in the results (1-based), and the corresponding value is the number of 351 clicks at that index. 352 353 Changelog 354 Firefox 109.0 355 Introduced. [Bug 1800993_] 356 357 Firefox 133.0 358 Removed. [Bug 1925355_] 359 360 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 361 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 362 363 contextual.services.quicksuggest.click_nav_notmatched 364 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 365 366 This keyed scalar records how many times a heuristic result was clicked while a 367 navigational suggestion was absent. It is recorded only when the Nimbus variable 368 ``recordNavigationalSuggestionTelemetry`` is true. (The variable is false by 369 default.) 370 371 Each key is the type of heuristic result that was clicked. Key names are the 372 same as the heuristic result type names recorded in Glean telemetry. 373 374 Changelog 375 Firefox 112.0 376 Introduced. [Bug 1819797_] 377 378 Firefox 133.0 379 Removed. [Bug 1925355_] 380 381 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 382 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 383 384 contextual.services.quicksuggest.click_nav_shown_heuristic 385 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 386 387 This keyed scalar records how many times a heuristic result was clicked while a 388 navigational suggestion was present. It is recorded only when the Nimbus 389 variable ``recordNavigationalSuggestionTelemetry`` is true. (The variable is 390 false by default.) 391 392 Each key is the type of heuristic result that was clicked. Key names are the 393 same as the heuristic result type names recorded in Glean telemetry. 394 395 Changelog 396 Firefox 112.0 397 Introduced. [Bug 1819797_] 398 399 Firefox 133.0 400 Removed. [Bug 1925355_] 401 402 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 403 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 404 405 contextual.services.quicksuggest.click_nav_shown_nav 406 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 407 408 This keyed scalar records how many times a navigational suggestion was clicked. 409 It is recorded only when the Nimbus variable 410 ``recordNavigationalSuggestionTelemetry`` is true. (The variable is false by 411 default.) 412 413 Each key is the type of heuristic result that was present at the time of the 414 engagement. Key names are the same as the heuristic result type names recorded 415 in Glean telemetry. 416 417 Changelog 418 Firefox 112.0 419 Introduced. [Bug 1819797_] 420 421 Firefox 133.0 422 Removed. [Bug 1925355_] 423 424 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 425 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 426 427 contextual.services.quicksuggest.click_nav_superceded 428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 429 430 This keyed scalar records how many times a heuristic result was clicked when a 431 navigational suggestion was matched but superseded by the heuristic. It is 432 recorded only when the Nimbus variable ``recordNavigationalSuggestionTelemetry`` 433 is true. (The variable is false by default.) 434 435 Each key is the type of heuristic result that was clicked. Key names are the 436 same as the heuristic result type names recorded in Glean telemetry. 437 438 Changelog 439 Firefox 112.0 440 Introduced. [Bug 1819797_] 441 442 Firefox 133.0 443 Removed. [Bug 1925355_] 444 445 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 446 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 447 448 contextual.services.quicksuggest.click_nonsponsored 449 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 450 451 This keyed scalar is incremented each time the user picks a non-sponsored 452 suggestion. Each key is the index at which a suggestion appeared in the 453 results (1-based), and the corresponding value is the number of clicks at 454 that index. 455 456 Changelog 457 Firefox 109.0 458 Introduced. [Bug 1800993_] 459 460 Firefox 133.0 461 Removed. [Bug 1925355_] 462 463 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 464 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 465 466 contextual.services.quicksuggest.click_nonsponsored_bestmatch 467 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 468 469 This keyed scalar was removed in Firefox 120. Prior to that, it is incremented 470 each time the user picks a non-sponsored best match. Each key is the index at 471 which a suggestion appeared in the results (1-based), and the corresponding 472 value is the number of clicks at that index. 473 474 Changelog 475 Firefox 99.0 476 Introduced. [Bug 1752953_] 477 478 Firefox 120.0 479 Removed. [Bug 1857391_] 480 481 .. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953 482 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 483 484 contextual.services.quicksuggest.click_sponsored 485 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 486 487 This keyed scalar is incremented each time the user picks a sponsored suggestion. 488 Each key is the index at which a suggestion appeared in the results (1-based), 489 and the corresponding value is the number of clicks at that index. 490 491 Changelog 492 Firefox 109.0 493 Introduced. [Bug 1800993_] 494 495 Firefox 133.0 496 Removed. [Bug 1925355_] 497 498 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 499 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 500 501 contextual.services.quicksuggest.click_sponsored_bestmatch 502 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 503 504 This keyed scalar was removed in Firefox 120. Prior to that, it is incremented 505 each time the user picks a sponsored best match. Each key is the index at which 506 a suggestion appeared in the results (1-based), and the corresponding value is 507 the number of clicks at that index. 508 509 Changelog 510 Firefox 99.0 511 Introduced. [Bug 1752953_] 512 513 Firefox 120.0 514 Removed. [Bug 1857391_] 515 516 .. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953 517 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 518 519 contextual.services.quicksuggest.click_weather 520 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 521 522 This keyed scalar is incremented each time the user picks a weather suggestion. 523 Each key is the index at which a suggestion appeared in the results (1-based), 524 and the corresponding value is the number of clicks at that index. 525 526 Changelog 527 Firefox 110.0 528 Introduced. [Bug 1804536_] 529 530 Firefox 133.0 531 Removed. [Bug 1925355_] 532 533 .. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536 534 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 535 536 contextual.services.quicksuggest.exposure_weather 537 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 538 539 This keyed scalar records weather suggestion exposures. It is incremented each 540 time the user is shown a weather suggestion. It can be compared to the 541 ``urlbar.zeroprefix.exposure`` scalar (see :doc:`telemetry`) to determine the 542 percentage of zero-prefix exposures that included weather suggestions. 543 544 Each key is the index at which a suggestion appeared in the results (1-based), 545 and the corresponding value is the number of exposures at that index. 546 547 Changelog 548 Firefox 110.0 549 Introduced. [Bug 1806765_] 550 551 Firefox 114.0 552 Removed since the weather suggestion is no longer triggered on zero prefix. 553 [Bug 1831971_] 554 555 .. _1806765: https://bugzilla.mozilla.org/show_bug.cgi?id=1806765 556 .. _1831971: https://bugzilla.mozilla.org/show_bug.cgi?id=1831971 557 558 contextual.services.quicksuggest.help 559 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 560 561 This keyed scalar is incremented each time the user picks the help button in a 562 suggestion. Each key is the index at which a suggestion appeared in the results 563 (1-based), and the corresponding value is the number of help button clicks at 564 that index. 565 566 Changelog 567 Firefox 87.0 568 Introduced. [Bug 1693927_] 569 570 Firefox 109.0 571 Removed. [Bug 1800993_] 572 573 .. _1693927: https://bugzilla.mozilla.org/show_bug.cgi?id=1693927 574 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 575 576 contextual.services.quicksuggest.help_dynamic_wikipedia 577 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 578 579 This keyed scalar is incremented each time the user picks the help button in a 580 dynamic wikipedia suggestion. Each key is the index at which a suggestion 581 appeared in the results (1-based), and the corresponding value is the number 582 of help button clicks at that index. 583 584 Changelog 585 Firefox 109.0 586 Introduced. [Bug 1800993_] 587 588 Firefox 127.0 589 Removed. [Bug 1891602_] 590 591 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 592 .. _1891602: https://bugzilla.mozilla.org/show_bug.cgi?id=1891602 593 594 contextual.services.quicksuggest.help_nonsponsored 595 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 596 597 This keyed scalar is incremented each time the user picks the help button in a 598 non-sponsored suggestion. Each key is the index at which a suggestion appeared in the 599 results (1-based), and the corresponding value is the number of help button clicks 600 at that index. 601 602 Changelog 603 Firefox 109.0 604 Introduced. [Bug 1800993_] 605 606 Firefox 133.0 607 Removed. [Bug 1925355_] 608 609 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 610 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 611 612 contextual.services.quicksuggest.help_nonsponsored_bestmatch 613 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 614 615 This keyed scalar was removed in Firefox 120. Prior to that, it is incremented 616 each time the user picks the help button in a non-sponsored best match. Each key 617 is the index at which a suggestion appeared in the results (1-based), and the 618 corresponding value is the number of help button clicks at that index. 619 620 Changelog 621 Firefox 99.0 622 Introduced. [Bug 1752953_] 623 624 Firefox 120.0 625 Removed. [Bug 1857391_] 626 627 .. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953 628 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 629 630 contextual.services.quicksuggest.help_sponsored 631 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 632 633 This keyed scalar is incremented each time the user picks the help button in a 634 sponsored suggestion. Each key is the index at which a suggestion appeared in the 635 results (1-based), and the corresponding value is the number of help button clicks 636 at that index. 637 638 Changelog 639 Firefox 109.0 640 Introduced. [Bug 1800993_] 641 642 Firefox 133.0 643 Removed. [Bug 1925355_] 644 645 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 646 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 647 648 contextual.services.quicksuggest.help_sponsored_bestmatch 649 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 650 651 This keyed scalar was removed in Firefox 120. Prior to that, it is incremented 652 each time the user picks the help button in a sponsored best match. Each key is 653 the index at which a suggestion appeared in the results (1-based), and the 654 corresponding value is the number of help button clicks at that index. 655 656 Changelog 657 Firefox 99.0 658 Introduced. [Bug 1752953_] 659 660 Firefox 120.0 661 Removed. [Bug 1857391_] 662 663 .. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953 664 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 665 666 contextual.services.quicksuggest.help_weather 667 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 668 669 This keyed scalar is incremented each time the user picks the help button in a 670 weather suggestion. Each key is the index at which a suggestion appeared in the 671 results (1-based), and the corresponding value is the number of help button 672 clicks at that index. 673 674 Changelog 675 Firefox 110.0 676 Introduced. [Bug 1804536_] 677 678 Firefox 127.0 679 Removed. [Bug 1891602_] 680 681 .. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536 682 .. _1891602: https://bugzilla.mozilla.org/show_bug.cgi?id=1891602 683 684 contextual.services.quicksuggest.impression 685 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 686 687 This keyed scalar records suggestion impressions. It is incremented each time 688 the user is shown a suggestion and the following two conditions hold: 689 690 - The user has completed an engagement with the address bar by picking a result 691 in it or by pressing the Enter key. 692 - At the time the user completed the engagement, a suggestion was present in the 693 results. 694 695 Each key is the index at which a suggestion appeared in the results (1-based), 696 and the corresponding value is the number of impressions at that index. 697 698 Changelog 699 Firefox 87.0 700 Introduced. [Bug 1693927_] 701 702 Firefox 109.0 703 Removed. [Bug 1800993_] 704 705 .. _1693927: https://bugzilla.mozilla.org/show_bug.cgi?id=1693927 706 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 707 708 contextual.services.quicksuggest.impression_dynamic_wikipedia 709 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 710 711 This keyed scalar records dynamic wikipedia impressions. It is incremented 712 each time the user is shown a dynamic wikipedia suggestion and the following 713 two conditions hold: 714 715 - The user has completed an engagement with the address bar by picking a result 716 in it or by pressing the Enter key. 717 - At the time the user completed the engagement, a dynamic wikipedia suggestion 718 was present in the results. 719 720 Each key is the index at which a suggestion appeared in the results (1-based), 721 and the corresponding value is the number of impressions at that index. 722 723 Changelog 724 Firefox 109.0 725 Introduced. [Bug 1800993_] 726 727 Firefox 133.0 728 Removed. [Bug 1925355_] 729 730 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 731 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 732 733 contextual.services.quicksuggest.impression_nav_notmatched 734 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 735 736 This keyed scalar records how many times a urlbar engagement occurred while a 737 navigational suggestion was absent. It is recorded only when the Nimbus variable 738 ``recordNavigationalSuggestionTelemetry`` is true. (The variable is false by 739 default.) 740 741 Each key is the type of heuristic result that was present at the time of the 742 engagement. Key names are the same as the heuristic result type names recorded 743 in Glean telemetry. 744 745 Changelog 746 Firefox 112.0 747 Introduced. [Bug 1819797_] 748 749 Firefox 133.0 750 Removed. [Bug 1925355_] 751 752 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 753 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 754 755 contextual.services.quicksuggest.impression_nav_shown 756 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 757 758 This keyed scalar records how many times a urlbar engagement occurred while a 759 navigational suggestion was present. It is recorded only when the Nimbus 760 variable ``recordNavigationalSuggestionTelemetry`` is true. (The variable is 761 false by default.) 762 763 Each key is the type of heuristic result that was present at the time of the 764 engagement. Key names are the same as the heuristic result type names recorded 765 in Glean telemetry. 766 767 Changelog 768 Firefox 112.0 769 Introduced. [Bug 1819797_] 770 771 Firefox 133.0 772 Removed. [Bug 1925355_] 773 774 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 775 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 776 777 contextual.services.quicksuggest.impression_nav_superceded 778 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 779 780 This keyed scalar records how many times a urlbar engagement occurred when a 781 navigational suggestion was matched but superseded by a heuristic result. It is 782 recorded only when the Nimbus variable ``recordNavigationalSuggestionTelemetry`` 783 is true. (The variable is false by default.) 784 785 Each key is the type of heuristic result that was present at the time of the 786 engagement. Key names are the same as the heuristic result type names recorded 787 in Glean telemetry. 788 789 Changelog 790 Firefox 112.0 791 Introduced. [Bug 1819797_] 792 793 Firefox 133.0 794 Removed. [Bug 1925355_] 795 796 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 797 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 798 799 contextual.services.quicksuggest.impression_nonsponsored 800 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 801 802 This keyed scalar records suggestion impressions. It is incremented each time 803 the user is shown a non-sponsored suggestion and the following two conditions hold: 804 805 - The user has completed an engagement with the address bar by picking a result 806 in it or by pressing the Enter key. 807 - At the time the user completed the engagement, a suggestion was present in the 808 results. 809 810 Each key is the index at which a suggestion appeared in the results (1-based), 811 and the corresponding value is the number of impressions at that index. 812 813 Changelog 814 Firefox 109.0 815 Introduced. [Bug 1800993_] 816 817 Firefox 133.0 818 Removed. [Bug 1925355_] 819 820 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 821 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 822 823 contextual.services.quicksuggest.impression_nonsponsored_bestmatch 824 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 825 826 This keyed scalar was removed in Firefox 120. Prior to that, it records 827 non-sponsored best match impressions. It is incremented each time the user is 828 shown a non-sponsored best match and the following two conditions hold: 829 830 - The user has completed an engagement with the address bar by picking a result 831 in it or by pressing the Enter key. 832 - At the time the user completed the engagement, a non-sponsored best match was 833 present in the results. 834 835 Each key is the index at which a suggestion appeared in the results (1-based), 836 and the corresponding value is the number of impressions at that index. 837 838 Changelog 839 Firefox 99.0 840 Introduced. [Bug 1752953_] 841 842 Firefox 120.0 843 Removed. [Bug 1857391_] 844 845 .. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953 846 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 847 848 contextual.services.quicksuggest.impression_sponsored 849 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 850 851 This keyed scalar records suggestion impressions. It is incremented each time 852 the user is shown a sponsored suggestion and the following two conditions hold: 853 854 - The user has completed an engagement with the address bar by picking a result 855 in it or by pressing the Enter key. 856 - At the time the user completed the engagement, a suggestion was present in the 857 results. 858 859 Each key is the index at which a suggestion appeared in the results (1-based), 860 and the corresponding value is the number of impressions at that index. 861 862 Changelog 863 Firefox 109.0 864 Introduced. [Bug 1800993_] 865 866 Firefox 133.0 867 Removed. [Bug 1925355_] 868 869 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 870 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 871 872 contextual.services.quicksuggest.impression_sponsored_bestmatch 873 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 874 875 This keyed scalar was removed in Firefox 120. Prior to that, it records 876 sponsored best match impressions. It is incremented each time the user is shown 877 a sponsored best match and the following two conditions hold: 878 879 - The user has completed an engagement with the address bar by picking a result 880 in it or by pressing the Enter key. 881 - At the time the user completed the engagement, a sponsored best match was 882 present in the results. 883 884 Each key is the index at which a suggestion appeared in the results (1-based), 885 and the corresponding value is the number of impressions at that index. 886 887 Changelog 888 Firefox 99.0 889 Introduced. [Bug 1752953_] 890 891 Firefox 120.0 892 Removed. [Bug 1857391_] 893 894 .. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953 895 .. _1857391: https://bugzilla.mozilla.org/show_bug.cgi?id=1857391 896 897 contextual.services.quicksuggest.impression_weather 898 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 899 900 This keyed scalar records weather suggestion impressions. It is incremented each 901 time the user is shown a weather suggestion and the following two conditions 902 hold: 903 904 - The user has completed an engagement with the address bar by picking a result 905 in it or by pressing the Enter key. 906 - At the time the user completed the engagement, a weather suggestion was 907 present in the results. 908 909 Each key is the index at which a suggestion appeared in the results (1-based), 910 and the corresponding value is the number of impressions at that index. 911 912 Changelog 913 Firefox 110.0 914 Introduced. [Bug 1804536_] 915 916 Firefox 133.0 917 Removed. [Bug 1925355_] 918 919 .. _1804536: https://bugzilla.mozilla.org/show_bug.cgi?id=1804536 920 .. _1925355: https://bugzilla.mozilla.org/show_bug.cgi?id=1925355 921 922 Events 923 ------ 924 925 The following Firefox Suggest events are recorded in the 926 ``contextservices.quicksuggest`` category. For general information on event 927 telemetry in Firefox, see the 928 :doc:`/toolkit/components/telemetry/collection/events` document. 929 930 contextservices.quicksuggest.data_collect_toggled 931 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 932 933 This event is recorded when the 934 ``browser.urlbar.quicksuggest.dataCollection.enabled`` pref is toggled. The pref 935 can be toggled in the following ways: 936 937 - The user can toggle it in the preferences UI. 938 - The user can toggle it in about:config. 939 940 The event is also recorded when the user opts in to the online modal dialog, 941 with one exception: If the user has already enabled data collection using the 942 preferences UI or about:config, then the pref's user value is already 943 true. Opting in doesn't change the user value, so no event is recorded. 944 945 The event's objects are the following: 946 947 :enabled: 948 Recorded when the pref is flipped from false to true. 949 :disabled: 950 Recorded when the pref is flipped from true to false. 951 952 Changelog 953 Firefox 94.0.2 954 Introduced. [Bug 1735976_] 955 956 Firefox 133.0 957 Removed. [Bug 1921748_] 958 959 .. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976 960 .. _1921748: https://bugzilla.mozilla.org/show_bug.cgi?id=1921748 961 962 contextservices.quicksuggest.enable_toggled 963 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 964 965 This event is recorded when the 966 ``browser.urlbar.suggest.quicksuggest.nonsponsored`` pref is toggled. The pref 967 can be toggled in the following ways: 968 969 - The user can toggle it in the preferences UI. 970 - The user can toggle it in about:config. 971 972 The event's objects are the following: 973 974 :enabled: 975 Recorded when the pref is flipped from false to true. 976 :disabled: 977 Recorded when the pref is flipped from true to false. 978 979 Changelog 980 Firefox 87.0: 981 Introduced. The event corresponds to the 982 ``browser.urlbar.suggest.quicksuggest`` pref. [Bug 1693126_] 983 984 Firefox 94.0.2: 985 ``browser.urlbar.suggest.quicksuggest`` is replaced with 986 ``browser.urlbar.suggest.quicksuggest.nonsponsored``, and this event now 987 corresponds to the latter pref. [Bug 1735976_] 988 989 Firefox 96.0: 990 The event is no longer recorded when the user interacts with the online 991 modal dialog since the ``browser.urlbar.suggest.quicksuggest.nonsponsored`` 992 pref is no longer set when the user opts in or out. [Bug 1740965_] 993 994 Firefox 133.0 995 Removed. [Bug 1921748_] 996 997 .. _1693126: https://bugzilla.mozilla.org/show_bug.cgi?id=1693126 998 .. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976 999 .. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965 1000 .. _1921748: https://bugzilla.mozilla.org/show_bug.cgi?id=1921748 1001 1002 contextservices.quicksuggest.engagement 1003 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1004 1005 This event is recorded when an engagement occurs in the address bar while a 1006 Firefox Suggest suggestion is present. In other words, it is recorded in two 1007 cases: 1008 1009 - The user picks a Firefox Suggest suggestion or a related UI element like its 1010 help button. 1011 - While a Firefox Suggest suggestion is present in the address bar, the user 1012 picks some other row. 1013 1014 The event's objects are the following possible values: 1015 1016 :block: 1017 The user dismissed ("blocked") the suggestion. 1018 :click: 1019 The user picked the suggestion. 1020 :help: 1021 The user picked the suggestion's help button. 1022 :impression_only: 1023 The user picked some other row. 1024 :other: 1025 The user engaged with the suggestion in some other way, for example by picking 1026 a command in the result menu. This is a catch-all category and going forward 1027 Glean telemetry should be preferred. 1028 1029 The event's ``extra`` contains the following properties: 1030 1031 :match_type: 1032 "best-match" if the suggestion was a best match or "firefox-suggest" if it was 1033 a non-best-match suggestion. 1034 :position: 1035 The index of the suggestion in the list of results (1-based). 1036 :suggestion_type: 1037 The type of suggestion, one of: "sponsored", "nonsponsored", 1038 "dynamic-wikipedia", "navigational" 1039 :source: 1040 The source of suggestion, one of: "remote-settings", "merino" 1041 1042 Changelog 1043 Firefox 101.0 1044 Introduced. [Bug 1761059_] 1045 1046 Firefox 109.0 1047 ``source`` is added. [Bug 1800993_] 1048 ``dynamic-wikipedia`` is added as a value of ``suggestion_type``. [Bug 1800993_] 1049 1050 Firefox 112.0 1051 ``navigational`` is added as a value of ``suggestion_type``. [Bug 1819797_] 1052 1053 Firefox 114.0 1054 ``other`` is added as a value of the event object. [Bug 1827943_] 1055 1056 Firefox 133.0 1057 Removed. [Bug 1921748_] 1058 1059 .. _1761059: https://bugzilla.mozilla.org/show_bug.cgi?id=1761059 1060 .. _1800993: https://bugzilla.mozilla.org/show_bug.cgi?id=1800993 1061 .. _1819797: https://bugzilla.mozilla.org/show_bug.cgi?id=1819797 1062 .. _1827943: https://bugzilla.mozilla.org/show_bug.cgi?id=1827943 1063 .. _1921748: https://bugzilla.mozilla.org/show_bug.cgi?id=1921748 1064 1065 contextservices.quicksuggest.impression_cap 1066 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1067 1068 This event is recorded when an event related to an impression cap occurs. The 1069 event's objects are the following possible values: 1070 1071 :hit: 1072 Recorded when an impression cap is hit. 1073 :reset: 1074 Recorded when a cap's counter is reset because its interval period has 1075 elapsed. The implementation may batch multiple consecutive reset events for a 1076 cap in a single telemetry event; see the ``eventCount`` discussion below. 1077 Reset events are reported only when a cap's interval period elapses while 1078 Firefox is running. 1079 1080 The event's ``extra`` contains the following properties: 1081 1082 :count: 1083 The number of impressions during the cap's interval period. 1084 :eventCount: 1085 The number of impression cap events reported in the telemetry event. This is 1086 necessary because the implementation may batch multiple consecutive "reset" 1087 events for a cap in a single telemetry event. When that occurs, this value 1088 will be greater than 1, ``startDate`` will be the timestamp at which the 1089 first event's interval period started, ``eventDate`` will be the timestamp at 1090 which the last event's interval period ended, and ``count`` will be the number 1091 of impressions during the first event's interval period. (The implementation 1092 guarantees that reset events are batched only when the number of impressions 1093 for all subsequent interval periods is zero.) For "hit" events, 1094 ``eventCount`` will always be 1. 1095 :eventDate: 1096 The event's timestamp, in number of milliseconds since Unix epoch. For "reset" 1097 events, this is the timestamp at which the cap's interval period ended. If 1098 ``eventCount`` is greater than 1, it's the timestamp at which the last 1099 interval period ended. For "hit" events, this is the timestamp at which the 1100 cap was hit. 1101 :impressionDate: 1102 The timestamp of the most recent impression, in number of milliseconds since 1103 Unix epoch. 1104 :intervalSeconds: 1105 The number of seconds in the cap's interval period. For lifetime caps, this 1106 value will be "Infinity". 1107 :maxCount: 1108 The maximum number of impressions allowed in the cap's interval period. 1109 :startDate: 1110 The timestamp at which the cap's interval period started, in number of 1111 milliseconds since Unix epoch. 1112 :type: 1113 The type of cap, one of: "sponsored", "nonsponsored" 1114 1115 Changelog 1116 Firefox 101.0 1117 Introduced. [Bug 1761058_, 1765881_] 1118 1119 Firefox 133.0 1120 Removed. [Bug 1921748_] 1121 1122 .. _1761058: https://bugzilla.mozilla.org/show_bug.cgi?id=1761058 1123 .. _1765881: https://bugzilla.mozilla.org/show_bug.cgi?id=1765881 1124 .. _1921748: https://bugzilla.mozilla.org/show_bug.cgi?id=1921748 1125 1126 contextservices.quicksuggest.opt_in_dialog 1127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1128 1129 This event is recorded when the user interacts with the online modal dialog. 1130 The event's objects are the following: 1131 1132 :accept: 1133 The user accepted the dialog and opted in. This object was removed in Firefox 1134 96.0.2. 1135 :accept_2: 1136 The user accepted the dialog and opted in. 1137 :close_1: 1138 The user clicked close button or something similar link on the introduction 1139 section. The user remains opted out in this case. 1140 :dismiss_1: 1141 The user dismissed the dialog by pressing the Escape key or some unknown way 1142 on the introduction section. The user remains opted out in this case. 1143 :dismiss_2: 1144 The user dismissed the dialog by pressing the Escape key or some unknown way 1145 on main section. The user remains opted out in this case. 1146 :dismissed_escape_key: 1147 The user dismissed the dialog by pressing the Escape key. The user remains 1148 opted out in this case. This object was removed in Firefox 96.0.2. 1149 :dismissed_other: 1150 The dialog was dismissed in some unknown way. One case where this can happen 1151 is when the dialog is replaced with another higher priority dialog like the 1152 one shown when quitting the app. The user remains opted out in this case. 1153 This object was removed in Firefox 96.0.2. 1154 :learn_more: 1155 The user clicked "Learn more". The user remains opted out in this case. This 1156 object was removed in Firefox 96.0.2. 1157 :learn_more_1: 1158 The user clicked "Learn more" on the introduction section. The user remains 1159 opted out in this case. 1160 :learn_more_2: 1161 The user clicked "Learn more" on the main section. The user remains opted out 1162 in this case. 1163 :not_now: 1164 The dialog was dismissed in some way without opting in. This object was 1165 removed in Firefox 94.0. 1166 :not_now_2: 1167 The user clicked "Not now" link on main section. The user remains opted out in 1168 this case. 1169 :not_now_link: 1170 The user clicked "Not now". The user remains opted out in this case. This 1171 object was removed in Firefox 96.0.2. 1172 :reject_2: 1173 The user rejected the dialog and opted out. 1174 :settings: 1175 The user clicked the "Customize" button. The user remains opted out in this 1176 case. This object was removed in Firefox 96.0.2. 1177 1178 Changelog 1179 Firefox 92.0.1 1180 Introduced. Objects are: ``accept``, ``settings``, ``learn_more``, and 1181 ``not_now``. ``not_now`` is recorded when the dialog is dismissed in any 1182 manner not covered by the other objects. [Bug 1723860_] 1183 1184 Firefox 94.0 1185 Objects changed to: ``accept``, ``dismissed_escape_key``, 1186 ``dismissed_other``, ``learn_more``, ``not_now_link``, and ``settings``. 1187 [Bug 1733687_] 1188 1189 Firefox 96.0.2 1190 Objects changed to: ``accept_2``, ``reject_2``, ``learn_more_2``, 1191 ``close_1``, ``not_now_2``, ``dismiss_1`` and ``dismiss_2``. 1192 [Bug 1745026_] 1193 1194 Firefox 100.0 1195 Objects changed to: ``accept_2``, ``reject_2``, ``learn_more_1``, 1196 ``learn_more_2``, ``close_1``, ``not_now_2``, ``dismiss_1`` and 1197 ``dismiss_2``. 1198 [Bug 1761171_] 1199 1200 Firefox 133.0 1201 Removed. [Bug 1921748_] 1202 1203 .. _1723860: https://bugzilla.mozilla.org/show_bug.cgi?id=1723860 1204 .. _1733687: https://bugzilla.mozilla.org/show_bug.cgi?id=1733687 1205 .. _1745026: https://bugzilla.mozilla.org/show_bug.cgi?id=1745026 1206 .. _1761171: https://bugzilla.mozilla.org/show_bug.cgi?id=1761171 1207 .. _1921748: https://bugzilla.mozilla.org/show_bug.cgi?id=1921748 1208 1209 contextservices.quicksuggest.sponsored_toggled 1210 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1211 1212 This event is recorded when the 1213 ``browser.urlbar.suggest.quicksuggest.sponsored`` pref is toggled. The pref can 1214 be toggled in the following ways: 1215 1216 - The user can toggle it in the preferences UI. 1217 - The user can toggle it in about:config. 1218 1219 The event's objects are the following: 1220 1221 :enabled: 1222 Recorded when the pref is flipped from false to true. 1223 :disabled: 1224 Recorded when the pref is flipped from true to false. 1225 1226 Changelog 1227 Firefox 92.0.1 1228 Introduced. [Bug 1728430_] 1229 1230 Firefox 96.0: 1231 The event is no longer recorded when the user interacts with the online 1232 modal dialog since the ``browser.urlbar.suggest.quicksuggest.sponsored`` 1233 pref is no longer set when the user opts in or out. [Bug 1740965_] 1234 1235 Firefox 133.0 1236 Removed. [Bug 1921748_] 1237 1238 .. _1728430: https://bugzilla.mozilla.org/show_bug.cgi?id=1728430 1239 .. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965 1240 .. _1921748: https://bugzilla.mozilla.org/show_bug.cgi?id=1921748 1241 1242 Environment 1243 ----------- 1244 1245 The following preferences are recorded in telemetry environment data. For 1246 general information on telemetry environment data in Firefox, see the 1247 :doc:`/toolkit/components/telemetry/data/environment` document. 1248 1249 browser.urlbar.quicksuggest.onboardingDialogChoice 1250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1251 1252 This pref records the user's choice in the online modal dialog. If the dialog 1253 was shown multiple times, it records the user's most recent choice. It is a 1254 string-valued pref with the following possible values: 1255 1256 :<empty string>: 1257 The user has not made a choice (e.g., because the dialog hasn't been shown). 1258 :accept: 1259 The user accepted the dialog and opted in. This object was removed in Firefox 1260 96.0.2. 1261 :accept_2: 1262 The user accepted the dialog and opted in. 1263 :close_1: 1264 The user clicked close button or something similar link on the introduction 1265 section. The user remains opted out in this case. 1266 :dismiss_1: 1267 The user dismissed the dialog by pressing the Escape key or some unknown way 1268 on the introduction section. The user remains opted out in this case. 1269 :dismiss_2: 1270 The user dismissed the dialog by pressing the Escape key or some unknown way 1271 on main section. The user remains opted out in this case. 1272 :dismissed_escape_key: 1273 The user dismissed the dialog by pressing the Escape key. The user remains 1274 opted out in this case. This object was removed in Firefox 96.0.2. 1275 :dismissed_other: 1276 The dialog was dismissed in some unknown way. One case where this can happen 1277 is when the dialog is replaced with another higher priority dialog like the 1278 one shown when quitting the app. The user remains opted out in this case. This 1279 object was removed in Firefox 96.0.2. 1280 :learn_more: 1281 The user clicked "Learn more". The user remains opted out in this case. This 1282 object was removed in Firefox 96.0.2. 1283 :learn_more_1: 1284 The user clicked "Learn more" on the introduction section. The user remains 1285 opted out in this case. 1286 :learn_more_2: 1287 The user clicked "Learn more" on the main section. The user remains opted out 1288 in this case. 1289 :not_now_2: 1290 The user clicked "Not now" link on main section. The user remains opted out in 1291 this case. 1292 :not_now_link: 1293 The user clicked "Not now". The user remains opted out in this case. This 1294 object was removed in Firefox 96.0.2. 1295 :reject_2: 1296 The user rejected the dialog and opted out. 1297 :settings: 1298 The user clicked the "Customize" button. The user remains opted out in this 1299 case. This object was removed in Firefox 96.0.2. 1300 1301 Changelog 1302 Firefox 94.0 1303 Introduced. [Bug 1734447_] 1304 1305 Firefox 96.0.2 1306 Added ``accept_2``, ``reject_2``, ``learn_more_2``, ``close_1``, 1307 ``not_now_2``, ``dismiss_1``, ``dismiss_2`` and removed ``accept``, 1308 ``dismissed_escape_key``, ``dismissed_other``, ``learn_more``, 1309 ``not_now_link``, ``settings``. [Bug 1745026_] 1310 1311 Firefox 100.0 1312 Added ``learn_more_1``. [Bug 1761171_] 1313 1314 Firefox 137.0 1315 Removed. [Bug 1936455_] 1316 1317 .. _1734447: https://bugzilla.mozilla.org/show_bug.cgi?id=1734447 1318 .. _1745026: https://bugzilla.mozilla.org/show_bug.cgi?id=1745026 1319 .. _1761171: https://bugzilla.mozilla.org/show_bug.cgi?id=1761171 1320 .. _1936455: https://bugzilla.mozilla.org/show_bug.cgi?id=1936455 1321 1322 browser.urlbar.quicksuggest.dataCollection.enabled 1323 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1324 1325 This boolean pref records whether the user has opted in to data collection for 1326 Firefox Suggest. It is false by default. It is set to true when the user opts in 1327 to the online modal dialog. The user can also toggle it in the preferences UI 1328 and about:config. 1329 1330 Changelog 1331 Firefox 94.0.2 1332 Introduced. [Bug 1735976_] 1333 1334 Firefox 146.0 1335 Removed. [Bug 1995362_] 1336 1337 .. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976 1338 .. _1995362: https://bugzilla.mozilla.org/show_bug.cgi?id=1995362 1339 1340 browser.urlbar.suggest.quicksuggest 1341 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1342 1343 This pref no longer exists and is not recorded. It was replaced with 1344 ``browser.urlbar.suggest.quicksuggest.nonsponsored`` in Firefox 94.0.2. Prior to 1345 94.0.2, this boolean pref recorded whether suggestions in general were enabled. 1346 1347 Changelog 1348 Firefox 92.0.1 1349 Introduced. [Bug 1730721_] 1350 1351 Firefox 94.0.2 1352 Replaced with ``browser.urlbar.suggest.quicksuggest.nonsponsored``. [Bug 1353 1735976_] 1354 1355 .. _1730721: https://bugzilla.mozilla.org/show_bug.cgi?id=1730721 1356 .. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976 1357 1358 browser.urlbar.suggest.quicksuggest.nonsponsored 1359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1360 1361 This boolean pref records whether non-sponsored suggestions are enabled. In both 1362 the offline and online scenarios it is true by default. The user can also toggle 1363 it in the preferences UI and about:config. 1364 1365 Changelog 1366 Firefox 94.0.2 1367 Introduced. It replaces ``browser.urlbar.suggest.quicksuggest``. [Bug 1368 1735976_] 1369 1370 Firefox 96.0: 1371 The pref is now true by default in the online scenario. Previously it was 1372 false by default in online. For users who were enrolled in the online 1373 scenario in older versions and who did not opt in or otherwise enable 1374 non-sponsored suggestions, the pref will remain false when upgrading. For 1375 all other users, it will default to true when/if they are enrolled in 1376 online. [Bug 1740965_] 1377 1378 Firefox 146.0 1379 Removed. [Bug 1995574_] 1380 1381 .. _1735976: https://bugzilla.mozilla.org/show_bug.cgi?id=1735976 1382 .. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965 1383 .. _1995574: https://bugzilla.mozilla.org/show_bug.cgi?id=1995574 1384 1385 browser.urlbar.suggest.quicksuggest.sponsored 1386 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1387 1388 This boolean pref records whether sponsored suggestions are enabled. In both the 1389 offline and online scenarios it is true by default. The user can also toggle it 1390 in the preferences UI and about:config. 1391 1392 Changelog 1393 Firefox 92.0.1 1394 Introduced. [Bug 1730721_] 1395 1396 Firefox 96.0: 1397 The pref is now true by default in the online scenario. Previously it was 1398 false by default in online. For users who were enrolled in the online 1399 scenario in older versions and who did not opt in or otherwise enable 1400 sponsored suggestions, the pref will remain false when upgrading. For all 1401 other users, it will default to true when/if they are enrolled in 1402 online. [Bug 1740965_] 1403 1404 .. _1730721: https://bugzilla.mozilla.org/show_bug.cgi?id=1730721 1405 .. _1740965: https://bugzilla.mozilla.org/show_bug.cgi?id=1740965 1406 1407 The "quick-suggest" Ping 1408 ------------------------ 1409 1410 Firefox Suggest suggestions record telemetry via the `"quick-suggest" ping`_, 1411 which is detailed in the linked Glean Dictionary page. 1412 1413 .. _"quick-suggest" ping: https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/pings/quick-suggest 1414 1415 Changelog 1416 Firefox 116.0 1417 Introduced. [Bug 1836283_] 1418 1419 Firefox 122.0 1420 PingCentre-sent custom pings removed. [Bug `1868580`_] 1421 1422 .. _1836283: https://bugzilla.mozilla.org/show_bug.cgi?id=1836283 1423 .. _1868580: https://bugzilla.mozilla.org/show_bug.cgi?id=1868580 1424 1425 Nimbus Exposure Event 1426 --------------------- 1427 1428 .. note:: 1429 1430 This section is historical and describes how older versions of Firefox 1431 recorded Nimbus exposure events for Firefox Suggest. Recent Firefox versions 1432 no longer record Nimbus exposure events for Firefox Suggest. 1433 1434 A Nimbus exposure event is recorded once per app session when the user first 1435 encounters the UI of an experiment in which they're enrolled. The timing of the 1436 event depends on the experiment and branch. 1437 1438 There are two Nimbus variables that determine the timing of the event: 1439 ``experimentType`` and the deprecated ``isBestMatchExperiment``. To determine 1440 when the exposure event is recorded for a specific experiment and branch, 1441 examine the experiment's recipe and look for one of these variables. 1442 1443 Listed below are the supported values of ``experimentType`` and 1444 ``isBestMatchExperiment`` along with details on when their corresponding 1445 exposure events are recorded. 1446 1447 :experimentType = "best-match": 1448 If the user is in a treatment branch and they did not disable best match, the 1449 event is recorded the first time they trigger a best match; if the user is in 1450 a treatment branch and they did disable best match, the event is not recorded 1451 at all. If the user is in the control branch, the event is recorded the first 1452 time they would have triggered a best match. (Users in the control branch 1453 cannot "disable" best match since the feature is totally hidden from them.) 1454 NOTE: The "Top pick" checkbox, which allowed the user to disable best batch, 1455 was removed in 120. 1456 :experimentType = "modal": 1457 If the user is in a treatment branch, the event is recorded when they are 1458 shown an opt-in modal. If the user is in the control branch, the event is 1459 recorded every time they would have been shown a modal, which is on every 1460 startup where another non-Suggest modal does not appear. 1461 NOTE: This has been removed in Firefox 124. 1462 :isBestMatchExperiment = true: 1463 This is a deprecated version of ``experimentType == "best-match"``. 1464 :All other experiments: 1465 For all other experiments not listed above, the event is recorded the first 1466 time the user triggers a Firefox Suggest suggestion. 1467 1468 Changelog 1469 Firefox 92.0 1470 Introduced. The event is always recorded the first time the user triggers 1471 a Firefox Suggest suggestion regardless of the experiment they are enrolled 1472 in. [Bug 1724076_, 1727392_] 1473 1474 Firefox 99.0 1475 The ``isBestMatchExperiment = true`` case is added. [Bug 1752953_] 1476 1477 Firefox 100.0 1478 The ``experimentType = "modal"`` case is added. 1479 ``isBestMatchExperiment = true`` is deprecated in favor of 1480 ``experimentType = "best-match"``. [Bug 1760596_] 1481 1482 Firefox 124.0 1483 The ``experimentType = "modal"`` case is removed. 1484 1485 Firefox 135.0 1486 The ``experimentType`` Nimbus variable is removed. By this time it already 1487 not been referenced in Firefox code for quite a while. [Bug 1932502_] 1488 1489 .. _1724076: https://bugzilla.mozilla.org/show_bug.cgi?id=1724076 1490 .. _1727392: https://bugzilla.mozilla.org/show_bug.cgi?id=1727392 1491 .. _1752953: https://bugzilla.mozilla.org/show_bug.cgi?id=1752953 1492 .. _1760596: https://bugzilla.mozilla.org/show_bug.cgi?id=1760596 1493 .. _1932502: https://bugzilla.mozilla.org/show_bug.cgi?id=1932502 1494 1495 Merino Search Queries 1496 --------------------- 1497 1498 Merino is a Mozilla service that provides Firefox Suggest suggestions. Along 1499 with remote settings on the client, it is one of two possible sources for 1500 Firefox Suggest. When Merino integration is enabled on the client and the user 1501 has opted in to Firefox Suggest data collection, Firefox sends everything the 1502 user types in the address bar to the Merino server. In response, Merino finds 1503 relevant search results from its search providers and sends them to Firefox, 1504 where they are shown to the user in the address bar. 1505 1506 The user opts in to Firefox Suggest data collection when they either opt in to 1507 the online modal dialog or they enable Firefox Suggest data collection in the 1508 preferences UI. 1509 1510 Merino queries are not telemetry per se but we include them in this document 1511 since they necessarily involve data collection. 1512 1513 Merino API 1514 ~~~~~~~~~~ 1515 1516 Data that Firefox sends to the Merino server is summarized below. When Merino 1517 integration is enabled on the client and the user has opted in to Firefox 1518 Suggest data collection, this data is sent with every user keystroke in the 1519 address bar. 1520 1521 For details on the Merino API, see the `Merino documentation`_. 1522 1523 .. _Merino documentation: https://mozilla-services.github.io/merino/api.html#suggest 1524 1525 Search Query 1526 The user's search query typed in the address bar. 1527 1528 API parameter name: ``q`` 1529 1530 Session ID 1531 A UUID that identifies the user's current search session in the address bar. 1532 This ID is unique per search session. A search session ends when the focus 1533 leaves the address bar or a timeout of 5 minutes elapses, whichever comes 1534 first. 1535 1536 API parameter name: ``sid`` 1537 1538 Sequence Number 1539 A zero-based integer that is incremented after a response is received from 1540 Merino. It is reset at the end of each search session along with the session 1541 ID. 1542 1543 API parameter name: ``seq`` 1544 1545 Client Variants 1546 Optional. A list of experiments or rollouts that are affecting the Firefox 1547 Suggest user experience. If Merino recognizes any of them, it will modify its 1548 behavior accordingly. 1549 1550 API parameter name: ``client_variants`` 1551 1552 Providers 1553 Optional. A list of providers to use for this request. If specified, only 1554 suggestions from the listed providers will be returned. Otherwise Merino will 1555 use a default set of providers. 1556 1557 API parameter name: ``providers``