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

• Core Adapty：此模块是 Adapty 正常运行的必要组件。
• AdaptyUI：此模块负责渲染流程以及旧版编辑工具付费墙。AdaptyUI 会随核心模块自动激活。

系统要求

Adapty Capacitor SDK 的版本要求如下：

Adapty SDK 版本	Capacitor 版本	iOS 版本
4.1+	8	15.0+
3.16.0+	8	15.0+
3.15	7	14.0+

不支持 Capacitor 6 及以下版本。

构建 iOS 应用需要 Xcode 26 或更高版本——原生 iOS SDK 使用 Swift tools 6.2 构建。Android 最低支持 SDK 24。

依赖关系

Adapty SDK 在 Android 上支持以下 Google Play Billing Library 版本：

Adapty SDK 版本	Billing Library 版本
3.17.0 及以上	v8
3.15.0–3.16.3	默认使用 v7，若其他依赖将其提升则使用 v8

安装 Adapty SDK

我们始终建议安装最新版本的 SDK——它包含最新的稳定性修复和改进。

安装 Adapty SDK：

npm install @adapty/capacitor
npx cap sync

在 iOS 上，Adapty SDK 仅通过 Swift Package Manager 拉取原生 Adapty SDK——CocoaPods podspec 已被移除（CocoaPods 的 spec 仓库将于 2026 年 12 月变为只读）。您的应用 iOS 项目必须使用 Capacitor 的 SPM 集成：

• 对于新应用，使用 SPM 包管理器添加 iOS 平台：

  npx cap add ios --packagemanager SPM

• 对于现有应用，按照 Capacitor 迁移至 SPM 的指南，将 iOS 项目从 CocoaPods 迁移到 SPM。

从 v3 升级？请参阅将 Adapty Capacitor SDK 迁移至 v4.1，了解完整的 API 变更列表。

激活 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 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的那个。

将以下代码复制到任意应用文件中以激活 Adapty：

try {
  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
      // verbose logging is recommended for the development purposes and for the first production release
        logLevel: 'verbose',
      // in the development environment, use this variable to avoid multiple activation errors. Set it to your development environment variable
      __ignoreActivationOnFastRefresh: true,
    }
  });
  console.log('Adapty activated successfully!');
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
}

接下来在应用中配置付费墙：

• 如果你使用 Flow & Paywall Builder，请参阅快速入门指南。
• 如果你自行构建付费墙 UI，请参阅自定义付费墙快速入门指南。

激活 Adapty SDK 的 AdaptyUI 模块

如果你打算使用 Flow & 付费墙编辑工具，则需要 AdaptyUI 模块。该模块会在激活核心模块时自动启用，无需额外操作。

可选配置

日志记录

配置日志系统

Adapty 会记录错误和其他重要信息，帮助你了解运行情况。可用的日志级别如下：

Level	Description
error	仅记录错误日志
warn	记录错误以及 SDK 中不会导致严重错误但值得关注的消息
info	记录错误、警告及各类信息消息
verbose	记录调试时可能有用的所有附加信息，例如函数调用、API 请求等

您可以在配置 Adapty 之前或配置过程中设置日志级别：

// Set log level before activation
adapty.setLogLevel({ logLevel: 'verbose' });

// Or set it during configuration
await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    logLevel: 'verbose',
  }
});

数据策略

Adapty 不会存储用户的个人数据，除非您明确发送，但您可以实施额外的数据安全策略，以符合应用商店或特定国家/地区的规定。

禁用 IP 地址收集与共享

在激活 Adapty 模块时，将 ipAddressCollectionDisabled 设置为 true 即可禁用用户 IP 地址的收集与共享。默认值为 false。

使用此参数可增强用户隐私保护、遵守区域性数据保护法规（如 GDPR 或 CCPA），或在应用不需要基于 IP 的功能时减少不必要的数据收集。

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    ipAddressCollectionDisabled: true,
  }
});

禁用广告 ID 的收集与共享

激活 Adapty 模块时，将 ios.idfaCollectionDisabled（iOS）或 android.adIdCollectionDisabled（Android）设置为 true 可禁用广告标识符的收集，默认值为 false。

如需遵守 App Store/Play Store 政策、避免触发应用跟踪透明度（App Tracking Transparency）提示，或者您的应用不需要基于广告 ID 的广告归因或数据分析，请使用此参数。

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    ios: {
      idfaCollectionDisabled: true,
    },
    android: {
      adIdCollectionDisabled: true,
    },
  }
});

为 AdaptyUI 配置媒体缓存

默认情况下，AdaptyUI 会缓存媒体内容（如图片和视频），以提升性能并减少网络流量。你可以通过自定义配置来调整缓存设置。

使用 mediaCache 覆盖默认缓存配置：

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    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：

await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
        android: {
            localAccessLevelAllowed: true,
        },
    }
});

备份恢复时清除数据

当 clearDataOnBackup 设置为 true 时，SDK 会检测到应用从 iCloud 备份中恢复，并删除所有本地存储的 SDK 数据，包括缓存的用户画像信息、产品详情和付费墙。SDK 随后将以全新状态重新初始化。默认值为 false。

await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
        ios: {
            clearDataOnBackup: true,
        },
    }
});

启用 Adapty 归因

如果您使用 Adapty 归因，请在激活 SDK 时将 adaptyAttributionEnabled 设置为 true。默认值为 false：不设置此参数时，SDK 不会注册安装事件，也不会向您的应用传递安装详情。在低于 4.1 的 SDK 版本中，Adapty 归因会自动启用。

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    adaptyAttributionEnabled: true,
  }
});

开发环境使用技巧

排查 Capacitor 热重载时的 SDK 激活报错

在 Capacitor 中使用 Adapty SDK 开发时，你可能会遇到以下报错：Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.

这是因为 Capacitor 的热重载功能在开发过程中会多次触发激活调用。要避免此问题，请将 __ignoreActivationOnFastRefresh 选项设置为 Capacitor 的开发模式标志——具体取值取决于你所使用的打包工具。

try {
  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
        // Set your development environment variable
      __ignoreActivationOnFastRefresh: true,
    }
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

故障排除

iOS 最低版本错误

如果在 SDK 3.x 上遇到 iOS 最低版本错误，请更新你的 Podfile：

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

Android 备份规则（自动备份配置）

部分 SDK（包括 Adapty）会附带自己的 Android Auto Backup 配置。如果您使用了多个定义备份规则的 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 构建 Capacitor 应用时，你可能会在 Adapty pod 目标上看到 Swift 6 编译错误。常见表现包括：AdaptyUIBuilderLogic 中的 @Sendable 不匹配、Adapty 类型缺少 Sendable 一致性，或 actor 隔离错误。

Adapty pods 声明了 s.swift_version = '6.0'，构建时需要 Swift 6。你自己的应用代码可以继续使用 Swift 5 —— 只有 Adapty 相关的 pod 目标（Adapty、AdaptyUI、AdaptyUIBuilder、AdaptyLogger、AdaptyPlugin）需要用 Swift 6 构建。

最常见的原因是 ios/App/Podfile 中存在 post_install 钩子，它会为所有 pod 目标重写 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 目标从覆盖范围中排除：

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

然后运行 npx cap sync ios 并重新构建。

如需验证，请打开 ios/App/Pods/Pods.xcodeproj，选择 Adapty pod target → Build Settings → Swift Language Version，确认显示的是 Swift 6。