Improve onboarding loader docs

Author: eandreeva-twr

versioned_docs/version-3.0/flutter-present-onboardings.md

@@ -110,13 +110,38 @@ class MainActivity : FlutterFragmentActivity() {
 
 ## Loader during onboarding
 
-By default, between the splash screen and onboarding, you will see the loading screen until the onboarding is fully loaded. However, if you want to make the transition smoother, you can override this in your Flutter app:
+When presenting an onboarding, you may notice a short loading screen between your splash screen and the onboarding while the underlying view is being initialized. You can handle this in different ways depending on your needs.
 
-- To customize the native loader on iOS, add `AdaptyOnboardingPlaceholderView.xib` to your Xcode project.
-- For full control, overlay your own widget above `AdaptyUIOnboardingPlatformView` and hide it on `onDidFinishLoading`.
-- To customize the native loader on Android, create `adapty_onboarding_placeholder_view.xml` in `res/layout` and define a placeholder there.
+#### Control splash screen using onDidFinishLoading
 
-This helps create seamless transitions and custom loading experiences.
+:::note
+This approach is only available when embedding the onboarding as a widget. It is not available for standalone screen presentation.
+:::
+
+The recommended cross-platform approach is to keep your splash screen or custom overlay visible until the onboarding is fully loaded, then hide it manually.
+
+When using the embedded widget, overlay your own widget above it and hide the overlay when `onDidFinishLoading` fires:
+
+```dart showLineNumbers title="Flutter"
+AdaptyUIOnboardingPlatformView(
+  onboarding: onboarding,
+  onDidFinishLoading: (meta) {
+    // Hide your custom splash screen or overlay here
+  },
+  // ... other callbacks
+)
+```
+
+### Customize native loader
+
+:::important
+This approach is platform-specific and requires maintaining native UI code. It's not recommended unless you already maintain separate native layers in your app.
+:::
+
+If you need to customize the default loader itself, you can replace it with platform-specific layouts. This approach requires separate implementations for Android and iOS:
+
+- **iOS**: Add `AdaptyOnboardingPlaceholderView.xib` to your Xcode project
+- **Android**: Create `adapty_onboarding_placeholder_view.xml` in `res/layout` and define a placeholder there
 
 ## Customize how links open in onboardings
 

versioned_docs/version-3.0/react-native-present-onboardings.md

@@ -160,6 +160,100 @@ try {
 }
 ```
 
+## Loader during onboarding
+
+When presenting an onboarding in React Native, you may notice a short white flash or loading screen before the onboarding appears. This happens while the underlying native view is being initialized. You can handle this in different ways depending on your needs and your workflow.
+
+#### Control splash screen using onFinishedLoading
+
+:::note
+This approach is only available when using the React component. It is not available for modal presentation.
+:::
+
+The recommended approach for React Native is to keep your splash screen or a custom overlay visible until the onboarding is fully loaded, then hide it manually.
+
+When using the React component (`AdaptyOnboardingView`), wait for the `onFinishedLoading` event before hiding your splash screen or overlay:
+
+<Tabs groupId="version" queryString>
+<TabItem value="new" label="SDK version 3.14 or later" default>
+
+```typescript showLineNumbers title="React Native (TSX)"
+import React, { useCallback, useState } from 'react';
+import { AdaptyOnboardingView } from 'react-native-adapty';
+import type { OnboardingEventHandlers } from 'react-native-adapty';
+
+function MyOnboarding({ onboarding }) {
+  const [isLoading, setIsLoading] = useState(true);
+
+  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {
+    // Hide your splash screen or custom overlay here
+    setIsLoading(false);
+  }, []);
+
+  return (
+    <>
+      <AdaptyOnboardingView
+        onboarding={onboarding}
+        style={styles.container}
+        onFinishedLoading={onFinishedLoading}
+        // ... other callbacks
+      />
+      {isLoading && <YourCustomLoadingOverlay />}
+    </>
+  );
+}
+```
+
+</TabItem>
+
+<TabItem value="old" label="SDK version < 3.14">
+
+```typescript showLineNumbers title="React Native (TSX)"
+import React, { useState } from 'react';
+import { AdaptyOnboardingView } from 'react-native-adapty';
+
+function MyOnboarding({ onboarding }) {
+  const [isLoading, setIsLoading] = useState(true);
+
+  return (
+    <>
+      <AdaptyOnboardingView
+        onboarding={onboarding}
+        style={{ flex: 1 }}
+        eventHandlers={{
+          onFinishedLoading(meta) {
+            // Hide your splash screen or custom overlay here
+            setIsLoading(false);
+          },
+          // ... other handlers
+        }}
+      />
+      {isLoading && <YourCustomLoadingOverlay />}
+    </>
+  );
+}
+```
+
+</TabItem>
+</Tabs>
+
+#### Customize native loader
+
+:::important
+Expo does not support placing custom native layouts (e.g., `res/layout` on Android). For Expo apps, controlling the splash screen or using a React Native overlay is the only viable solution.
+:::
+
+You can replace the native loader using platform-specific layouts on Android and iOS. However, this approach is usually less convenient for React Native apps:
+
+- Requires separate Android and iOS implementations
+- Not compatible with Expo (Expo doesn't allow adding custom native layouts)
+- Higher maintenance cost
+
+Define a placeholder for each platform:
+
+- **iOS**: Add `AdaptyOnboardingPlaceholderView.xib` to your Xcode project
+- **Android**: Create `adapty_onboarding_placeholder_view.xml` in `res/layout` and define a placeholder there
+
 ## Customize how links open in onboardings
 
 :::important