Adapty SDK 包含两个关键模块，可无缝集成到您的 React Native 应用中：

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

如果您需要在 React Native 应用中实现 IAP 的完整教程，请查阅此文章。

您也可以观看以下视频，了解完整的实现流程：

环境要求

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

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

import { adapty } from 'react-native-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 跟踪透明度提示，或在应用不需要基于广告 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 配置模拟模式

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

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

模拟模式激活时：

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

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

import { adapty } from 'react-native-adapty';

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 已经初始化，此方法不执行任何操作。

import { adapty } from 'react-native-adapty';

adapty.enableMock(); // Optional: pass mockConfig to customize mock data

// Now you can call methods before activation

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 激活错误

在使用 Adapty SDK 进行 React Native 开发时，您可能会遇到以下错误：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 版本或部署目标的错误，尤其是在使用付费墙编辑工具创建的付费墙时，这些付费墙需要 iOS 15.0+。

由于 Expo 在 expo prebuild 期间会生成 iOS 项目（包括 Podfile），您不应直接编辑 Podfile。请通过 expo-build-properties config plugin 配置部署目标。

1. 安装插件：

   npx expo install expo-build-properties

2. 更新您的 Expo 配置文件（app.json 或 app.config.js）以设置 iOS 部署目标：

{
    "expo": {
        // ...other Expo config...
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        // Use "13.0" for core Adapty features only,
                        // or "15.0" if you use paywalls created in the paywall builder.
                        "deploymentTarget": "15.0"
                    }
                }
            ],
        ]
    }
}

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

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

Android 自动备份清单冲突

当在 Expo 中同时使用多个配置了 Android 自动备份的 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 处理。