在 React Native SDK 中展示用户引导

如果您已使用编辑工具自定义了用户引导，则无需在移动应用代码中手动渲染以向用户展示。这类用户引导已包含应展示的内容及展示方式。

开始之前，请确保：

已安装 Adapty React Native SDK 3.8.0 或更高版本。
已创建用户引导。
已将用户引导添加到版位。

Adapty React Native SDK 提供两种展示用户引导的方式：

React 组件：嵌入式组件，可集成到您应用的架构和导航系统中。
模态展示

React 组件

要在现有组件树中嵌入用户引导，请在您的 React Native 组件层级中直接使用 AdaptyOnboardingView 组件。嵌入式组件允许您将其集成到应用的架构和导航系统中。

在 Android 上，我们建议为 AdaptyOnboardingView 进行额外配置，以避免出现视觉渲染瑕疵。请参阅系统 UI 与用户引导内容重叠（Android）。

import React, { useCallback } from 'react';
import { AdaptyOnboardingView } from 'react-native-adapty';
import type { OnboardingEventHandlers } from 'react-native-adapty';

function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
  const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
  const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onAnalytics={onAnalytics}
      onClose={onClose}
      onCustom={onCustom}
      onPaywall={onPaywall}
      onStateUpdated={onStateUpdated}
      onFinishedLoading={onFinishedLoading}
      onError={onError}
    />
  );
}

import React from 'react';
import { AdaptyOnboardingView } from 'react-native-adapty';

function MyOnboarding({ onboarding }) {
  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={{ flex: 1 }}
      eventHandlers={{
        onAnalytics(event, meta) { 
          // Handle analytics events
        },
        onClose(actionId, meta) { 
          // Handle close actions
        },
        onCustom(actionId, meta) { 
          // Handle custom actions
        },
        onPaywall(actionId, meta) { 
          // Handle paywall actions
        },
        onStateUpdated(action, meta) { 
          // Handle state updates
        },
        onFinishedLoading(meta) { 
          // Handle when onboarding finishes loading
        },
        onError(error) { 
          // Handle errors
        },
      }}
    />
  );
}

要将用户引导作为独立屏幕展示（用户可关闭），请对由 createOnboardingView 方法创建的 view 调用 view.present() 方法。每个 view 只能使用一次。如需再次展示用户引导，请再次调用 createOnboardingView 以创建新的 view 实例。

禁止在未重新创建的情况下复用同一个 view，否则将导致 AdaptyUIError.viewAlreadyPresented 错误。

import { createOnboardingView } from 'react-native-adapty';

const view = await createOnboardingView(onboarding);

// Optional: handle onboarding events (close, custom actions, etc)
// view.setEventHandlers({ ... });

try {
    await view.present();
} catch (error) {
    // handle the error
}

import { createOnboardingView } from 'react-native-adapty/dist/ui';

const view = await createOnboardingView(onboarding);

view.registerEventHandlers(); // handle close press, etc

try {
    await view.present();
} catch (error) {
    // handle the error
}

配置 iOS 展示样式

通过向 present() 方法传递 iosPresentationStyle 参数，配置付费墙在 iOS 上的展示方式。该参数接受 'full_screen'（默认）或 'page_sheet' 值。

try {
  await view.present(iosPresentationStyle: 'page_sheet');
} catch (error) {
  // handle the error
}

用户引导加载中的加载器

在 React Native 中展示用户引导时，您可能会注意到在用户引导出现之前有短暂的白屏或加载画面。这是因为底层原生视图正在初始化。您可以根据需求和工作流程，以不同方式处理此问题。

使用 onFinishedLoading 控制启动屏幕

此方式仅适用于 React 组件，不适用于模态展示。

React Native 推荐的做法是：在用户引导完全加载前，保持启动屏幕或自定义遮罩层可见，然后手动隐藏它。

使用 React 组件（AdaptyOnboardingView）时，请等待 onFinishedLoading 事件后再隐藏启动屏幕或遮罩层：

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}
        onFinishedLoading={onFinishedLoading}
        // ... other callbacks
      />
      {isLoading && <YourCustomLoadingOverlay />}
    </>
  );
}

import React, { useState } from 'react';
import { AdaptyOnboardingView } from 'react-native-adapty';

function MyOnboarding({ onboarding }) {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <>
      <AdaptyOnboardingView
        onboarding={onboarding}
        eventHandlers={{
          onFinishedLoading(meta) {
            // Hide your splash screen or custom overlay here
            setIsLoading(false);
          },
          // ... other handlers
        }}
      />
      {isLoading && <YourCustomLoadingOverlay />}
    </>
  );
}

自定义原生加载器

Expo 托管工作流不支持放置自定义原生布局（例如 Android 上的 res/layout）。对于 Expo 应用，控制启动屏幕或使用 React Native 遮罩层是唯一可行的方案。

您可以在 Android 和 iOS 上使用平台特定布局替换原生加载器。如果您使用模态展示，这是您唯一的选择。

但是，此方式对于 React Native 应用通常不够便捷：

需要分别实现 Android 和 iOS 版本
与 Expo 托管工作流不兼容

为每个平台定义占位符：

iOS：将 AdaptyOnboardingPlaceholderView.xib 添加到您的 Xcode 项目中。了解更多。
Android：在 res/layout 中创建 adapty_onboarding_placeholder_view.xml，并在其中定义占位符。了解更多。

自定义用户引导中链接的打开方式

自定义用户引导中链接的打开方式从 Adapty SDK v. 3.15.1 开始支持。

默认情况下，用户引导中的链接会在应用内浏览器中打开。这通过在应用内显示网页，提供无缝的用户体验，让用户无需切换应用即可查看。

如果您希望在外部浏览器中打开链接，可以将 externalUrlsPresentation 参数设置为 WebPresentation.BrowserOutApp 来自定义此行为：

import React, { useCallback } from 'react';
import { AdaptyOnboardingView, WebPresentation } from 'react-native-adapty';
import type { OnboardingEventHandlers } from 'react-native-adapty';

function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
  const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
  const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      externalUrlsPresentation={WebPresentation.BrowserOutApp} // default – BrowserInApp
      onAnalytics={onAnalytics}
      onClose={onClose}
      onCustom={onCustom}
      onPaywall={onPaywall}
      onStateUpdated={onStateUpdated}
      onFinishedLoading={onFinishedLoading}
      onError={onError}
    />
  );
}

import { createOnboardingView, WebPresentation } from 'react-native-adapty';

const view = await createOnboardingView(
  onboarding, 
  { externalUrlsPresentation: WebPresentation.BrowserOutApp } // default – BrowserInApp
);

try {
    await view.present();
} catch (error) {
    // handle the error
}

故障排查

系统 UI 与 Android 上的用户引导内容重叠

此设置仅在裸 React Native 项目中支持。

如果您使用 Expo 托管工作流，则无法直接添加此 Android 资源。要应用此设置，您必须创建一个自定义 Expo 配置插件，添加对应的 Android 资源并在 app.config.js 中注册。这是必要的，因为 Expo 会为您管理原生 Android 项目。

在 Android 上使用 AdaptyOnboardingView 时，状态栏和导航栏等系统 UI 元素可能会覆盖在付费墙内容之上。要防止这种情况，请在您的应用中添加以下布尔资源：

前往 android/app/src/main/res/values。如果没有 bools.xml 文件，请创建一个。
添加以下资源：

<resources>
    <bool name="adapty_onboarding_enable_safe_area_paddings">false</bool>
</resources>

请注意，该更改将全局应用于您应用中的所有用户引导。

后续步骤

展示用户引导后，您需要处理用户交互和事件。了解如何处理用户引导事件，以响应用户操作并跟踪分析数据。