|
| 1 | +--- |
| 2 | +title: Learn |
| 3 | +description: Learn how the Okto Onboarding Modal helps streamline user authentication and onboarding workflows in Flutter apps. |
| 4 | +full: false |
| 5 | +--- |
| 6 | + |
| 7 | +import { Callout } from 'fumadocs-ui/components/callout'; |
| 8 | +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; |
| 9 | + |
| 10 | +# What is the Onboarding Modal? |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +## Why Use the Onboarding Modal? |
| 15 | + |
| 16 | +1. **No Authentication Flow Management** |
| 17 | + 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. |
| 18 | + |
| 19 | +2. **Multi-Auth Support** |
| 20 | + The modal can be set up to handle Google Auth, Email OTP, Phone OTP, or your primary authentication of choice. |
| 21 | + |
| 22 | +3. **Brand & Theme Customizations** |
| 23 | + Pass your branding (title, subtitle, icon) and theming (colors, backgrounds, etc.) to tailor the onboarding experience to your style guidelines. |
| 24 | + |
| 25 | +## Typical Flow |
| 26 | + |
| 27 | +Below is a simplified sequence for how the Onboarding Modal works: |
| 28 | + |
| 29 | +1. **Trigger the Modal** |
| 30 | + Your Flutter code calls `okto.openOnboarding(...)` from the **Okto** SDK. This opens a new **Onboarding** page containing a WebView. |
| 31 | + |
| 32 | +2. **WebView Initialization** |
| 33 | + The WebView loads the Okto environment for your selected `buildType` (Sandbox, Staging, or Production). |
| 34 | + It also receives your brand data, theming, and selected primary authentication method. |
| 35 | + |
| 36 | +3. **User Authentication** |
| 37 | + 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()`. |
| 38 | + |
| 39 | +4. **Auth Success** |
| 40 | + 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. |
| 41 | + |
| 42 | +### Sequence Diagram |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +## Key Points to Remember |
| 47 | + |
| 48 | +- **`showOnboardingModal()`** in the SDK is your main entry point to launch the modal. |
| 49 | +- You can customize brand data, theming, and the primary auth method (Email, Phone, or Google). |
| 50 | +- For Google OAuth, provide a callback (`gAuthCallback`) that returns an ID token from your chosen sign-in flow (e.g., `google_sign_in` package). |
| 51 | +- On success, your app will have the user’s `authToken` (and refresh token) stored in Okto’s internal state. |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +# Enabling Google Authentication in the Onboarding Modal |
| 56 | + |
| 57 | +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. |
| 58 | + |
| 59 | +**Example `login_page.dart` snippet:** |
| 60 | + |
| 61 | +```dart |
| 62 | +import 'package:google_sign_in/google_sign_in.dart'; |
| 63 | +import 'package:example/okto.dart'; // or your own utils |
| 64 | +import 'package:flutter/material.dart'; |
| 65 | +import '../screens/home/home_page.dart'; |
| 66 | +
|
| 67 | +class LoginPage extends StatefulWidget { |
| 68 | + const LoginPage({super.key}); |
| 69 | +
|
| 70 | + @override |
| 71 | + State<LoginPage> createState() => _LoginPageState(); |
| 72 | +} |
| 73 | +
|
| 74 | +class _LoginPageState extends State<LoginPage> { |
| 75 | + @override |
| 76 | + Widget build(BuildContext context) { |
| 77 | + return Scaffold( |
| 78 | + backgroundColor: const Color(0xff5166EE), |
| 79 | + body: SafeArea( |
| 80 | + child: Column( |
| 81 | + children: [ |
| 82 | + // ... other login methods here ... |
| 83 | + ElevatedButton( |
| 84 | + onPressed: () async { |
| 85 | + // This uses the Okto Onboarding flow with a callback for Google sign-in |
| 86 | + await okto!.openOnboarding( |
| 87 | + context: context, |
| 88 | + gAuthCallback: _loginWithGoogle, |
| 89 | + onLoginSuccess: _handleLoginSuccess, |
| 90 | + primaryAuth: AuthType.GAuth, // sets Google as the primary |
| 91 | + title: "My Flutter App", |
| 92 | + iconUrl: "https://example.com/icon.png", |
| 93 | + subtitle: "Welcome to Web3 with Okto", |
| 94 | + ); |
| 95 | + }, |
| 96 | + child: const Text('Onboarding (Google)'), |
| 97 | + ), |
| 98 | + ], |
| 99 | + ), |
| 100 | + ), |
| 101 | + ); |
| 102 | + } |
| 103 | +
|
| 104 | + Future<String> _loginWithGoogle() async { |
| 105 | + final GoogleSignIn googleSignIn = GoogleSignIn( |
| 106 | + scopes: [ |
| 107 | + 'email', |
| 108 | + 'https://www.googleapis.com/auth/userinfo.profile', |
| 109 | + 'openid', |
| 110 | + ], |
| 111 | + ); |
| 112 | + try { |
| 113 | + final user = await googleSignIn.signIn(); |
| 114 | + final auth = await user?.authentication; |
| 115 | + if (auth == null) return ""; |
| 116 | + return auth.idToken ?? ""; |
| 117 | + } catch (e) { |
| 118 | + debugPrint("GAuth Error: $e"); |
| 119 | + return ""; |
| 120 | + } |
| 121 | + } |
| 122 | +
|
| 123 | + void _handleLoginSuccess() { |
| 124 | + // Optionally, navigate or show a toast |
| 125 | + Navigator.pushReplacement( |
| 126 | + context, |
| 127 | + MaterialPageRoute(builder: (context) => const HomePage()), |
| 128 | + ); |
| 129 | + } |
| 130 | +} |
| 131 | +
|
| 132 | +``` |
| 133 | + |
| 134 | +**Key Steps:** |
| 135 | + |
| 136 | +- The callback `_loginWithGoogle` returns a Google ID token (or empty on error). |
| 137 | +- Okto uses this token to complete the Google auth process. |
| 138 | +- On success, `onLoginSuccess` is called, and your user is now fully authenticated. |
| 139 | + |
| 140 | +## Common Tips & FAQ |
| 141 | + |
| 142 | +- **Custom Branding:** Okto’s `openOnboarding(...)` lets you pass `title`, `subtitle`, `iconUrl` plus color theming to customize the look. |
| 143 | + |
| 144 | +- **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. |
0 commit comments