---
title: "Capacitor - Adapty SDK 安装与配置"
description: "基于订阅的应用在 Capacitor 上安装 Adapty SDK 的分步指南。"
---

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

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

:::tip
想查看 Adapty SDK 集成到移动应用中的真实示例？请查看我们的[示例应用](https://github.com/adaptyteam/AdaptySDK-Capacitor/tree/master/examples)，其中展示了完整的设置流程，包括显示付费墙、进行购买及其他基本功能。
:::

## 要求 \{#requirements\}

[Adapty Capacitor SDK](https://github.com/adaptyteam/AdaptySDK-Capacitor/) 的版本要求如下：

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

不支持 Capacitor 6 及以下版本。

:::info
Adapty 兼容 Google Play Billing Library 8.x 及以下版本。默认情况下，Adapty 使用 Google Play Billing Library v.7.0.0，但如果您希望强制使用更高版本，可以手动[添加依赖项](https://developer.android.com/google/play/billing/integrate#dependency)。
:::

---
no_index: true
---
import Callout from '../../../components/Callout.astro';

<Callout type="info">
安装 SDK 是 Adapty 配置流程的第 5 步。在您的应用内购买功能正常运行之前，您还需要将应用连接到应用商店，然后在 Adapty 控制台中创建产品、付费墙和版位。[快速入门指南](quickstart) 将引导您完成所有必要步骤。
</Callout>

## 安装 Adapty SDK \{#install-adapty-sdk\}

[![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-Capacitor.svg?style=flat&logo=capacitor)](https://github.com/adaptyteam/AdaptySDK-Capacitor/releases)

安装 Adapty SDK：

```sh 
npm install @adapty/capacitor
npx cap sync   
```

## 激活 Adapty SDK 的 Adapty 模块 \{#activate-adapty-module-of-adapty-sdk\}

:::note
Adapty SDK 在您的应用中只需激活一次。
:::

要获取您的 **Public SDK Key**：

1. 前往 Adapty 控制台，导航至 [**App settings → General**](https://app.adapty.io/settings/general)。
2. 在 **Api keys** 部分，复制 **Public SDK Key**（不是 Secret Key）。
3. 将代码中的 `"YOUR_PUBLIC_SDK_KEY"` 替换为您的密钥。

:::important

- 请确保使用 **Public SDK key** 进行 Adapty 初始化，**Secret key** 仅应用于[服务端 API](getting-started-with-server-side-api)。
- **SDK keys** 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的密钥。
:::

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

```typescript showLineNumbers

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

:::tip
为避免开发环境中的激活错误，请使用[相关提示](#development-environment-tips)。
:::

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

- 如果您使用 [Adapty 付费墙编辑工具](adapty-paywall-builder)，请参照[付费墙编辑工具快速入门](capacitor-quickstart-paywalls)。
- 如果您自行构建付费墙 UI，请参阅[自定义付费墙快速入门](capacitor-quickstart-manual)。

## 激活 Adapty SDK 的 AdaptyUI 模块 \{#activate-adaptyui-module-of-adapty-sdk\}

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

## 可选配置 \{#optional-setup\}

### 日志记录 \{#logging\}

#### 设置日志系统 \{#set-up-the-logging-system\}

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

| 级别      | 描述                                                  |
| ---------- | ------------------------------------------------------------ |
| `error`    | 仅记录错误                                    |
| `warn`     | 记录错误以及 SDK 中不会导致严重错误但值得关注的消息 |
| `info`     | 记录错误、警告及各种信息消息 |
| `verbose`  | 记录调试期间可能有用的任何附加信息，例如函数调用、API 查询等 |

您可以在激活 Adapty 之前或期间在应用中设置日志级别：

```typescript showLineNumbers
// 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',
  }
});
```

### 数据政策 \{#data-policies\}

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

#### 禁用 IP 地址收集和共享 \{#disable-ip-address-collection-and-sharing\}

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

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

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

#### 禁用广告 ID 收集和共享 \{#disable-advertising-id-collection-and-sharing\}

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

使用此参数可遵守 App Store/Play Store 政策、避免触发 App Tracking Transparency 提示，或在您的应用不需要基于广告 ID 的广告归因或数据分析时使用。

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

#### 为 AdaptyUI 设置媒体缓存配置 \{#set-up-media-cache-configuration-for-adaptyui\}

默认情况下，AdaptyUI 会缓存媒体（如图片和视频）以提高性能并减少网络使用。您可以通过提供自定义配置来自定义缓存设置。

使用 `mediaCache` 覆盖默认缓存设置：

```typescript showLineNumbers
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） \{#enable-local-access-levels-android\}

默认情况下，[本地访问等级](local-access-levels) 在 iOS 上已启用，在 Android 上已禁用。要在 Android 上也启用此功能，请将 `localAccessLevelAllowed` 设置为 `true`：

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

### 备份恢复时清除数据 \{#clear-data-on-backup-restore\}

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

:::note
仅删除本地 SDK 缓存。与 Apple 的交易历史记录及 Adapty 服务器上的用户数据保持不变。
:::

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

## 开发环境提示 \{#development-environment-tips\}

#### 排查 Capacitor 热重载中的 SDK 激活错误 \{#troubleshoot-sdk-activation-errors-on-capacitors-live-reload\}

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

这是因为 Capacitor 的热重载功能在开发过程中会触发多次激活调用。为防止此问题，请将 `__ignoreActivationOnFastRefresh` 选项设置为 Capacitor 的开发模式标志——具体值因您使用的打包工具而异。

```typescript showLineNumbers
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
}
```

## 问题排查 \{#troubleshooting\}

#### iOS 最低版本错误 \{#minimum-ios-version-error\}

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

```diff
-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 备份规则（自动备份配置） \{#android-backup-rules-auto-backup-configuration\}

部分 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)`

:::note
这些更改应在您的 Android 平台目录中进行（通常位于项目的 `android/` 文件夹中）。
:::

要解决此问题，您需要：

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

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

#### 1. 在清单中添加 `tools` 命名空间 \{#1-add-the-tools-namespace-to-your-manifest\}

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

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

    ...
</manifest>
```

#### 2. 在 `<application>` 中覆盖备份属性 \{#2-override-backup-attributes-in-application\}

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

```xml
<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`：

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

#### 3. 创建合并后的备份规则文件 \{#3-create-merged-backup-rules-files\}

在您 Android 项目的 `res/xml/` 目录中创建 XML 文件，将 Adapty 的规则与其他 SDK 的规则合并。Android 根据操作系统版本使用不同的备份规则格式，因此同时创建这两个文件可确保您的应用在所有支持的 Android 版本上的兼容性。

:::note
以下示例使用 AppsFlyer 作为第三方 SDK 的示例。请替换或添加您应用中实际使用的其他 SDK 的规则。
:::

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

```xml title="sample_data_extraction_rules.xml"
<?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 title="sample_backup_rules.xml"
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

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

:::tip
修改原生 Android 文件后，如果您重新生成平台，请运行 `npx cap sync android` 以使 Capacitor 获取更新后的资源。
:::

#### 在 Android 上从其他应用返回后购买失败 \{#purchases-fail-after-returning-from-another-app-in-android\}

如果启动购买流程的 Activity 使用了非默认的 `launchMode`，当用户从 Google Play、银行应用或浏览器返回时，Android 可能会错误地重建或复用该 Activity。这可能导致购买结果丢失或被视为已取消。

为确保购买正常运行，启动购买流程的 Activity 只能使用 `standard` 或 `singleTop` 启动模式，避免使用其他任何模式。

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

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