Install & configure Adapty React Native SDK in an Expo project

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

• Core Adapty：此模块是 Adapty 在您的应用中正常运行的必要组件。
• AdaptyUI：如果您使用 Adapty 付费墙编辑工具——一款无需编写代码即可轻松创建跨平台付费墙的工具，则需要此模块。AdaptyUI 会随核心模块一并自动激活。

如果您需要一份关于如何在 React Native 应用中实现 IAP 的完整教程，请参阅这篇文章。

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

要求

Adapty React Native SDK 要求 iOS 15.0 或更高版本。

构建 iOS 需要 Swift 6.0 或更高版本。儿童模式 需要 Swift 6.1 或更高版本。

安装 Adapty SDK

1. 安装 Adapty SDK（同时会自动安装 @adapty/core）：

   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 4.0：启用 Swift Package Manager

React Native SDK 4.0（新增 Flow Builder 支持）需要 React Native 0.75 或更高版本。安装 SDK：

npx expo install react-native-adapty@^4.0.0

v4 通过 Swift Package Manager 而非 CocoaPods 子依赖来拉取原生 iOS SDK（Adapty、AdaptyUI、AdaptyPlugin）（CocoaPods 的 spec 仓库将于 2026 年 12 月变为只读）。SPM 需要动态框架，在 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

完整迁移步骤请参阅 将 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');

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

• 如果您使用 Adapty 付费墙编辑工具，请参考付费墙编辑工具快速入门。
• 如果您自行构建付费墙 UI，请参考自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

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

可选配置

日志记录

配置日志系统

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

开发环境使用技巧

为 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 统一管理。