Bugzilla

# Onboarding Redesign (Cards)

The current Onboarding Flow is an embedded listview that includes a variety of educational cards to help a user learn about core functionality. However, these cards are easy to miss for new users.

We want to create a new design for the first-run Onboarding Flow using the same fullscreen cards leveraged in MR 2022, allowing users to swipe between these items.

This epic includes two parts:
* Technical restructuring of the onboarding cards so that different layouts and actions can all use the same infrastructure
* An introduction of <3? number still TBD> basic onboarding cards. (Note: one of the cards that must always be included is the privacy notice)

This should be released initially as an on/off experiment, if possible. The subsequent epic, "Nimbus-powered Onboarding", will make those basic onboarding cards more dynamic by allowing their presence, order, and contents to be powered by Nimbus.

# Onboarding Redesign (Cards)

The current Onboarding Flow is an embedded listview that includes a variety of educational cards to help a user learn about core functionality. However, these cards are easy to miss for new users.

We want to create a new design for the first-run Onboarding Flow using the same fullscreen cards leveraged in MR 2022, allowing users to swipe between these items.

This epic includes two parts:
* Technical restructuring of the onboarding cards so that different layouts and actions can all use the same infrastructure
* An introduction of 4 basic onboarding cards. (Note: one of the cards that must always be included is the privacy notice). The initial cards are:
  * Notification opt-in
  * Set to default
  * Sync sign-in
  * Privacy policy
* It is assumed that we will later add new types of cards that could be incorporated into this onboarding flow via experiments (see [1818296](https://bugzilla.mozilla.org/show_bug.cgi?id=1818296) for more info)

This should be released initially as an on/off experiment, if possible. The subsequent epic, "Nimbus-powered Onboarding", will make those basic onboarding cards more dynamic by allowing their presence, order, and contents to be powered by Nimbus.

# Onboarding Redesign (Cards)

The current Onboarding Flow is an embedded listview that includes a variety of educational cards to help a user learn about core functionality. However, these cards are easy to miss for new users.

We want to create a new design for the first-run Onboarding Flow using the same fullscreen cards leveraged in MR 2022, allowing users to swipe between these items.

This epic includes two parts:
* Technical restructuring of the onboarding cards so that different layouts and actions can all use the same infrastructure
* An introduction of 4 basic onboarding cards. (Note: one of the cards that must always be included is the privacy notice). The initial cards are:
  * Notification opt-in
  * Set to default
  * Sync sign-in
  * Privacy policy
* It is assumed that we will later add new types of cards that could be incorporated into this onboarding flow via experiments (see [1818296](https://bugzilla.mozilla.org/show_bug.cgi?id=1818296) for more info)
* Note: PM should provide the starting order for these cards. (The subsequent ticket will allow us to experiment with the order)

This should be released initially as an on/off experiment, if possible. The subsequent epic, "Nimbus-powered Onboarding", will make those basic onboarding cards more dynamic by allowing their presence, order, and contents to be powered by Nimbus.

# Onboarding Redesign (Cards)

The current Onboarding Flow is an embedded listview that includes a variety of educational cards to help a user learn about core functionality. However, these cards are easy to miss for new users.

We want to create a new design for the first-run Onboarding Flow using the same fullscreen cards leveraged in MR 2022, allowing users to swipe between these items.

### Behavior Spec

1. Onboarding is shown to new users. (not during app updates)
1. Show three cards, in this order:
    1. Set to default (+ privacy policy)
    1. Sign in to sync
    1. Notification permissions
1. There should be no "x" button on the card, and onboarding should be undismissable. The back button should close the app, rather than dismissing the onboarding interstitial.
1. If user leaves onboarding without finishing it, it should re-appear the next time they enter the app. (no need to keep track of where they were in the onboarding - if the app has been killed in the background, they can just start from the beginning again).
1. We don't need to deal with "smart" behavior around cards showing or hiding based on system state (e.g., if they somehow already have notification permissions enabled, the card should still appear in the flow. They can just continue past it). This might be an opportunity for a future UX optimization.
1. Users should be able to swipe backwards. If it's straightforward to do, swiping forward should be prohibited. (See note in "topics for product" for more info)
1. The 'notification permissions' card should not appear for devices below Android 13. (note in "topics for product" section)

### Topics for product:

* Swiping behaviors:
  * Swiping forward: If possible, we'll restrict users from swiping forward (to ensure they click one of the two buttons); but if it adds technical complexity, we'll defer that to a future version.
  * Swiping backward: should be enabled, in case a user leaves the sign in, set to default, or notification permission flow accidentally, and wants to do it again.
* **Warning about potential telemetry confusion**: Android 12 and below doesn't require notification permissions, so we won't show them the permission prompt card - users on these devices will only see 2 cards, not 3. We need to account for this in any evaluations we run, because it would be easy to misunderstand that a lack of positive action on these devices might imply user drop-off or negative action.



### Experiment setup:

This release of the new onboarding feature should be able to be enabled or disabled by Nimbus:
* The control branch should be the _current_ onboarding experience (listview + notification permission prompt)
* The treatment branch should be the updated onboarding experience (card-based redesign)

The [next version of this feature](https://bugzilla.mozilla.org/show_bug.cgi?id=1818296) will enable customizing the contents of the onboarding flow through Nimbus.

---

> *Update, March 10:* we aren't ready for today's string freeze, but we've been brainstorming some ideas about whether it's possible to release this sooner than v113 by localizing & enabling the redesign for a small subset of locales. I currently have no idea if this is even possible.
> * If we do some limited localization, can we use Nimbus to target them? Need to coordinate this between Delphine, Flod, & Daniela.
>   * Specific locales expected to be supported: marketing focused locales: 
>     * en-*
>     * fr-*
>     * de
>     * es-*
>     * it
>   * So, for engineering: we'd need to land this, then request localization for those limited locales (from Delphine and/or Flod), and we'd need to make sure the experiment is set up to only target those locales (Daniela can help there, particularly to coordinate with Shell). But as of 3/10, not sure if this idea is viable.

### Feature Outline

The current Onboarding Flow is an embedded listview that includes a variety of educational cards to help a user learn about core functionality. However, these cards are easy to miss for new users.

We want to create a new design for the first-run Onboarding Flow using the same fullscreen cards leveraged in MR 2022, allowing users to swipe between these items.

### Behavior Spec

1. Onboarding is shown to new users. (not during app updates)
1. Show three cards, in this order:
    1. Set to default (+ privacy policy)
    1. Sign in to sync
    1. Notification permissions
1. There should be no "x" button on the card, and onboarding should be undismissable. The back button should close the app, rather than dismissing the onboarding interstitial.
1. If user leaves onboarding without finishing it, it should re-appear the next time they enter the app. (no need to keep track of where they were in the onboarding - if the app has been killed in the background, they can just start from the beginning again).
1. We don't need to deal with "smart" behavior around cards showing or hiding based on system state (e.g., if they somehow already have notification permissions enabled, the card should still appear in the flow. They can just continue past it). This might be an opportunity for a future UX optimization.
1. Users should be able to swipe backwards. If it's straightforward to do, swiping forward should be prohibited. (See note in "topics for product" for more info)
1. The 'notification permissions' card should not appear for devices below Android 13. (note in "topics for product" section)

### Topics for product:

* Swiping behaviors:
  * Swiping forward: If possible, we'll restrict users from swiping forward (to ensure they click one of the two buttons); but if it adds technical complexity, we'll defer that to a future version.
  * Swiping backward: should be enabled, in case a user leaves the sign in, set to default, or notification permission flow accidentally, and wants to do it again.
* **Warning about potential telemetry confusion**: Android 12 and below doesn't require notification permissions, so we won't show them the permission prompt card - users on these devices will only see 2 cards, not 3. We need to account for this in any evaluations we run, because it would be easy to misunderstand that a lack of positive action on these devices might imply user drop-off or negative action.



### Experiment setup:

This release of the new onboarding feature should be able to be enabled or disabled by Nimbus:
* The control branch should be the _current_ onboarding experience (listview + notification permission prompt)
* The treatment branch should be the updated onboarding experience (card-based redesign)

The [next version of this feature](https://bugzilla.mozilla.org/show_bug.cgi?id=1818296) will enable customizing the contents of the onboarding flow through Nimbus.

---
Update, March 20: below section is no longer relevant. We're just aiming to land for v113 & allowing localization to happen normally.

> ~*Update, March 10:* we aren't ready for today's string freeze, but we've been brainstorming some ideas about whether it's possible to release this sooner than v113 by localizing & enabling the redesign for a small subset of locales. I currently have no idea if this is even possible.~
> * ~If we do some limited localization, can we use Nimbus to target them? Need to coordinate this between Delphine, Flod, & Daniela.~
>   * ~Specific locales expected to be supported: marketing focused locales:~
>     * ~en-*~
>     * ~fr-*~
>     * ~de~
>     * ~es-*~
>     * ~it~
>   * ~So, for engineering: we'd need to land this, then request localization for those limited locales (from Delphine and/or Flod), and we'd need to make sure the experiment is set up to only target those locales (Daniela can help there, particularly to coordinate with Shell). But as of 3/10, not sure if this idea is viable.~