Add first-run onboarding guide by bjorkert · Pull Request #673 · loopandlearn/LoopFollow

bjorkert · 2026-06-14T19:08:36Z

Adds a friendly, step-based first-run onboarding wizard, shown once on launch and skippable (with a prominent Skip for users who are already configured).

Flow

Welcome → choose a data source → connect (Nightscout or Dexcom Share) → units & metrics → a few useful alarms → done.

Highlights

Nightscout token from API secret: on the connect step, users can paste a token or have LoopFollow create a read-only one from their site's API secret. The secret only authorizes the request and is never stored; the token is derived locally from the created subject's id and the secret (Nightscout's subjects list is cache-served and doesn't reflect a freshly created subject right away, so reading it back isn't reliable).
Seeded alarms: Low, High, Missed Reading, Not Looping, and Phone Battery are offered with sensible defaults and a single inline control each. The device/system alarms (Not Looping, Phone Battery) rely on loop/uploader data and are only offered when following Nightscout.
Deferred permission prompts: notifications, calendar, and Bluetooth are no longer requested at launch. Notifications are requested when alarms are set up or first added, calendar from the Calendar settings screen, and Bluetooth only when a BLE background-refresh mode is selected — so a fresh install isn't fronted with prompts before onboarding.
Telemetry consent is sequenced to appear after onboarding rather than on top of it.
Welcome screen uses the LoopFollow mark with a coin-landing animation.

Also modernises the Dexcom field labels ("Username", "Outside US") in both onboarding and the existing Dexcom settings screen for consistency; stored values are unchanged.

A matching docs update will follow separately in the docs repo.

Introduce a step-based onboarding wizard shown once on launch (skippable, with a prominent Skip for already-configured users): welcome, data source choice, Nightscout/Dexcom connection, units, and a few useful alarms seeded with sensible defaults. For Nightscout, add the option to create a read-only access token from the site's API secret. The secret is used only to authorize the request and is never stored. The token is derived locally from the created subject's id and the secret, since Nightscout's subjects list is served from a cache that does not reflect a freshly created subject right away. Replace the launch-time permission prompts with deferred requests so a fresh install is not fronted with them before onboarding: - notifications are requested when alarms are set up or first added - calendar is requested from the Calendar settings screen - Bluetooth is initialised only when a BLE background refresh mode is selected Welcome screen uses the LoopFollow mark with a coin-landing animation.

Not Looping and Low Battery rely on loop and uploader data that only a Nightscout site provides, so they are meaningless for a Dexcom-only follower. Offer the device/system alarm group during onboarding only when following Nightscout (or a Nightscout URL is already configured), and don't seed them otherwise.

Polish the onboarding wording (data source, Nightscout token, Dexcom sign-in, units, alarms, and completion screens) and modernise the Dexcom field labels: "Username" instead of "User Name" and "Outside US" instead of "NON-US" (display only; stored server value is unchanged). Apply the same Dexcom label changes to the standalone Dexcom settings screen so the two stay consistent.

bjorkert · 2026-06-14T20:43:28Z

# Conflicts: # LoopFollow.xcodeproj/project.pbxproj

marionbarker · 2026-06-16T04:27:42Z

Test

✅ successful test - very nice
Look below for ❓ for comments or nice to have features are noted

Configuration

iPhone SE 2nd gen running iOS 18.7.8

begin with phone already configured with a Loop URL

iPhone SE 3rd gen running iOS 26.5

begin with phone already configured with a Trio URL

Updated build on phone with existing app

SE 2nd gen:

I got the welcome screen and chose to review settings
I took the Nightscout path

SE 3rd gen:

I got the welcome screen and chose to skip the review
returned to nominal home screen

New build on phone without the app

Deleted LoopFollow from the SE 2nd gen phone

build fresh
choose Dexcom Share path
- ❓ any chance of adding password access so I can use my keychain to enter Dexcom username and password
✅ The allow bluetooth screen was not shown until I selected Settings, Background Refresh

Deleted LoopFollow from the SE 2nd gen phone

build fresh
choose Nightscout path (went through it a couple of times)
- ❓ I think the directions that you can paste a link with the token embedded and the URL and token are automatically filled in should be higher up - above the URL line
  - tested copying link with token from NS admin tools and it worked
- typed in URL and API secret and requested token be created for me
  - I repeated this action several times where I entered API Secret and asked for token to be generated - it ❓ often took 2 tries for it to succeed
- ❓ What about allow import QR code here?

Deleted LoopFollow from the SE 2nd gen phone

build fresh
choose to skip the onboarding
takes you to share screen (note - this was last screen when I got guided onboarding)
takes you to the old setup Nightscout or setupDexcom Share buttons
❓ Note that the Nightscout settings screen is different here than in the onboarding path - the websockets option is not found when onboarding

Screenshots

Onboarding NS on left, Settings NS on the right

Comments

❓ What about adding a feature to get to the QR codes earlier - maybe a third option that says I want to configure this phone from another LoopFollow phone

❓ should the Dexcom and Nightscout screens from onboarding and settings be combined or kept separate?

dnzxy · 2026-06-16T17:04:14Z

First of all, this is awesome. I played with this yesterday and I really like it. Great first draft!
I'll put a few general thoughts below, and then go step by step through the Onboarding flow with a few notes.
All of this is of course just first impression feedback and ideas that came up while I played with it.

A few general thoughts:

The content per onboarding step is for most steps not overwhelming and very "limited" to what's needed to be set up.
Consider adding a few more hints or explanation and tightening "connections" between labels, input controls and their sections.
Literacy and numeracy are often an issue. Consider adding a few more hints or tips and utilize LLMs to help with typo. Typo for diabetes tech is often catered to a target audience of 6th graders or high school students. You know the user base of LF best, I cannot gauge their literacy.
Would it make sense to also expose a step called "General Alarm Settings" before "Useful Alarms" where you can set up the few general settings that you can set up in LF when you navigate to Alarms -> ⚙️. This may especially make sense for the Day & Night window and the sound handlng.
Would it make sense to give users the ability to set up background refresh mode? It's probably one of the most important setting for caregivers, so that LF keeps staying active and fetching from NS, outside of providing alarms and remote commands, right?
I really love this screen about LoopFollow. Without making things wayyy to complicated, does it make sense to add it to the Onboarding?

A few more detailed comments about the Onboarding flow

Screenshot	Comment
	Justified text is shown to cause trouble reading for users. I'll note it here, but it applies for all subviews in the Onboarding
	It helps to give users a sense of "How many steps do I have left?" Consider adding some sense of step indicator. Consider adding an overview or "introductory" step that gives a rough overview over the app setup, and an estimate of time.
	Really like the style of this when it becomes the active option
	The water drop SF Symbol especially with blue color does give a mismatching impression
	The Nightscout option has a label for this status indicator, "Status" When initially navigating this feels a bit off as if it just flows there. Can the text be adaptive? In the screenshot I entered the username, the status still asks me to enter it.
	I love the option of LF creating a token for the user. Great for the setup. Consider making the "connection" between the various sections clearer. Maybe just change which elements / controls have a dark grey background.
	This lets me paste a site with a token, but not enter one my typing it in. Consider allowing this, too.
	Accent color always implies something is active. Consider changing the style here to what it looks like when the user focuses the Token input
	^^^ refers to this
	This is was now entered by me and it shows white color. Should this maybe be accentuated, as the user entered it?
	When testing this, I ran into a situation where I let LF create a token, and it then showed "Invalid Token" for the status. When that was the case, it was not super clear, that this creates a token, automatically fills it in and then attempts to connect to NS. Consider animating the picker and view so that you Create token from API secret -> animate view and switch picker option -> user then sees token was entered -> then proceeds to check. Smaller devices may hide the Status check badge and the user needs to scroll to it. Consider moving it up or somehow changing it. Maybe the globe icon up top could morph into a status badge (like a pill) once the user has started adding something, and then morph along with various user inputs, finally showing a successful connection?
	In this screen it's not immediately clear what various elements mean, because they are abbreviated. Consider adding section footer notes or hints that explain them, or what the entice (e.g. TIR = 70-180 mg/dL). Consider not allowing the user to choose TITR, as TITR isn't really a good metric for glucose monitoring from a mental burden standpoint. Consider explaining what Variability and Standard Deviation or Covariance mean in this context.
	Consider changing the labeling away from "useful" maybe; more like "recommended"; all alarms in LF are useful :)
	I love the concept of this and providing a set of default alerts with sensible values. The bottom hint may get cut off on smaller device screens and not be visible; consider moving it further to the top.
	Different alarms expose different tunable thresholds. Would it make sense to maybe split this view into 5 substeps and letting the user define some (not all!) more of the options that alerts in LF come with? So you enter the "Useful Alarms" step, the initial substep contains a little explanation about what the next substeps contain, how recommended alarms can be now set up, and that not all options are exposed. The user can then proceed to navigate through the next 5 recommended alarms where the user can tune a few of the options, then you proceed.
	From the Onboarding progress, this looks like there is another step, but proceeding to the next step will do two things: show the "You are done ✅" screen and on top of it prompt notification permissions. Consider adjusting this.
	This step looks to be the last step, but the user has to do one more thing: decide about notifications. Following https://developer.apple.com/design/human-interface-guidelines/privacy#Pre-alert-screens-windows-or-views it may be sensible to add a dedicated screen contextualizing it, so giving a very brief explanation why this permission should be granted and what it is used for. Enhance-d also does this in a very nice manner, if you want to look at a commercial app with permission context screen.
	Maybe we can find a nicer label than "Done" for users to continue on their LF. "Finish" or maybe "Got it!" ?
	Typically data sharing or telemetry is part of an app's onboarding. Especially in our ecosystem, Loop and Trio have (unfortunately?) set this precedent. Apple does not really have guidelines on this, but hints at usage metrics in their onboarding best practices, see https://developer.apple.com/design/human-interface-guidelines/privacy#Best-practices. Consider moving this into the Onboarding flow as an additional step, which also offers an opportunity to give more information about what is shared to the user

Onboarding - Track progress by phase with a smooth bar and a per-phase counter - Add overview, general alarm settings, tab order, notification and telemetry steps, plus a "Copy from another phone" QR data source - Left-align text and tidy copy throughout Nightscout - Split connect into an address page and a token page shown only when needed - Add a live status pill; show "needs a token" as a positive state - Accept both array and object shapes from the subject-create response, fixing the create-token-fails-first-time case - Treat a freshly created but not-yet-accepted token as pending instead of an error so the user can continue Dexcom - Enable keychain autofill, verify credentials with a real login, and use a CGM-style icon Alarms - Offer more alarms one per page, on by default, with a few settings each - Skip alarm types the user already has and use each type's own icon Other - Defer notification, calendar and Bluetooth prompts away from launch - Add units explainer footers with correct values that follow the unit

- Unify the Nightscout and Dexcom connect screens on a shared, color-coded status pill pinned at the top. - Give every onboarding header one shared leading edge with its content by moving horizontal margins out of OnboardingStepHeader to the call sites. - Top-align the Notifications and Privacy screens to match the rest of the flow. - Split the Units phase into two lighter pages: Units and Statistics. - State a concrete setup time on the Overview screen and add a short "things to explore" tease on the completion screen. - Format the Fast drop alarm's threshold in the selected glucose unit. - Show the day/night setting on the Sensor change and Pump change alarms, defaulting to Day. - Derive the onboarding alarm control fallbacks from Alarm(type:) so they share the one source of truth for per-type defaults.

- Update recommended thresholds: Low 70 / 20 min predictive, Urgent low 54, Fast drop 15 over 3 readings (~45 in 15 minutes), Not looping 16 (aligned with Missed readings). - Add a "Readings in a row" control and a plain-language footer to the Fast drop onboarding page so its per-reading behaviour is clear. - Derive the onboarding alarm control fallbacks from Alarm(type:) so they share one source of truth with the normal per-type defaults. - Add FastDropCondition tests covering per-reading vs cumulative behaviour, window and threshold edges, and guard cases.

Bring the onboarding's token-from-secret flow to the regular Nightscout settings screen: paste a token, or paste the API secret and LoopFollow creates (or reuses) a read-only token for you. When the token field holds something that isn't a token and the site rejects it — most often a pasted API secret — a one-tap "create a token from this" action is offered. The provisioning logic, secret detection, and error mapping now live on NightscoutSettingsViewModel so onboarding and settings share one implementation.

Detect a pasted API secret by actually verifying it against the site (an auth probe on an admin-gated endpoint), rather than guessing from its shape — so the "create a read-only token from this" suggestion only appears when creating one will genuinely work. Show the suggestion on the onboarding token page as well, not just the Nightscout settings screen.