在 React Native SDK 中展示用户引导

如果你使用编辑工具自定义了用户引导，就无需在移动端代码中手动处理渲染逻辑来向用户展示它。这类用户引导已经包含了展示内容和展示方式的完整配置。

开始之前，请确认：

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

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

React 组件：嵌入式组件，可将其集成到应用的架构和导航系统中。
模态呈现

React 组件

如需将用户引导嵌入现有组件树，可在 React Native 组件层级中直接使用 AdaptyOnboardingView 组件。嵌入式组件让你能够将其集成到应用的架构和导航系统中。

在 Android 上，我们建议对 AdaptyOnboardingView 进行额外配置，以避免视觉渲染异常。详见系统界面遮挡 Android 用户引导内容。


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}
    />
  );
}


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 错误。


const view = await createOnboardingView(onboarding);

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

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


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 事件触发后再隐藏启动页或遮罩层：


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 />}
    </>
  );
}


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 v3.15.1 及以上版本。

默认情况下，用户引导中的链接会在应用内浏览器中打开。这样用户无需切换应用即可查看网页，体验更流畅。

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


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}
    />
  );
}


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

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

故障排查

Android 上系统 UI 遮挡用户引导内容

此设置仅在裸 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>

请注意，此更改会对应用中的所有用户引导全局生效。

后续步骤

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