bce749c8e1
We'll stop dispatching "keypress" event for non-printable keys and key combinations in the default event group of web content. Therefore, onbording.js needs to stop handling some keys with "keypress" event listener. This patch makes add a "keydown" event listener, handleKeydown(), and make it handle only non-printable keys. Note that we'll keep dispatching "keypress" event for " " and "Enter". So, we can keep handling them in "keypress" event listener. MozReview-Commit-ID: 1jFIv9N03fa --HG-- extra : rebase_source : 8acabac7ae5c06b527a9fad0fb0fb7b3a2cc5a61 |
||
|---|---|---|
| .. | ||
| content | ||
| locales | ||
| test | ||
| bootstrap.js | ||
| data_events.md | ||
| install.rdf.in | ||
| jar.mn | ||
| moz.build | ||
| OnboardingTelemetry.jsm | ||
| OnboardingTourType.jsm | ||
| README.md | ||
Onboarding
System addon to provide the onboarding overlay for user-friendly tours.
How to show the onboarding tour
Open about:config page and filter with onboarding keyword. Then set following preferences:
browser.onboarding.disabled = false
browser.onboarding.tour-set = "new" // for new user tour, or "update" for update user tour
And make sure the value of browser.onboarding.tourset-verion and browser.onboarding.seen-tourset-verion are the same.
How to show the onboarding notification
Besides above settings, notification will wait 5 minutes before showing the first notification on a new profile or the updated user profile (to not put too much information to the user at once).
To manually remove the mute duration, set pref browser.onboarding.notification.mute-duration-on-first-session-ms to 0 and notification will be shown at the next time you open about:home or about:newtab.
How to show the snippets
Snippets (the remote notification that handled by activity stream) will only be shown after onboarding notifications are all done. You can set preference browser.onboarding.notification.finished to true to disable onboarding notification and accept snippets right away.
Architecture
During booting from bootstrap.js, OnboardingTourType.jsm will check the onboarding tour type (new and update are supported types) and set required initial states into preferences.
Everytime about:home or about:newtab page is opened, onboarding.js is injected into that page via frame scripts.
Then in onboarding.js, all tours are defined inside of onboardingTourset dictionary. getTourIDList function will load tours from proper preferences. (Check How to change the order of tours section for more detail).
When user clicks the action button in each tour, We use UITour to highlight the correspondent browser UI element. The UITour client is bundled in onboarding addon via jar.mn.
Landing rules
We would apply some rules:
- To avoid conflict with the origin page, all styles and ids should be formatted as
onboarding-*. - For consistency and easier filtering, all strings in
localesshould be formatted asonboarding.*. - For consistency, all related preferences should be formatted as
browser.onboarding.*. - For accessibility, images that are for presentation only should have
role="presentation"attribute.
How to change the order of tours
Edit browser/app/profile/firefox.js and modify browser.onboarding.newtour for the new user tour or browser.onboarding.updatetour for the update user tour. You can change the tour list and the order by concate tourIds with , sign. You can find available tourId from onboardingTourset in onboarding.js.
How to pump tour set version after update tours
We only update the tourset version when we have different update tourset. Update the new tourset does not require update the tourset version.
The tourset version is used to track the last major tourset change version. The tourset-version pref store the major tourset version (ex: 1) but not the current browser version. When browser update to the next version (ex: 58, 59) the tourset pref is still 1 if we didn't do any major tourset update.
Once the tour set version is updated (ex: 2), onboarding overlay should show the update tour to the updated user (ex: update from v56 -> v57), even when user has watched the previous tours or preferred to hide the previous tours.
Edit browser/app/profile/firefox.js and set browser.onboarding.tourset-version as [tourset version] (in integer format).
For example, if we update the tourset in v60 and decide to show all update users the tour, we set browser.onboarding.tourset-version as 3.
Icon states
Onboarding module has two states for its overlay icon: default and watermark.
By default, it shows default state.
When either tours or notifications are all completed, the icon changes to the watermark state.
The icon state is stored in browser.onboarding.state.
When tourset-version is updated, or when we detect the tour-type is changed to update, icon state will be changed back to the default state.
Customizable preferences
Here are current support preferences that allow to customize the Onboarding's behavior.
| PREF | DESCRIPTION | DEFAULT |
|---|---|---|
browser.onboarding.enabled |
disable onboarding experience entirely | true |
browser.onboarding.notification.finished |
Decide if we want to hide the notification permanently. | false |
browser.onboarding.notification.mute-duration-on-first-session-ms |
Notification mute duration. It also effect when the speech bubble is hidden and turned into the blue dot | 300000 (5 Min) |
browser.onboarding.notification.max-life-time-all-tours-ms |
Notification tours will all hide after this period | 1209600000 (10 Days) |
browser.onboarding.notification.max-life-time-per-tours-ms |
Per Notification tours will hide and show the next tour after this period | 432000000 (5 Days) |
browser.onboarding.notification.max-prompt-count-per-tour |
Each tour can only show the specific times in notification bar if user didn't interact with the tour notification. | 8 |
browser.onboarding.newtour |
The tourset of new user tour. | performance,private,screenshots,addons,customize,default |
browser.onboarding.newtour.tooltip |
The string id which is shown in the new user tour's speech bubble. The preffered length is 2 lines. Should use %S to denote Firefox (brand short name) in string, or use %1$S if the name shows more than 1 time. |
onboarding.overlay-icon-tooltip2 |
browser.onboarding.updatetour |
The tourset of new user tour. | performance,library,screenshots,singlesearch,customize,sync |
browser.onboarding.updatetour.tooltip |
The string id which is shown in the update user tour's speech bubble. The preffered length is 2 lines. Should use %S to denote Firefox (brand short name) in string, or use %1$S if the name shows shows more than 1 time. |
onboarding.overlay-icon-tooltip-updated2 |
browser.onboarding.default-icon-src |
The default icon url. Should be svg or at least 64x64 | chrome://branding/content/icon64.png |
browser.onboarding.watermark-icon-src |
The watermark icon url. Should be svg or at least 64x64 | resource://onboarding/img/watermark.svg |