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

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

如果你需要关于如何在 React Native 应用中实现应用内购买的完整教程，请查看此教程。

如需完整的实现步骤说明，也可以观看以下视频：

环境要求

Adapty React Native SDK 支持 iOS 13.0+，但使用付费墙编辑工具创建的付费墙需要 iOS 15.0+。

安装 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 的 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 会记录错误和其他重要信息，帮助你了解运行状况。目前支持以下日志级别：

级别	描述
error	仅记录错误
warn	记录错误以及 SDK 中不会导致严重错误但值得关注的消息
info	记录错误、警告及各类信息消息
verbose	记录调试时可能有用的所有附加信息，例如函数调用、API 请求等
您可以在应用中配置 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 政策、避免触发应用跟踪透明度提示，或者你的应用不需要基于广告 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
  },
});

参数	是否必填	描述
memoryStorageTotalCostLimit	可选	内存缓存总大小，单位为字节。默认值取决于平台。
memoryStorageCountLimit	可选	内存存储的条目数量上限。默认值取决于平台。
diskStorageSizeLimit	可选	磁盘文件大小上限，单位为字节。默认值取决于平台。

启用本地访问等级（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 配置 Mock 模式

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

默认情况下，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 的快速刷新功能在开发过程中会触发多次激活调用。要避免这个问题，请将 __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. 安装插件：

2. npx expo install expo-build-properties

3. 更新你的 Expo 配置文件（app.json 或 app.config.js），设置 iOS 部署目标版本：

{
    "expo": {
        // ...other Expo config...
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        // 仅使用核心 Adapty 功能时填 "13.0"，
                        // 如果使用付费墙编辑工具创建的付费墙则填 "15.0"。
                        "deploymentTarget": "15.0"
                    }
                }
            ],
        ]
    }
}

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

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

Android Auto Backup manifest 冲突

当你在 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 统一管理。