在 Expo 项目中安装并配置 Adapty React Native SDK

Adapty SDK 包含两个核心模块，可无缝集成到你的 React Native 应用中：

• Core Adapty：此模块是 Adapty 正常运行的必要组件。
• AdaptyUI：此模块用于渲染流程及旧版编辑工具付费墙。AdaptyUI 会随核心模块自动激活。

如果你需要一个完整的教程，了解如何在 React Native 应用中实现应用内购买，请查看这篇文章。

如需完整的实现演示，您也可以观看以下视频：

系统要求

依赖项

Adapty SDK 在 Android 上支持以下 Google Play Billing Library 版本：

安装 Adapty SDK

我们始终建议安装最新版本的 SDK——它包含最新的稳定性修复和改进。

1. 安装 Adapty SDK：

   npx expo install react-native-adapty
   npx expo prebuild

2. 使用 EAS 或本地构建为开发环境构建应用：

# For iOS
eas build --profile development --platform ios

# For Android
eas build --profile development --platform android

# For iOS
npx expo run:ios

# For Android
npx expo run:android

3. 启动开发服务器：

   npx expo start --dev-client

为 Adapty SDK v4 启用动态框架

React Native SDK 4.0（新增对流程的支持）需要 React Native 0.75 或更高版本。安装 SDK：

npx expo install react-native-adapty@^4.0.0

v4 将原生 iOS SDK（Adapty、AdaptyUI、AdaptyPlugin）以 Swift 包的形式引入，而非 CocoaPods 子依赖（CocoaPods 的 spec 仓库将于 2026 年 12 月进入只读模式）。Swift 包采用动态链接，在 Expo 中可通过 expo-build-properties 插件启用。将其添加到 app.json（或 app.config.js）中：

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "dynamic"
          }
        }
      ]
    ]
  }
}

然后安装插件并重新生成原生项目：

npx expo install expo-build-properties
npx expo prebuild --clean

如果 iOS 构建时出现 'React/RCTBridge.h' file not found 错误，请参阅故障排查条目。

完整迁移步骤请参阅 Adapty React Native SDK 迁移至 v4。

激活 Adapty SDK 的 Adapty 模块

获取您的 Public SDK Key：

1. 打开 Adapty 看板，导航至 App settings → General。
2. 在 Api keys 部分，复制 Public SDK Key（不是 Secret Key）。
3. 将代码中的 "YOUR_PUBLIC_SDK_KEY" 替换为实际值。

或者，使用 Adapty CLI 以编程方式获取：

npm install -g adapty
adapty auth login
adapty apps list

或者，直接运行：

npx adapty auth login
adapty apps list

• 请确保使用 Public SDK key 初始化 Adapty，Secret key 仅用于服务端 API。
• SDK keys 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的那个。

将以下代码复制到 App.tsx 以激活 Adapty：

adapty.activate('YOUR_PUBLIC_SDK_KEY');

现在在你的应用中配置付费墙：

• 如果您使用流程与付费墙编辑工具，请参阅快速入门指南。
• 如果您自行构建付费墙 UI，请参阅自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

如果你计划使用 Flow 与付费墙编辑工具，则需要 AdaptyUI 模块。当你激活核心模块时，它会自动激活，无需额外操作。

可选配置

日志记录

配置日志系统

Adapty 会记录错误和其他重要信息，帮助你了解运行状况。可用的日志级别如下：

您可以在应用中配置 Adapty 之前或期间设置日志级别：

// Set log level before activation
// 'verbose' is recommended for development and the first production release
adapty.setLogLevel('verbose');

// Or set it during configuration
adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  logLevel: 'verbose',
});

数据政策

Adapty 不会存储用户的个人数据，除非您主动发送，但您可以实施额外的数据安全策略，以符合应用商店或特定国家/地区的要求。

禁用 IP 地址收集与共享

在激活 Adapty 模块时，将 ipAddressCollectionDisabled 设置为 true 以禁用用户 IP 地址的收集与共享。默认值为 false。

使用此参数可以保护用户隐私、遵守地区数据保护法规（如 GDPR 或 CCPA），或在应用不需要基于 IP 的功能时减少不必要的数据收集。

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ipAddressCollectionDisabled: true,
});

禁用广告 ID 的收集与共享

在激活 Adapty 模块时，将 ios.idfaCollectionDisabled（iOS）或 android.adIdCollectionDisabled（Android）设置为 true 即可禁用广告标识符的收集。默认值为 false。

如需遵守 App Store/Play Store 政策、避免触发应用跟踪透明度（ATT）弹窗，或者你的应用不需要基于广告 ID 的广告归因或数据分析，可使用此参数。

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ios: {
    idfaCollectionDisabled: true,
  },
  android: {
    adIdCollectionDisabled: true,
  },
});

为 AdaptyUI 配置媒体缓存

AdaptyUI 默认会缓存媒体文件（如图片和视频），以提升性能并减少网络流量消耗。你可以通过提供自定义配置来调整缓存设置。

使用 mediaCache 覆盖默认缓存设置：

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  mediaCache: {
    memoryStorageTotalCostLimit: 200 * 1024 * 1024, // Optional: memory cache size in bytes
    memoryStorageCountLimit: 2147483647,            // Optional: max number of items in memory
    diskStorageSizeLimit: 200 * 1024 * 1024,       // Optional: disk cache size in bytes
  },
});

启用本地访问等级（Android）

默认情况下，本地访问等级在 iOS 上已启用，在 Android 上处于禁用状态。如需在 Android 上同样启用，请将 localAccessLevelAllowed 设置为 true：

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  android: {
     localAccessLevelAllowed: true,
  },
});

从备份恢复时清除数据

当 clearDataOnBackup 设置为 true 时，SDK 会检测应用是否从 iCloud 备份中恢复，并删除所有本地存储的 SDK 数据，包括已缓存的用户画像信息、产品详情和付费墙。SDK 随后会以全新状态重新初始化。默认值为 false。

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   ios: {
       clearDataOnBackup: true
   },
});

启用 Adapty 归因

如果您使用 Adapty 归因，请在激活 SDK 时将 adaptyAttributionEnabled 设置为 true。默认值为 false：不设置此参数时，SDK 不会注册安装事件，也不会向您的应用传递安装详情。在低于 4.1 的 SDK 版本中，Adapty 归因会自动启用。

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   adaptyAttributionEnabled: true,
});

开发环境使用技巧

为 Expo Go / Expo Web 配置模拟模式

Expo Go 和 Expo Web 环境无法访问 Adapty 的原生模块。为了在构建和测试应用 UI 及付费墙逻辑时避免运行时错误，Adapty 提供了模拟模式。

默认情况下，SDK 会自动检测 Expo Go 和 Web 环境并启用模拟模式。除非你想自定义模拟数据，否则无需做任何配置。

模拟模式激活后：

• 所有 Adapty 方法均返回模拟数据，不会向 Adapty 服务器发起网络请求。
• 默认情况下，初始模拟用户画像没有任何有效订阅。
• 默认情况下，makePurchase(...) 会模拟一次成功的购买并授予高级访问等级。

您可以在激活时通过 mockConfig 自定义模拟数据。配置格式和支持的参数请参阅此处。

try {
  await adapty.activate('YOUR_PUBLIC_SDK_KEY', {
    mockConfig: {
      // Customize the initial mock profile (optional)
    },
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
}

如果需要在激活前调用 SDK 方法（例如 isActivated() 或 setLogLevel()），请在 activate() 之前调用 enableMock()。如果 bridge 已经初始化，此方法不会执行任何操作。

adapty.enableMock(); // 可选：传入 mockConfig 来自定义模拟数据

// 现在可以在激活前调用方法

await adapty.activate('YOUR_PUBLIC_SDK_KEY');

出于开发目的延迟 SDK 激活

Adapty 在 SDK 激活时会预先获取所有必要的用户数据，从而更快地访问最新数据。

但在 iOS 模拟器中，这可能会带来问题——开发过程中模拟器经常弹出身份验证提示。虽然 Adapty 无法控制 StoreKit 的身份验证流程，但可以延迟 SDK 获取最新用户数据的请求时机。

启用 __debugDeferActivation 属性后，activate 调用会被挂起，直到你发起下一次 Adapty SDK 调用。这样一来，如果不需要身份验证数据，就不会触发多余的验证提示。

需要注意的是，此功能仅供开发阶段使用，因为它并不涵盖所有潜在的用户场景。在生产环境中，不应延迟激活，因为真实设备通常会记住认证数据，不会反复提示用户输入凭据。

以下是推荐的使用方式：

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __debugDeferActivation: isSimulator(), // 'isSimulator' from any 3rd party library
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

排查 React Native Fast Refresh 导致的 SDK 激活错误

在 React Native 中使用 Adapty SDK 进行开发时，你可能会遇到以下错误：Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.

这是因为 React Native 的快速刷新（fast refresh）功能会在开发过程中触发多次激活调用。为了避免这种情况，请将 __ignoreActivationOnFastRefresh 选项设置为 __DEV__（React Native 的开发模式标志）。

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __ignoreActivationOnFastRefresh: __DEV__,
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

故障排查

iOS 最低版本错误

在为 iOS 构建时，你可能会看到关于 最低 iOS 版本 或部署目标的错误。Adapty 要求 iOS 15.0+。

由于 Expo 在执行 expo prebuild 时会自动生成 iOS 项目（包括 Podfile），请勿直接编辑 Podfile。应通过 expo-build-properties 配置插件来设置部署目标。

1. 安装插件：

   npx expo install expo-build-properties

2. 更新你的 Expo 配置（app.json 或 app.config.js），设置 iOS 部署目标：

{
    "expo": {
        // ...other Expo config...
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        // Adapty requires iOS 15.0+.
                        "deploymentTarget": "15.0"
                    }
                }
            ],
        ]
    }
}

3. 重新生成原生 iOS 项目并重新构建：

npx expo prebuild --clean
npx expo run:ios      # or `eas build -p ios` on your CI

Android 自动备份清单冲突

当使用 Expo 并集成多个配置 Android Auto Backup 的 SDK（如 Adapty、AppsFlyer 或 expo-secure-store）时，可能会遇到 manifest 合并冲突。

典型的错误如下：Manifest merger failed : Attribute application@fullBackupContent value=(@xml/secure_store_backup_rules) from AndroidManifest.xml:24:248-306 is also present at [io.adapty:android-sdk:3.12.0] AndroidManifest.xml:9:18-70 value=(@xml/adapty_backup_rules).

要解决此冲突，您需要让 Adapty 插件管理 Android 备份配置。 如果您的项目也使用了 expo-secure-store，请禁用其自身的备份设置以避免冲突。

以下是配置 app.json 的方法：

{
  "expo": {
    "plugins": [
      ["react-native-adapty", { "replaceAndroidBackupConfig": true }],
      ["expo-secure-store", { "configureAndroidBackup": false }]
    ]
  }
}

replaceAndroidBackupConfig 选项默认为 false。启用后，Adapty 插件将接管 Android 备份规则的控制权。 如果你使用了 expo-secure-store，请添加 "configureAndroidBackup": false 以避免警告，因为 SecureStore 的备份配置现在将由 Adapty 统一管理。

iOS 构建失败，报错 'React/RCTBridge.h' file not found

在为 Adapty SDK v4 启用动态框架后，iOS 构建可能在 expo-updates、@expo/ui 或其他包含 Objective-C 源文件的包中失败，报错如下：

error: 'React/RCTBridge.h' file not found

该故障是由 expo-modules-autolinking 包（expo 的依赖项）中的一个缺陷引起的。受影响的版本为 57.0.5–57.0.9（Expo SDK 57）和 56.0.19–56.0.21（Expo SDK 56）；该缺陷已在 57.0.10 和 56.0.22 中修复。

要修复构建问题，请将 expo-modules-autolinking 更新到已修复的版本并重新生成原生项目：

npm update expo-modules-autolinking
npx expo prebuild

如果当前使用的 Expo SDK 版本尚未提供已修复的版本，请改为从源码构建 React Native。此方法可以绕过该缺陷，但会导致 iOS 构建时间变长：

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "dynamic",
            "buildReactNativeFromSource": true
          }
        }
      ]
    ]
  }
}