Install & configure Adapty SDK in a pure React Native project

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

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

要求

Adapty React Native SDK 要求 iOS 15.0 及以上版本。

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

安装 Adapty SDK

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

   # using npm
   npm install react-native-adapty
   
   # or using yarn
   yarn add react-native-adapty

2. 对于 iOS，安装 pods：

   cd ios && pod install

   ...
   buildscript {
     ...
     dependencies {
       ...
       classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0"
     }
   }
   ...

Adapty SDK 4.0：启用 Swift Package Manager

React Native SDK 4.0——新增了 Flow Builder 支持——要求 React Native 0.75 或更高版本。安装 SDK：

npm install react-native-adapty@^4.0.0

# or using yarn
yarn add react-native-adapty@^4.0.0

v4 通过 Swift Package Manager 而非 CocoaPods 子依赖项来拉取原生 iOS SDK（Adapty、AdaptyUI、AdaptyPlugin）（CocoaPods 的 spec 仓库将于 2026 年 12 月进入只读状态）。SPM 需要动态框架——在 ios/Podfile 目标中添加以下内容，然后重新安装 pods：

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

如果您之前通过 CocoaPods 将 Adapty、AdaptyUI 或 AdaptyPlugin 作为子依赖项引入，请先从 Podfile 中删除所有显式的 pod 'Adapty'、pod 'AdaptyUI' 或 pod 'AdaptyPlugin' 行。

激活 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 政策、避免触发应用追踪透明度提示，或者您的应用不需要基于广告 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
   },
});

开发环境使用技巧

在开发阶段延迟 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
}

为本地测试设置模拟模式

对于本地开发和测试，您可以启用模拟模式，无需沙盒 App Store/Google Play 账号，从而加快迭代速度。模拟模式完全绕过 Adapty 的原生模块，返回模拟数据。

要启用模拟模式，请将 enableMock 设置为 true：

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

当模拟模式处于激活状态时：

• 所有 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(); // Optional: pass mockConfig to customize mock data

// Now you can call methods before activation

await adapty.activate('YOUR_PUBLIC_SDK_KEY');

故障排查

iOS 最低版本错误

如果遇到 iOS 最低版本错误，请更新你的 Podfile：

-platform :ios, min_ios_version_supported
+platform :ios, '15.0'

Android 自动备份清单冲突

部分 SDK（包括 Adapty）会自带 Android 自动备份配置。如果多个 SDK 都定义了备份规则，Android 清单合并工具可能会报错，提示 android:fullBackupContent、android:dataExtractionRules 或 android:allowBackup 相关问题。

常见错误示例：Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

要解决此问题，你需要：

• 告知清单合并工具使用应用自身的备份相关属性值。

• 创建备份规则文件，将 Adapty 的规则与其他 SDK 的规则合并。

1. 在清单中添加 tools 命名空间

在 AndroidManifest.xml 文件中，确保根标签 <manifest> 包含 tools：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. 在 <application> 中覆盖备份属性

在同一个 AndroidManifest.xml 文件中，更新 <application> 标签，使应用提供最终属性值，并告知清单合并工具替换库中的值：

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

如果某个 SDK 也设置了 android:allowBackup，请将其一并加入 tools:replace：

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. 创建合并后的备份规则文件

在 Android 项目的 res/xml/ 目录下创建 XML 文件，将 Adapty 的规则与其他 SDK 的规则合并。Android 根据系统版本使用不同的备份规则格式，同时创建两个文件可确保应用所支持的所有 Android 版本都能正常兼容。

Android 12 及更高版本（使用新的数据提取规则格式）：

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Android 11 及更低版本（使用旧版完整备份内容格式）：

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

在 Android 上从其他应用返回后购买失败

如果启动购买流程的 Activity 使用了非默认的 launchMode，当用户从 Google Play、银行应用或浏览器返回时，Android 可能会以错误的方式重新创建或复用该 Activity，导致购买结果丢失或被视为已取消。 为确保购买流程正常运行，请仅为启动购买流程的 Activity 使用 standard 或 singleTop 启动模式，避免使用其他模式。

在 AndroidManifest.xml 中，确保启动购买流程的 Activity 设置为 standard 或 singleTop：

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />

Podfile 中 SWIFT_VERSION 覆盖导致的 Swift 6 构建错误

在为 iOS 构建 React Native 应用时，你可能会在 Adapty pod 目标上遇到 Swift 6 编译错误。常见症状包括：AdaptyUIBuilderLogic 中的 @Sendable 不匹配、Adapty 类型缺少 Sendable 一致性，或 actor 隔离错误。

Adapty pod 声明了 s.swift_version = '6.0'，需要使用 Swift 6 进行构建。你自己的应用代码可以继续使用 Swift 5——只有 Adapty pod 目标（Adapty、AdaptyUI、AdaptyUIBuilder、AdaptyLogger、AdaptyPlugin）需要以 Swift 6 构建。 最常见的原因是 ios/Podfile 中的 post_install 钩子为每个 pod target 重写了 SWIFT_VERSION：

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

解决方法：将 Adapty 的 pod target 排除在覆盖范围之外：

post_install do |installer|
  installer.pods_project.targets.each do |target|
    next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger AdaptyPlugin].include?(target.name)
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

然后从 ios/ 目录运行 pod install 并重新构建。

如需验证，打开 ios/Pods/Pods.xcodeproj，选择 Adapty pod 目标 → Build Settings → Swift Language Version，确认显示为 Swift 6。