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

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

要求

Adapty Capacitor SDK 的版本要求如下：

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

不支持 Capacitor 6 及以下版本。

安装 Adapty SDK

安装 Adapty SDK：

npm install @adapty/capacitor
npx cap sync   

激活 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：

import { adapty } from '@adapty/capacitor';

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);
}

现在在您的应用中设置付费墙：

• 如果您使用 Adapty 付费墙编辑工具，请参照付费墙编辑工具快速入门。
• 如果您自行构建付费墙 UI，请参阅自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

如果您计划使用付费墙编辑工具，则需要 AdaptyUI 模块。激活核心模块时会自动完成此操作，您无需进行任何额外操作。

可选配置

日志记录

设置日志系统

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

级别	描述
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,
        },
    }
});

开发环境提示

排查 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 最低版本错误

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

-platform :ios, min_ios_version_supported
+platform :ios, '14.0'  # For core features only
# OR
+platform :ios, '15.0'  # If using paywalls created in the paywall builder

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" />