Repository navigation
Make Formulus settings QR codes camera-scannable via formulus:// deep link #915
Description
Activity
Hi @r0ssing, I'd be interested in working on this issue. I recently worked on Formulus profile/settings functionality and would like to take this on. Is #917 far enough along for me to start implementing the Android deep-link flow, or would you prefer this issue to wait for the profiles work to land?
Reacted by Emil RossingHi @r0ssing, I'd be interested in working on this issue. I recently worked on Formulus profile/settings functionality and would like to take this on. Is #917 far enough along for me to start implementing the Android deep-link flow, or would you prefer this issue to wait for the profiles work to land?
Hi @allennakalema06-web - thanks for taking this on! Please go ahead, and then we can discuss any technical considerations either here on in our calls..
The profiles implementation is already present in the dev branch/prereleases of Formulus, so you should be able to switch between profiles in Formulus, if you test with a local build..
@najuna-brian ; Are you working on a guide on how to test locally? Perhaps we could discuss at our next meeting, and take any feedback from @allennakalema06-web on this into account?
Hi @Mishael-2584, thanks for the review on #1009. I understand the smaller implementation suggestions and will work through those.
I wanted to ask for some clarification on the two broader points you raised before I make changes, so that I follow the intended direction for #915.- Compatibility with older Formulus versions
The new QR format allows the normal phone camera to recognize the QR as a Formulus link and open the app. However, once the Portal, synk qr, and the QR generation script start generating this new format, older versions of Formulus that only understand the bare FRMLS: format may no longer be able to scan those newly generated QR codes using their in-app scanner.
You suggested either providing a legacy-generation option during the transition or documenting a minimum supported Formulus version.
Which direction would you prefer for Make Formulus settings QR codes camera-scannable via formulus:// deep link #915? Should I add a way for admins/users to still generate the old FRMLS: QR format, or should the new QR format require users to be on a newer Formulus version? - iOS scope
I also understand your point that registering the formulus:// scheme in Info.plist alone doesn't complete the iOS flow, since the incoming URL still needs to reach the React Native navigation layer.
I don't currently have access to the Mac + iPhone setup needed to properly test the complete iOS flow. The original issue allows for an Android-first implementation if the iOS camera behavior isn't reliable.
Would you prefer that feat(formulus): support settings deep links #1009 remain Android-first and that I remove/defer the incomplete iOS implementation to a follow-up issue, or should the additional iOS handling still be implemented as part of this PR?
For Android, I confirmed on a physical device that Android recognizes the formulus://settings link and launches Formulus. I wasn't able to complete the full profile-prefill flow because my local React Native/Metro development environment ran into a dependency-resolution issue. Brian has offered to build the branch and help verify the complete Android flow as well.
Once I know your preferred direction on the two points above, I'll update feat(formulus): support settings deep links #1009 accordingly. Thank you!
- Compatibility with older Formulus versions
Summary
Update the Formulus settings QR payload so it can be scanned by the system camera (Android first; investigate iOS) and open Formulus into the settings / profile flow, instead of only working when scanned from the in-app Settings scanner.
Today the QR encodes an opaque
FRMLS:…string (FRMLSHelpers, Portal,synk qr,formulus/scripts/generateQR.ts). That is not a URI, so OS cameras do not offer an “Open in Formulus” action.Proposed URI shape
Prefer a custom URL scheme (not an
https://opendataensemble.org/…App/Universal Link):Rationale: best fit for app-only deep links. Catching a shared
opendataensemble.orgHTTPS path risks colliding with normal website / docs QR codes.Exact query encoding can be finalized in implementation (e.g. wrap the existing FRMLS string in a query param). Keep the FRMLS body as the credential payload.
Requirements
Formulus (consume path)
formulus://scheme (path/host for settings as needed).FRMLS:…codes (no URI wrapper).serverUrl/ username / password) via existingQRSettingsService/decodeFRMLSpath (or a thin wrapper around it).iOS
formulus://settings?…custom scheme is feasible (URL types in Info.plist +Linking), and whether OS Camera / Control Center scanner surfaces an open-app affordance comparable to Android.Generators (same issue)
Update all producers to emit the new URI-wrapped form (while documenting that bare FRMLS remains readable in-app):
synkronus-portalFRMLS / formulus QR helpers)synk qr)formulus/scripts/generateQR.tsAcceptance criteria
FRMLS:…and the newformulus://settings?…form.synk qr, andgenerateQR.tsemit the new URI format.opendataensemble.orgHTTPS links for this feature.Notes / context
FRMLS:v:<b64>;s:<b64>;u:<b64>;p:<b64>;;formulus/src/utils/FRMLSHelpers.ts,formulus/src/services/QRSettingsService.ts,formulus/src/screens/SettingsScreen.tsx, Portalfrmls/ formulus QR utils,synkronus-cliqrcommand.