1867871 - Documentation: update the targeting page docs

Status: NEW

(Firefox :: Messaging System, task, P2)

Description

[Vtay]

targeting locales in experiment =
current UI locale! (and when we target locale in experiments, we are targeting UI locales).

• value is coming from locale Services call here (https://searchfox.org/mozilla-central/source/browser/components/newtab/lib/ASRouterTargeting.jsm#528)

It should return the current UI locale (the first match between available locales and requested locales) https://searchfox.org/mozilla-central/source/intl/locale/mozILocaleService.idl#128-146

Comment 1

[Dan Mosedale (:dmosedale, :dmose)]

Things worth adding:

• describing "current" and "home" regions so it's possible to understand the behavior of the targeting, along with the fact that this targeting exposes "current".
• include something like flod's description in comment 0:

It should return the current UI locale (the first match between available locales and requested locales) https://searchfox.org/mozilla-central/source/intl/locale/mozILocaleService.idl#128-146

But match it up with preference screenshots and possibly more detailed text to give readers sufficient context to understand what that means.

Comment 2

[Dan Mosedale (:dmosedale, :dmose)]

isFirstRun is not documented on the targeting page at all. My understanding is that because isFirstRun is passed by the installer, it probably won't work with other installation mechanisms (MSIX, Linux packaging stuff, ...). Worth verifying and adding.

Comment 3

[Shane Hughes [:aminomancer]]

(In reply to Dan Mosedale (:dmosedale, :dmose) from comment #2)

isFirstRun is not documented on the targeting page at all. My understanding is that because isFirstRun is passed by the installer, it probably won't work with other installation mechanisms (MSIX, Linux packaging stuff, ...). Worth verifying and adding.

Targeting first run is currently somewhat informal. isFirstRun is only defined in the nimbus client targeting context (but not in the messaging system context). It returns the value of a pref. I think this pref starts as true, but then gets set to false after normandy is initialized for the first time. So it's only true during that first initialization of experiments (and other older types of studies).

isFirstStartup is also only defined in the nimbus client context. I think this is the one you're actually supposed to use in experiment advanced targeting configs, since the other one relies on an old normandy pref. From what I heard recently from Beth, this normandy code will be removed by the end of the year. It's the one that actually reflects the state of the --first-startup flag.

But in messages, we've been using !previousSessionEnd to exclude first run. We're not sure how reliable this is. It's stored in ASRouter's IndexedDB so, while it's unlikely to be erroneously cleared, I think it is per-profile, unlike isFirstStartup which is only true for that specific firefox launch. And there might be situations where it fails to be created, like maybe if Firefox crashes, the ASRouter uninit code does not run.

If we do include nimbus-only targeting attributes like isFirstStartup in the source doc, we should add a

⚠ NOTE: This targeting attribute is only available for the JEXL expressions of experiments' advanced targeting configs, which are defined in the experimenter repository. Targeting expressions for messages do not have access to this attribute.

I'm not sure if we can expose this attribute to messages, because it's only true for a brief window during startup. On the first run, it starts out as true, and then the code awaits the first evaluation of nimbus enrollments, and when that finishes, its value changes.

However, we could store some state in the FirstStartup module to indicate that it was initialized in this session. It doesn't init at all if it's not first startup. So an initialized property would suffice to permanently record that it is the first run. In fact, we could probably use FirstStartup.state !== FirstStartup.NOT_STARTED. But as you noted, there are ways to run Firefox where we may not have control of the command line arguments for the first firefox process. I guess you could combine the two so they cover some of each others' weaknesses: !isFirstStartup && !previousSessionEnd. But that still excludes situations where it's the first time a profile is run, but not the first time this firefox installation is run.

Perhaps this is the sort of thing we can rely on the new profile management state storage system for, to store a variable across all profiles.

Comment 4

[Dan Mosedale (:dmosedale, :dmose)]

Thanks for all the super helpful context, Shane!

I've spun fixing and documenting the general problem in comment 2 into bug 1929652, since there's clearly a lot more to do here than just clean up documentation.

As far as what we do for the documentation for now, maybe we just add documentation for isFirstStartup (nimbus-only) with text saying "be sure to review bug 1929652 before using this".