♻️ Re-rethink the onboarding process

[shankari]

We last rethought the onboarding process in Spring 2023
Related issue: #850, particularly starting at #850 (comment)
Related PR (scroll down for discussion about links versus copy-paste): e-mission/e-mission-phone#973

We think that the changes have generally been positive, but we have still encountered some confusion with the new workflow.
Concretely:

• in group settings for autogenerated opcodes, we display a QR code for the join page in a presentation. But then this is again different from the opcode QR code, so the participants try to scan the join page QR code, which fails.
• at least twice, admins have shared an real opcode with participants, and have ended up with two people logging in with the same opcode

It seems like with the previous changes, we got the pre-generated opcode case working smoothly, but autogenerated could be improved

• Suggestion from @JGreenlee: have the join page generate the opcode only after the user clicks on a button ("Click to generate opcode")
• Suggestion from @shankari while typing this: have the autogenerated opcode be something that is static (like nrelop_dfc-fermata_default_autogen. In the onboarding, replace the 'autogen' string with an actually autogenerated opcode. On the server, reject any opcodes that have the 'autogen' opcode.
  • Pro: users would have to scan a single opcode that could also be statically shared
  • Con: the opcode that users see won't be the same as the one in the app

@jiji14 @louisg1337 @Abby-Wheelis thoughts on UX welcome!

[Abby-Wheelis]

have the autogenerated opcode be something that is static

I think would solve the problems we've encountered with confusion over "scan to access the join page" then "copy and paste the string" that I have experienced while onboarding users, and would still allow for the "distribute personal opcodes" option. I don't think the generation in the app would be all that confusing, people don't seem to pay much attention to the opcode anyways until I tell them to save it. So for the "presenting" version of onboarding, I think this would be helpful.

It would prevent anyone who might have been saving the opcode to/from their laptop to do that anymore, do we have an idea or any way of knowing if anyone was saving them that way? I could also see confusion if people were interacting with the join page independently, I wonder if people would think the autogen portion was a mistake or if we could label the opcode in such a way that it's clear the app will generate the rest.

[louisg1337]

I think all of the above ideas are great and could definitely make the onboarding process smoother. Here is my take on how we could potentially make it easier for users.

A lot of the confusion comes from the op code website as Abby mentioned yesterday. It definitely makes sense too because there is that added layer of the user needing to get that op code into their app some how, which can for sure add confusion. I was thinking what if we just made the entire onboarding process be on the app so there is no need for scanning or copying OP Codes? My thought process was that we can auto generate the OP Codes in the app itself, and do what Jack mentioned, make a button saying Generate UNIQUE OPCode or something like that. To deal with the study specific op codes, I say we just add a screen, before the generate opcode one, that asks for a study identifier. Here is a rough visual implementation of the flow of the onboarding process I had in mind.

I feel like if we were to do it this way it would be a lot easier for Abby to guide everyone through it as everyone stays on the app the whole time, and the only real help they need is to type in the study identifier.

[shankari]

The problem with asking people to type things in is that they can make mistakes while typing - e.g. dfc_fermata versus dfc-fermata versus dfc_germata ...

Maybe if we can validate as well, that would work

[louisg1337]

Thats a great point, I think that could definitely cause some confusion. Maybe we can make the study codes the users are supposed to input a short hand version of the one we maintain on the backend, and have some type of mapping between the two (i.e. the user would input DFC, but we represent it as dfc_fermata in the backend like we already do). This mapping would give us that validation aspect as we could provide an error message if the study code they entered doesn't exist.

[JGreenlee]

After thinking about this, I agree that for studies where autogen=true we should go back to generating the OPcodes on the phone.

• have the autogenerated opcode be something that is static (like nrelop_dfc-fermata_default_autogen. In the onboarding, replace the 'autogen' string with an actually autogenerated opcode. On the server, reject any opcodes that have the 'autogen' opcode.

How about having the QR code on the join page not be an OPcode at all?
Currently, the QR code on the join page is something like nrelopenpath://login_token?token=nrelop_dfc-fermata_default_randomlyGeneratedString.
Why not have it be something like nrelopenpath://join?study=dfc-fermata ?

This way there will be no need for a "stub" OPcode that could potentially confuse people. No OPcode will even exist until it is generated on the phone

[JGreenlee]

• in group settings for autogenerated opcodes, we display a QR code for the join page in a presentation. But then this is again different from the opcode QR code, so the participants try to scan the join page QR code, which fails.

We would still have this problem though, where there are 2 QR codes / links.

The first QR code (included in a group presentation) is an https:// link; it tells the participant's browser to open the join webpage. The user installs OpenPATH. From inside the app, they can scan the second QR code, which is an nrelopenpath:// link; it tells OpenPATH to join a particular study.

What we'd really like is 1 QR code / link, which is an https:// link, that will automatically open the OpenPATH app and join a study if OpenPATH is installed; or go to the join webpage if OpenPATH isn't installed. We can't do this yet because it would require deferred deep linking.

Maybe the next best thing we can do is have the in-app QR scanner work with the first QR code, eliminating the need for a second QR code.
The first scan will take participants to the join page where they can read about the app. They are instructed to install the app. Then they can open the app and scan the same QR code, this time from within the app; it will join the study and generate an opcode for them.

We can also provide an nrelopenpath:// hyperlink (not QR code) on the join webpage. If viewing the join webpage from their phone, and they have OpenPATH installed, they can click that to immediately join a study.

---

[Abby-Wheelis]

We would still have this problem though, where there are 2 QR codes / links.

I don't know that we would have to have 2 links in the presentation, since the only reason (at least when I was doing this) that I was sending users to the join page was to get an OpCode. I'm imagining, with the "autogen is generated in the app" paradigm, that people could install the app directly from the app store, then scan the code from the screen. This does circumnavigate the join page, but in the presentation setting people aren't reading it anyways, and we can include it and the link to the general openpath page as options to learn more. The summary and privacy policy show the important study specific information in the app.

With your proposal above, it looks like we could still do it that way, and the code would do something no matter if you scanned it with your camera or with openPATH, which might be helpful.

If we could boil the "group" onboarding process down to "download the app from the store, scan the code on the screen, follow the prompts in the app" I think that would resolve most of the confusion