flutter-url-launcher-engineering

Flutter url_launcher Engineering

Mission

Treat url_launcher as a platform handoff API, not a browser framework or proof that an external business action completed. Use this loop:

identify external action
→ decide whether url_launcher is appropriate
→ classify destination trust
→ construct a safe Uri
→ choose an intentional LaunchMode
→ query capability only if it changes UX
→ launch once
→ handle false/exception with fallback
→ verify downstream business completion separately
→ test platform-specific behavior

Non-negotiable rules

1. Use launchUrl(Uri, ...); do not introduce deprecated string-based launch/canLaunch APIs.
2. Use Uri.parse only for known complete trusted constants; use structured Uri construction for dynamic components.
3. For dynamic HTTP(S) query values, use queryParameters rather than string concatenation.
4. For non-HTTP(S) schemes such as mailto:, follow the package's documented query + Uri.encodeComponent workaround.
5. Treat API, CMS, chat, QR, push, deep-link, remote-config, and user-provided destinations as untrusted.
6. Allow only intentional schemes and validate exact hosts when the destination is product-controlled.
7. Prefer HTTPS for ordinary web navigation when policy requires trusted web transport; reject disallowed HTTP rather than silently rewriting arbitrary URLs.
8. Do not put credentials, session secrets, private keys, or server secrets into externally launched URLs unless a reviewed protocol explicitly requires it.
9. Do not log complete sensitive URIs, query strings, or fragments.
10. Choose LaunchMode from required UX semantics. Do not rely on today's observed platformDefault behavior when the surface matters.
11. Both in-app modes require HTTP(S); do not use them for tel:, mailto:, sms:, or arbitrary custom schemes.
12. Prefer attempting launchUrl and handling failure when capability detection is not needed for pre-launch UI.
13. Treat canLaunchUrl as a platform-sensitive query that may return false because visibility/querying is restricted.
14. Use supportsLaunchMode only when automatic fallback would violate product requirements.
15. Add Android <queries> and iOS LSApplicationQueriesSchemes only when the app genuinely needs capability querying.
16. On web, preserve direct user-gesture context for new tab/window launches.
17. Never interpret launchUrl == true as proof of email delivery, call completion, SMS send, OAuth authentication, payment, purchase, installation, or any other external result.
18. Custom schemes are routing mechanisms, not verified application identity.
19. Use verified HTTPS/App Link/Universal Link mechanisms when target identity matters.
20. Keep internal Flutter navigation in the router/Navigator, not url_launcher.
21. Use a dedicated WebView/browser integration when the app needs rich embedded browsing controls.
22. Keep external navigation as a presentation/platform side effect unless a deliberate application abstraction adds security, fallback, observability, or testing value.
23. Prevent harmful duplicate launches when rapid repeated taps could open multiple windows/apps.
24. Test Android, iOS, web, and desktop behavior independently where supported.
25. Inspect resolved federated platform package versions before making implementation-specific claims.