Refactored Onboarding

[overheadhunter]

This updates the "setup" wizard, following feedback from usability tests. It is now a single stage wizard emphasizing the importance of the setup code.

While it still allows changing the browser name, it applies a sensible default based on the user agent string:

hub/frontend/src/components/InitialSetup.vue

Lines 181 to 191 in e5812bc

	var match = navigator.userAgent.toLowerCase().match(/(android|iphone|opr|edge|chrome|safari|firefox)/) || [''];
	switch (match[0]) {
	case 'android': return 'Android';
	case 'iphone': return 'iPhone';
	case 'opr': return 'Opera';
	case 'edge': return 'Edge';
	case 'chrome': return 'Chrome';
	case 'safari': return 'Safari';
	case 'firefox': return 'Firefox';
	default: return 'Browser';
	}

Furthermore it introduces a checkbox to raise more awareness of the significance of the setup code.

All labels are still WiP, most notably the setupCode = 'Account Key'. We're still looking for a good phrase which satisfies these requirements:

• it is concise
• it transports the message that it should be kept secret
• it explains what it is used for (linking apps to the user account)
• it does not contain "password" or "passphrase" to avoid confusion with the IDP's account password

---

This also fixes an "invalid state" where the browser still has a key pair but got deleted from the user's profile. Re-authorizing the same browser does now work again.

Tasks

Edit tasklist title

Beta Give feedback Tasklist Tasks, more options

• Rename
• Copy markdown
• Delete tasklist

Delete tasklist

Delete tasklist block?

Are you sure? All relationships in this tasklist will be removed.

Cancel Delete

1. one can still open `/app/setup` despite the browser already being set up

   one can still open /app/setup despite the browser already being set up
   Options

   • Convert to issue
   • Toggle completion
   • Rename
   • Remove
2. remove unique constraint for device names

   remove unique constraint for device names
   Options

   • Convert to issue
   • Toggle completion
   • Rename
   • Remove
3. add "not you? change user" link

   add "not you? change user" link
   Options

   • Convert to issue
   • Toggle completion
   • Rename
   • Remove

Add item to Tasks

[overheadhunter]

German translation is mostly still missing, but we should agree on the English labels first.

[tobihagemann]

Would love to test this, but I can't get past the following error with a fresh installation:

Fetching data failed
Cannot read properties of undefined (reading 'publicKey')

The error occurs here:

https://github.com/cryptomator/hub/pull/223/files#diff-3e773d478d54a16170ac8b7b79f6156a1da1548a34a76de0062c18c517bdbcebR221

Console log:

Retrieving setup information failed. TypeError: Cannot read properties of undefined (reading 'publicKey')
    at BrowserKeys.id (crypto.ts:491:89)
    at fetchData (InitialSetup.vue:221:41)

[overheadhunter]

Cannot read properties of undefined

I guess we need some "create or load" logic here... Looking into it tomorrow!

[infeo]

I looked at it from UX side (no real code review). What came to my mind is:

• Print button for account key
• If there is a warning sign, it should also be a warning color imho. Either
  • replace by info sign
  • change color
• first paragraph should be shortened:

This is your first login to Hub. We created your personal Account key:
[KEY]
Bla bla store it safely...

• Maybe underline the Browsername to let the users notice its clickable?

Also, what do you think about a redirect to the user profile page after onboarding? That way the user also finds the account key.

[overheadhunter]

I looked at it from UX side (no real code review). What came to my mind is:

• Print button for account key

Can be a follow-up PR. Keep in mind that other than a recovery key, the account key can be changed any time. Not sure if a print-out is the best storage option. Instead it would be nice to optimize the page for password managers to pick up the password and offer to store it?

• If there is a warning sign, it should also be a warning color imho. Either

  • replace by info sign
  • change color

I'm still looking for a completely different iconography here. Ideally, we should put the focus on "what the setup code is used for". Maybe we can add some illustration of various devices and change the text to something like:

You need your Account Key to authorize access to your account from other browsers, apps or devices. You can see a list of authorized devices on your profile page. This browser will appear under the name Chrome 🖊️.

• first paragraph should be shortened:

This is your first login to Hub. We created your personal Account key:
[KEY]
Bla bla store it safely...

Experience tells me that there is a maximum amount of text that users can handle before they switch to a "just click next" behaviour. In order to split up all relevant information into digestible chunks, I decided to use the space above the setup code to explain WHAT it is and the part below to explain its PURPOSE.

"Hi, this is a Plumbus. [picture] It can be used for ..."

• Maybe underline the Browsername to let the users notice its clickable?

Since we want to put the focus purely on the account key (as per feedback from usability tests with the old form), it was my intention to find a balance between completely hiding this feature and still offering users looking for it a way to easily recognize it. I tried underline before but imo it was too much. So I deemed monospace + pen icon sufficient. But this calls for another round of usability testing, specifically asking users to rename their browser during initial setup.

Also, what do you think about a redirect to the user profile page after onboarding? That way the user also finds the account key.

Yes, probably a good idea.

[overheadhunter]

Next revision, breaking the text down in even smaller chunks of information:

[infeo]

Looks good! My thoughts:

• Should we mention, that the account key can be viewed from authorized devices in the profile page? This is quite the lengthy information, don't know if there is space for that
• "... list of authorized apps and browsers on your profile ..."
• icon of third item should match the device type browser icon
• Wording for the first sentece. I would stick to directly address the user, how about "This is your first login to Cryptomator Hub. We created your unique, secret account key for you:" ?

[tobihagemann]

Is this intentional that you're moving away from the "device" wording? It has somehow been replaced with "app" (e.g., other apps or authorized apps). On the profile page, the heading is "Authorized Devices and Browsers". Do you think that "Authorized Apps and Browsers" makes more sense?

I actually like the first sentence with "every user gets a unique ...". It's short and gives you a broader context that you're not the only one.

[overheadhunter]

Is this intentional that you're moving away from the "device" wording? It has somehow been replaced with "app" (e.g., other apps or authorized apps). On the profile page, the heading is "Authorized Devices and Browsers". Do you think that "Authorized Apps and Browsers" makes more sense?

I'm still experimenting with the wording. "Device" was great when it was reasonable to assume there will only ever be one app (namely the Cryptomator app) per device. When we added browsers, this concept crumbles. Let's assume we stick with "device", a user might name their browser "MacBook". Later, when attempting to add the desktop app, they may run into naming conflicts.

And yes, if we agree on a good name, we should rename it in all places (but maybe keep the device-based name presets in the Cryptomator apps).

[tobihagemann]

Some questions on the open tasks:

one can still open /app/setup despite the browser already being set up

You added // TODO: move "already set up" case to setup component. Is there any reason why we shouldn't solve this like before, using a beforeEnter?

if we keep the unique constraint for device names, we need a proper error text

I'm inclined to remove the constraint. What do you think?

redirect to profile?

I'm against this. Users should be redirected to the "main" page after setup so that they can get familiar with managing vaults. If we find out that users are still confused by the account key after this refactoring, we can discuss this further.

[overheadhunter]

one can still open /app/setup despite the browser already being set up

You added // TODO: move "already set up" case to setup component. Is there any reason why we shouldn't solve this like before, using a beforeEnter?

iirc, the beforeEnter caused overhead on every single routing event. But there is lots of potential for improvement here (i.e. keeping certain user-related state in-memory).

if we keep the unique constraint for device names, we need a proper error text

I'm inclined to remove the constraint. What do you think?

I agree. @infeo opposed, maybe he can add some arguments? 😉

redirect to profile?

I'm against this. Users should be redirected to the "main" page after setup so that they can get familiar with managing vaults. If we find out that users are still confused by the account key after this refactoring, we can discuss this further.

ack

[infeo]

I agree. @infeo opposed, maybe he can add some arguments? 😉

Not technically. It is just the feeling, as a user looking at my devices, i could see several entries named "Browser XY". But we have for distinction the creation date, right? If so, we can drop it imho.

[tobihagemann]

In my opinion, we need more device metadata for better distinction (e.g., last access date, last IP address, operating system). But yeah, then let's remove the name constraint and think about this later.

[SailReal]

Please don't merge yet, found some bugs I'm currently fixing, see e.g.

Screencast.from.2023-10-30.14-48-35.webm

[SailReal]

Before I adjust this, what do you think, but IMO the "register first device" screen and the "register another device" screen should look more similar?