Merge pull request #214 from okto-hq/main

onboarding screen pages

content/docs/flutter-sdk/advanced-sdk-config/authenticate-users/meta.json

@@ -5,6 +5,7 @@
       "google-oauth",
       "phone-otp",
       "email-otp",
+      "onboarding-modal",
       "!other-social-auth",
       "login-logout"
     ]

content/docs/flutter-sdk/advanced-sdk-config/authenticate-users/onboarding-modal/auth-user-via-modal.mdx

@@ -0,0 +1,132 @@
+---
+title: Authenticate User via Onboarding Modal
+description: Learn how to trigger and handle authentication using the Okto Onboarding Modal.
+full: false
+---
+
+import { TypeTable } from 'fumadocs-ui/components/type-table';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+import { Icon as IIcon } from '@iconify/react';
+
+import '../../../styles.css';
+
+### Methods Overview
+
+| Method                             | Description                                                                                          |
+|----------------------------------|------------------------------------------------------------------------------------------------------|
+| <sub><i>async</i></sub>[`openOnboarding`](#show-onboarding-modal) | Opens the Okto Onboarding flow with your chosen primaryAuth (e.g., Email, Phone, or Google) and brand data |
+
+<div class="method-box">
+
+## Show Onboarding Modal
+
+`openOnboarding(...)` <a href="https://github.com/okto-hq/okto-sdk-flutter/blob/main/lib/src/okto.dart#L350" target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none' }}><IIcon icon="lucide:external-link" height="17" style={{ display: 'inline-block', verticalAlign: 'middle' }} /></a> presents a guided onboarding flow to the user. This includes brand data, theming, and whichever `primaryAuth` type you’ve set in the `openOnboarding()` parameters. Under the hood, it launches a **WebView** that takes the user through various authentication options (Email OTP, Phone OTP, Google OAuth, etc.).
+
+### Parameters
+
+| Parameter             | Type                          | Description                                                                 |
+|-----------------------|-------------------------------|-----------------------------------------------------------------------------|
+| `context`            | `BuildContext`                | The Flutter build context. *(Required)*                                     |
+| `gAuthCallback`       | `Future<String> Function()`    | A function that returns a Google **ID token** (if using `AuthType.GAUTH`).  |
+| `onLoginSuccess`      | `Function`                    | Callback triggered once the user completes onboarding successfully.         |
+| `primaryAuth`         | `AuthType`                    | Set your default authentication flow. E.g. `AuthType.EMAIL`, `AuthType.PHONE`, `AuthType.GAUTH`. |
+| `title`               | `String`                      | A title for brand customization (optional).                                 |
+| `iconUrl`             | `String`                      | A brand icon URL (optional).                                               |
+| `subtitle`            | `String`                      | A subtitle for brand customization (optional).                              |
+| Theming parameters    | `String` (color in hex)        | Additional theming (text colors, background, accent, etc.).                |
+
+### Response
+
+<Callout title="Success Response">
+
+| Field Name | Type             | Description                                | 
+|------------|------------------|--------------------------------------------|
+| `result`   | `Future<void>`   | Returns no meaningful response on success. |
+
+</Callout>
+
+<Accordions>
+<Accordion title="Example">
+<Tabs items={['Typescript']}>
+  <Tab value="Typescript">
+
+```typescript
+import 'package:flutter/material.dart';
+import 'package:okto_flutter_sdk/okto_flutter_sdk.dart';
+
+class OnboardingModalExample extends StatefulWidget {
+  const OnboardingModalExample({Key? key}) : super(key: key);
+
+  @override
+  _OnboardingModalExampleState createState() => _OnboardingModalExampleState();
+}
+
+class _OnboardingModalExampleState extends State<OnboardingModalExample> {
+  final Okto okto = Okto(); // Initialize Okto instance
+  String _message = '';
+
+  Future<void> _handleOnboarding() async {
+    try {
+      await okto.openOnboarding(
+        context: context,
+        gAuthCallback: _googleAuthCallback, // Returns Google ID token if using Google
+        primaryAuth: AuthType.EMAIL,       // Default to Email OTP
+        title: "Your App Name",
+        subtitle: "Welcome to Web3",
+        iconUrl: "https://your-app.com/icon.png",
+        textPrimaryColor: '0xFFFFFFFF',
+        textSecondaryColor: '0xFFCCCCCC',
+        accent1Color: '0xFF905BF5',
+        backgroundColor: '0xFF000000',
+      );
+      setState(() {
+        _message = 'Onboarding completed successfully!';
+      });
+    } catch (error) {
+      setState(() {
+        _message = 'Error during onboarding: $error';
+      });
+    }
+  }
+
+  Future<String> _googleAuthCallback() async {
+    // If using Google Sign-In:
+    // final GoogleSignIn googleSignIn = GoogleSignIn(...);
+    // final user = await googleSignIn.signIn();
+    // final auth = await user?.authentication;
+    // return auth?.idToken ?? "";
+    return ""; // Return "" if you don't have Google set up
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Onboarding Modal Example'),
+      ),
+      body: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          children: [
+            ElevatedButton(
+              onPressed: _handleOnboarding,
+              child: const Text('Launch Onboarding Modal'),
+            ),
+            const SizedBox(height: 16),
+            Text(_message),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+</Tab> 
+</Tabs> 
+</Accordion> 
+</Accordions> 
+
+</div>

content/docs/flutter-sdk/advanced-sdk-config/authenticate-users/onboarding-modal/learn.mdx

@@ -0,0 +1,144 @@
+---
+title: Learn
+description: Learn how the Okto Onboarding Modal helps streamline user authentication and onboarding workflows in Flutter apps.
+full: false
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+# What is the Onboarding Modal?
+
+Okto’s **Onboarding Modal** provides a **streamlined** way to authenticate users by displaying an embeddable flow (via a **WebView**) without requiring them to leave your **Flutter** app. Under the hood, the **Onboarding Modal** can handle multiple authentication flows (Email OTP, Phone OTP, Google OAuth, etc.) and can be customized with brand data, visuals, and theming.
+
+## Why Use the Onboarding Modal?
+
+1. **No Authentication Flow Management**  
+   Vendors need not work or worry about the authentication flow or the code for it. Okto handles everything on the server side, simplifying the implementation and saving development time.
+
+2. **Multi-Auth Support**  
+   The modal can be set up to handle Google Auth, Email OTP, Phone OTP, or your primary authentication of choice.
+
+3. **Brand & Theme Customizations**  
+   Pass your branding (title, subtitle, icon) and theming (colors, backgrounds, etc.) to tailor the onboarding experience to your style guidelines.
+
+## Typical Flow
+
+Below is a simplified sequence for how the Onboarding Modal works:
+
+1. **Trigger the Modal**  
+  Your Flutter code calls `okto.openOnboarding(...)` from the **Okto** SDK. This opens a new **Onboarding** page containing a WebView.
+
+2. **WebView Initialization**  
+  The WebView loads the Okto environment for your selected `buildType` (Sandbox, Staging, or Production).  
+  It also receives your brand data, theming, and selected primary authentication method.
+
+3. **User Authentication**  
+  The user completes the steps (e.g., Google login, Email OTP, or Phone OTP). If the flow requires an external token (like a Google ID token), Okto can request it from your Flutter app via `gAuthCallback()`.
+
+4. **Auth Success**  
+  Once the user is authenticated, Okto returns the relevant tokens (`authToken`, `refreshToken`, etc.) and closes the onboarding screen automatically. At that point, your Flutter app can continue with a fully authenticated user.
+
+### Sequence Diagram
+
+![Auth Sequence Diagram](/images/onboarding-modal-sequence-diagram.png)
+
+## Key Points to Remember
+
+- **`showOnboardingModal()`** in the SDK is your main entry point to launch the modal.
+- You can customize brand data, theming, and the primary auth method (Email, Phone, or Google).
+- For Google OAuth, provide a callback (`gAuthCallback`) that returns an ID token from your chosen sign-in flow (e.g., `google_sign_in` package).
+- On success, your app will have the user’s `authToken` (and refresh token) stored in Okto’s internal state.
+
+---
+
+# Enabling Google Authentication in the Onboarding Modal
+
+Okto’s Onboarding Modal can integrate with **Google Authentication** to offer a smooth, single-click login experience. To enable this, you need to configure the `gAuthCallback`, which handles the retrieval of your Google ID token. Below is an example using the `google_sign_in` package.
+
+**Example `login_page.dart` snippet:**
+
+```dart
+import 'package:google_sign_in/google_sign_in.dart';
+import 'package:example/okto.dart'; // or your own utils
+import 'package:flutter/material.dart';
+import '../screens/home/home_page.dart';
+
+class LoginPage extends StatefulWidget {
+  const LoginPage({super.key});
+
+  @override
+  State<LoginPage> createState() => _LoginPageState();
+}
+
+class _LoginPageState extends State<LoginPage> {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      backgroundColor: const Color(0xff5166EE),
+      body: SafeArea(
+        child: Column(
+          children: [
+            // ... other login methods here ...
+            ElevatedButton(
+              onPressed: () async {
+                // This uses the Okto Onboarding flow with a callback for Google sign-in
+                await okto!.openOnboarding(
+                  context: context,
+                  gAuthCallback: _loginWithGoogle,
+                  onLoginSuccess: _handleLoginSuccess,
+                  primaryAuth: AuthType.GAuth, // sets Google as the primary
+                  title: "My Flutter App",
+                  iconUrl: "https://example.com/icon.png",
+                  subtitle: "Welcome to Web3 with Okto",
+                );
+              },
+              child: const Text('Onboarding (Google)'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Future<String> _loginWithGoogle() async {
+    final GoogleSignIn googleSignIn = GoogleSignIn(
+      scopes: [
+        'email',
+        'https://www.googleapis.com/auth/userinfo.profile',
+        'openid',
+      ],
+    );
+    try {
+      final user = await googleSignIn.signIn();
+      final auth = await user?.authentication;
+      if (auth == null) return "";
+      return auth.idToken ?? "";
+    } catch (e) {
+      debugPrint("GAuth Error: $e");
+      return "";
+    }
+  }
+
+  void _handleLoginSuccess() {
+    // Optionally, navigate or show a toast
+    Navigator.pushReplacement(
+      context,
+      MaterialPageRoute(builder: (context) => const HomePage()),
+    );
+  }
+}
+
+```
+
+**Key Steps:**
+
+- The callback `_loginWithGoogle` returns a Google ID token (or empty on error).
+- Okto uses this token to complete the Google auth process.
+- On success, `onLoginSuccess` is called, and your user is now fully authenticated.
+
+## Common Tips & FAQ
+
+- **Custom Branding:** Okto’s `openOnboarding(...)` lets you pass `title`, `subtitle`, `iconUrl` plus color theming to customize the look.
+
+- **Primary Auth Method:** By default, you can set `primaryAuth: AuthType.GAuth` (Google), `AuthType.EMAIL`, or `AuthType.PHONE`. You can also override it dynamically if needed.

content/docs/flutter-sdk/advanced-sdk-config/authenticate-users/onboarding-modal/meta.json

@@ -0,0 +1,7 @@
+{
+    "title": "Onboarding Modal",
+    "pages": [
+      "learn",
+      "auth-user-via-modal"
+    ]
+  }

content/docs/flutter-sdk/advanced-sdk-config/okto-embedded-wallet/built-in-ui-screens/meta.json

@@ -2,7 +2,7 @@
     "title": "Built in UI Screens",
     "pages": [
       "!learn-okto-ui-screens",
-      "!onboarding-screen",
+      "[Onboarding Modal](/docs/flutter-sdk/advanced-sdk-config/authenticate-users/onboarding-modal/learn)",
       "!portfolio-screen",
       "!activity-screen",
       "show-ui-screen-via-code",

content/docs/react-native-sdk/advanced-sdk-config/authenticate-users/meta.json

@@ -5,6 +5,7 @@
       "google-oauth",
       "phone-otp",
       "email-otp",
+      "onboarding-modal",
       "!other-social-auth",
       "login-logout"
     ]