Enhance Flutter SDK documentation with comprehensive improvements #560
Conversation
WalkthroughUpdates the Flutter SDK documentation and public API: adds Android OAuth redirect scheme guidance, billing-related AdditionalParameters for login/register, and portal URL generation (PortalPage enum + createPortalUrl). Integrates runnable examples, validation notes, and API reference updates. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor U as Flutter App (User)
participant SDK as Kinde Flutter SDK
participant Auth as Kinde Auth Server
participant Portal as Kinde Portal
rect rgba(200,230,255,0.25)
note right of U: Optional billing context passed
U->>SDK: login(register)(additionalParameters?)
SDK->>Auth: Authorization request (+additionalParameters)
Auth-->>SDK: Tokens
SDK-->>U: Authenticated session
end
rect rgba(220,255,220,0.25)
note right of U: Portal URL generation
U->>SDK: createPortalUrl(returnUrl, subNav)
SDK->>Auth: Request signed portal URL (authenticated)
Auth-->>SDK: Portal URL
SDK-->>U: URL string
U->>Portal: Open portal URL (browser/webview)
Portal-->>U: Target sub-page (profile/billing/org)
end
sequenceDiagram
autonumber
actor A as Android App
participant SDK as Kinde Flutter SDK
participant Browser as System Browser
note over A: App configured with appAuthRedirectScheme + manifest filters
A->>SDK: Start auth flow
SDK->>Browser: Open authorize URL (redirect_uri uses custom scheme)
Browser-->>A: Redirect via custom scheme (login/logout)
A->>SDK: Deliver intent to RedirectUriReceiverActivity
SDK-->>A: Complete auth (tokens delivered)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx (1)
654-666: Same launch pattern and import as above.Keep examples consistent to reduce support noise.
🧹 Nitpick comments (8)
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx (8)
124-141: Clarify app-level Gradle placement and flavor overrides.State explicitly that this belongs in the module (android/app) Gradle file. Also show how to set
manifestPlaceholdersper build type/flavor to avoid mixing schemes across variants.Example (Groovy):
android { defaultConfig { - manifestPlaceholders += [ + manifestPlaceholders += [ appAuthRedirectScheme: '<your_custom_scheme>' ] } + productFlavors { + dev { + manifestPlaceholders.appAuthRedirectScheme = 'myapp-dev' + } + prod { + manifestPlaceholders.appAuthRedirectScheme = 'myapp' + } + } }
143-152: Kotlin DSL: show flavor-specific placeholders.Mirror the Groovy example so KTS users don’t guess how to scope per flavor.
android { defaultConfig { manifestPlaceholders["appAuthRedirectScheme"] = "<your_custom_scheme>" } + productFlavors { + create("dev") { + manifestPlaceholders["appAuthRedirectScheme"] = "myapp-dev" + } + create("prod") { + manifestPlaceholders["appAuthRedirectScheme"] = "myapp" + } + } }
154-161: Explicitly define “scheme” (no ://) and align with envs.Add a one-liner: “Use only the scheme portion (e.g., myapp), not ‘myapp://’.” Also call out that envs use full URLs while the manifest uses only the scheme to prevent common misconfigurations.
- The `appAuthRedirectScheme` is a custom URL scheme ... + The `appAuthRedirectScheme` is the URL scheme (e.g., `myapp`) — do not include `://`. + In env vars use full URLs (e.g., `myapp://kinde_callback`), but in the manifest use only the scheme.
210-217: Augment the checklist with namespace and deep-link notes.
- Add: “Define module namespace in build.gradle(.kts), e.g.,
android { namespace = "com.example.app" }.”- Add: “Don’t use
android:autoVerifyfor custom schemes.”- Remove: “tools namespace” if no
tools:attributes remain.
310-332: DocumentAdditionalParameterstype and imports; note optionality.Briefly define the model (fields optional) and where it’s imported from; otherwise readers can’t compile examples.
```dart +// import 'package:url_launcher/url_launcher.dart'; // if launching URLs elsewhere +// import 'package:kinde_flutter_sdk/kinde_flutter_sdk.dart'; +// AdditionalParameters has optional fields: { String? planInterest, String? pricingTableKey } // During login with billing context final token = await sdk.login( context: context, additionalParameters: AdditionalParameters( planInterest: 'premium', pricingTableKey: 'pricing_table_1' ), );And add this type to the API Reference with a short table. --- `597-672`: **Portal URL examples: include `url_launcher` import and failure handling.** Readers will copy-paste. Add the import and handle `canLaunchUrl` to avoid runtime errors. ```diff - // Open the portal URL in browser or WebView - print('Portal URL: $portalUrl'); + // Open the portal URL + final uri = Uri.parse(portalUrl); + if (!await canLaunchUrl(uri)) { + throw 'Cannot launch $uri'; + } + await launchUrl(uri, mode: LaunchMode.externalApplication);And prepend:
+import 'package:url_launcher/url_launcher.dart';
642-652: UsecanLaunchUrland external mode in examples.Harden example to avoid silent failures when a handler is unavailable.
- await launchUrl(Uri.parse(billingUrl)); + final uri = Uri.parse(billingUrl); + if (await canLaunchUrl(uri)) { + await launchUrl(uri, mode: LaunchMode.externalApplication); + }
1019-1048: API reference: add return type and errors; cross-link enum.Specify
Future<String>return type, possible errors (unauthenticated, invalidreturnUrl), and linkPortalPage. Also addAdditionalParametersto Methods/Types since it’s used above.- createPortalUrl({ + Future<String> createPortalUrl({ required String returnUrl, PortalPage subNav = PortalPage.profile })
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx(5 hunks)
🔇 Additional comments (2)
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx (2)
626-636: Keep enum list auto-synced with SDK to prevent drift.Note that values must mirror the SDK’s
PortalPage. Consider generating this list from source or linking to the API doc to avoid future mismatches.Would you like a small script to diff the enum in the repo against these docs?
668-672: Expand requirements: allowlists and org context.
- Add: “Ensure
returnUrlorigin is allowed in your Kinde app settings.”- If org-specific pages are used, clarify how the current org context is determined.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx (1)
167-169: Remove tools:node="replace"; keep AppCompat theme but note dependency.
- tools:node="replace" can clobber manifest merges from transitive libs and is unnecessary here. Remove it and the tools namespace if it’s unused elsewhere.
- Retain Theme.AppCompat.Translucent.NoTitleBar (we’ve seen crashes without it), but call out the appcompat dependency so this style resolves at build time.
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" - xmlns:tools="http://schemas.android.com/tools"> +<manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <!-- OAuth Redirect Handler --> <activity android:name="net.openid.appauth.RedirectUriReceiverActivity" android:theme="@style/Theme.AppCompat.Translucent.NoTitleBar" - android:exported="true" - tools:node="replace"> + android:exported="true">Add this dependency if not already present (outside the manifest):
Groovy:
dependencies { implementation "androidx.appcompat:appcompat:1.7.0" }Kotlin DSL:
dependencies { implementation("androidx.appcompat:appcompat:1.7.0") }Also applies to: 186-205
🧹 Nitpick comments (5)
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx (5)
124-152: Clarify placeholder usage for custom scheme (no ://, lowercase).To prevent common misconfigurations, add a short note that the manifest placeholder should be only the scheme (e.g., myapp), not myapp://, and recommend lowercase to avoid Android parsing quirks.
**For build.gradle.kts (Kotlin DSL):** ```kotlin android { ... defaultConfig { ... manifestPlaceholders["appAuthRedirectScheme"] = "<your_custom_scheme>" } }
+Tip: Use only the scheme part here (e.g.,
myapp— no://) and prefer lowercase. Your env vars should then bemyapp://kinde_callbackandmyapp://kinde_logoutcallback.--- `210-217`: **Update key points: tools namespace not needed; add appcompat note.** Since we’re removing tools:node, the tools namespace bullet should go. Add a note about resolving the AppCompat theme via the appcompat dependency. ```diff -**Key Configuration Points:** - -- Add the `tools` namespace to the manifest root +**Key Configuration Points:** +- Ensure the AppCompat theme resolves by including `androidx.appcompat:appcompat` in your app module dependencies - Set `taskAffinity="${applicationId}"` for the main activity - Include the `RedirectUriReceiverActivity` with proper intent filters for both login and logout callbacks - The `${appAuthRedirectScheme}` in the manifest gets replaced with your custom scheme from build.gradle - Intent filters handle both `kinde_callback` (login) and `kinde_logoutcallback` (logout) URLs
310-333: Document SDK surface for AdditionalParameters and add availability note.The examples look good. Please add an “API” note so readers know the option is part of
login/registerand which SDK version introduced it.## Billing URL Parameters When directing users to authentication flows with billing context, you can now pass additional parameters to indicate pricing interests: ```dart @@ );
+Note:
+-additionalParametersis supported by bothloginandregister.
+- Please ensure you are usingkinde_flutter_sdkversion X.Y.Z or later whereAdditionalParameterswas introduced.--- `597-672`: **Strengthen guidance for createPortalUrl (whitelisting and open‑redirect safety).** Add requirements to avoid configuration issues and security pitfalls when handling returnUrl. ```diff ### Requirements -- User must be authenticated before calling `createPortalUrl()` -- The `returnUrl` parameter must be an absolute URL +- User must be authenticated before calling `createPortalUrl()`. +- The `returnUrl` must be an absolute URL and its domain should be allowed in your Kinde app’s Allowed redirect URLs. +- Do not pass user-controlled input directly as `returnUrl` to avoid open‑redirect risks.
1019-1048: Use absolute returnUrl in examples to match the requirement.Examples currently use
your_return_urlwithout scheme/host. Show an absolute HTTPS URL for consistency with the Requirements.// Navigate to user profile final profileUrl = await sdk.createPortalUrl( - returnUrl: 'your_return_url' + returnUrl: 'https://yourapp.com/settings/profile' ); // Navigate to billing page final billingUrl = await sdk.createPortalUrl( - returnUrl: 'your_return_url', + returnUrl: 'https://yourapp.com/settings/billing', subNav: PortalPage.planSelection );
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx(5 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-09-15T05:43:48.408Z
Learnt from: ashar-aala
PR: kinde-oss/documentation#560
File: src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx:0-0
Timestamp: 2025-09-15T05:43:48.408Z
Learning: Theme.AppCompat.Translucent.NoTitleBar is required for RedirectUriReceiverActivity in Android manifest configurations when using AppAuth library. Removing this theme causes crashes with "java.lang.IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity".
Applied to files:
src/content/docs/developer-tools/sdks/native/flutter-sdk.mdx
Description (required)
Related issues & labels (optional)
Summary by CodeRabbit
New Features
Documentation