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
   
   # 适用于 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" 替换为您的密钥。

将以下代码复制到 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 相关政策、避免触发 App Tracking Transparency 弹窗，或者您的应用不需要基于广告 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, // 可选：内存缓存大小（字节）
    memoryStorageCountLimit: 2147483647,            // 可选：内存中最大条目数
    diskStorageSizeLimit: 200 * 1024 * 1024,       // 可选：磁盘缓存大小（字节）
  },
});

参数	是否必填	描述
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 配置模拟模式

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 属性后，激活调用会被挂起，直到你发起下一次 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. 安装插件：

   npx expo install expo-build-properties

2. 更新你的 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 清单冲突

在 Expo 中同时使用多个需要配置 Android Auto Backup 的 SDK（如 Adapty、AppsFlyer 或 expo-secure-store）时，可能会遇到清单合并冲突。

典型报错如下：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 统一处理。