借助 AI 将 Adapty 集成到 Capacitor 应用

本指南将逐步带你用 AI 编程工具将 Adapty 集成到 Capacitor 应用中——你只需按正确顺序把合适的 Adapty 文档喂给它即可。

开始之前：看板配置

在编写任何 SDK 代码之前，Adapty 需要先完成一些看板配置。您可以通过交互式 LLM 技能，或手动通过看板来完成配置。

技能方式（推荐）

Adapty CLI 技能允许您的 LLM 直接设置应用、产品、访问等级、付费墙和版位——无需为每个步骤打开看板。您只需在看板中连接您的应用商店即可。

npx skills add adaptyteam/adapty-cli --skill adapty-cli

添加技能后，在您的 agent 中运行 /adapty-cli。它将引导您完成每个步骤——包括何时打开看板来连接您的应用商店。

看板配置方式

如果你更倾向于手动配置，以下是编写代码前需要准备的内容。LLM 无法自动从看板中获取这些值，需要你手动提供。

连接应用商店：在 Adapty 看板中，进入 App settings → General，将 App Store 和 Google Play 都连接上（如果你的 Capacitor 应用需要同时支持两个平台）。这是购买功能正常运行的必要前提。连接应用商店
复制你的 Public SDK key：在 Adapty 看板中，前往 App settings → General，找到 API keys 部分。在代码中，这就是你传给 adapty.activate() 的字符串。
至少创建一个产品：在 Adapty 看板中，前往 Products 页面。你不需要在代码中直接引用产品——Adapty 会通过付费墙来分发它们。添加产品
创建付费墙和版位：在 Adapty 看板中，在 Paywalls 页面创建付费墙，然后在 Placements 页面将其分配到版位。在代码中，版位 ID 就是传给 adapty.getFlow() 的字符串。创建付费墙
设置访问等级：在 Adapty 看板的 Products 页面中，按产品进行配置。在代码中，通过 profile.accessLevels['premium']?.isActive 检查对应字符串。默认的 premium 访问等级适用于大多数应用。如果付费用户会因购买的产品不同而获得不同功能的访问权限（例如 basic 方案与 pro 方案），请在开始编写代码之前创建额外的访问等级。

准备好这五项之后，就可以开始写代码了。告诉你的 LLM：“我的 Public SDK key 是 X，版位 ID 是 Y”，它就能生成正确的初始化和获取流程的代码。

准备就绪后的配置

以下内容不是开始编码的必要条件，但随着集成的成熟，您会希望用到它们：

A/B 测试：在 Placements 页面配置。无需更改代码。 A/B 测试
更多付费墙和版位：使用不同的版位 ID 添加更多 getPaywall 调用。
分析集成：在 Integrations 页面配置。不同集成的设置方式各有不同。请参阅分析集成和归因集成。

向您的 LLM 提供 Adapty 文档

使用 Context7（推荐）

Context7 是一个 MCP 服务器，可让你的 LLM 直接访问最新的 Adapty 文档。它会根据你的提问自动获取相关文档，无需手动粘贴 URL。

Context7 支持 Cursor、Claude Code、Windsurf 以及其他兼容 MCP 的工具。运行以下命令即可完成配置：

npx ctx7 setup

该命令会自动检测你的编辑器并配置 Context7 服务器。如需手动配置，请参阅 Context7 GitHub 仓库。配置完成后，在提示词中引用 Adapty 库：

Use the adaptyteam/adapty-docs library to look up how to install the Capacitor SDK

尽管 Context7 无需手动粘贴文档链接，实施顺序仍然重要。请按照下方的实施流程逐步操作，确保一切正常运行。

使用纯文本文档

您可以以纯文本 Markdown 格式访问任何 Adapty 文档。在其 URL 末尾添加 .md，或点击文章标题下方的 Copy for LLM。例如：adapty-cursor-capacitor.md。

下方实现演练中的每个阶段都包含一个”发送给您的 LLM”代码块，其中有可粘贴的 .md 链接。

如需一次获取更多文档，请参阅下方的索引文件和平台特定子集。

实现演练

本指南的其余部分按实现顺序介绍 Adapty 集成。每个阶段包含要发送给 LLM 的文档、完成后应看到的效果，以及常见问题。

规划集成方案

在开始写代码之前，先让你的 LLM 分析项目结构并制定实施计划。如果你使用的 AI 工具支持规划模式（例如 Cursor 或 Claude Code 的 plan 模式），建议先启用该模式，让 LLM 在生成代码前同时读取你的项目结构和 Adapty 文档。

告诉你的 LLM 你使用哪种购买方式——这会影响它需要参考的指南：

Adapty Flow Builder：在 Adapty 的无代码编辑工具中创建流程，SDK 自动完成渲染。
手动创建付费墙：用代码构建自己的付费墙界面，但仍使用 Adapty 获取产品并处理购买。
观察者模式：保留现有的购买基础设施，仅将 Adapty 用于数据分析和集成。

不确定该选哪个？请查看快速入门中的对比表格。

安装并配置 SDK

通过 npm 添加 Adapty SDK 依赖，并使用您的 Public SDK key 激活它。这是一切功能的基础——没有它，其他任何功能都无法正常运行。

指南： 安装并配置 Adapty SDK

本演示面向 Adapty Capacitor SDK v4（测试版）——即快速入门所介绍的 API。v4 尚处于预发布阶段，请确保你的 LLM 固定使用精确版本（npm install @adapty/capacitor@4.0.0-beta.2），而非安装最新的稳定版 3.x。请参阅 SDK 4.0 安装说明及迁移指南。

将以下内容发送给你的 LLM：

Read these Adapty docs before writing code:
- https://adapty.io/docs/zh/sdk-installation-capacitor.md

Checkpoint

预期结果： 应用在 iOS 和 Android 上均能构建并运行，控制台显示 Adapty 激活日志。
常见问题： 提示”Public API key is missing” → 检查是否已将占位符替换为 App settings 中的真实密钥。

展示付费墙并处理购买

通过版位 ID 获取付费墙、展示付费墙并处理购买事件。具体需要参考哪些指南，取决于你的购买处理方式。

每完成一个购买功能就在沙盒中测试一次，不要等到最后再统一测试。沙盒环境的配置说明请参见在沙盒中测试购买。

指南：

Read these Adapty docs before writing code:
- https://adapty.io/docs/zh/capacitor-quickstart-paywalls.md
- https://adapty.io/docs/zh/capacitor-get-pb-paywalls.md
- https://adapty.io/docs/zh/capacitor-present-paywalls.md
- https://adapty.io/docs/zh/capacitor-handling-events.md
- https://adapty.io/docs/zh/capacitor-handle-paywall-actions.md

Checkpoint

预期结果： 流程正常显示，并附带你配置的产品。点击某个产品后会触发沙盒购买对话框。
注意事项： 流程为空或出现 getFlow 错误 → 请确认版位 ID 与看板中的完全一致，且该版位已分配目标受众。

指南：

Read these Adapty docs before writing code:
- https://adapty.io/docs/zh/capacitor-quickstart-manual.md
- https://adapty.io/docs/zh/fetch-paywalls-and-products-capacitor.md
- https://adapty.io/docs/zh/present-remote-config-paywalls-capacitor.md
- https://adapty.io/docs/zh/capacitor-making-purchases.md
- https://adapty.io/docs/zh/capacitor-restore-purchase.md

检查点

预期结果： 自定义付费墙显示从 Adapty 获取的产品，点击产品触发沙盒购买对话框。
注意事项： 产品数组为空 → 请确认付费墙已在看板中分配产品，且版位已设置目标受众。

检查订阅状态

购买完成后，检查用户画像中是否存在有效的访问等级，以控制高级内容的访问权限。

指南： 检查订阅状态

发送给您的 LLM：

Read these Adapty docs before writing code:
- https://adapty.io/docs/zh/capacitor-check-subscription-status.md

检查点

预期效果： 沙盒购买完成后，profile.accessLevels['premium']?.isActive 返回 true。
注意事项： 购买后 accessLevels 为空 → 检查该产品在看板中是否已分配访问等级。

识别用户

将你的应用用户账号与 Adapty 用户画像关联，确保购买记录在多设备间同步保留。

如果你的应用无需登录认证，请跳过此步骤。

指南： 识别用户

将以下内容发送给你的 LLM：

Read these Adapty docs before writing code:
- https://adapty.io/docs/zh/capacitor-quickstart-identify.md

Checkpoint

预期结果： 调用 adapty.identify() 后，看板的 Profiles 部分会显示你的自定义用户 ID。
注意事项： 请在激活后、获取付费墙之前调用 identify，以避免匿名用户画像归因问题。

准备发布

当你的集成在沙盒环境中运行正常后，请按照发布检查清单逐项确认，确保一切已准备好上线。

指南： 发布检查清单

将以下内容发送给你的 LLM：

Read these Adapty docs before releasing:
- https://adapty.io/docs/zh/release-checklist.md

Checkpoint

预期效果： 所有检查项均已确认：商店连接、服务器通知、购买流程、访问等级检查及隐私合规要求。
常见问题： 缺少服务器通知 → 请在 App settings → iOS SDK 中配置 App Store 服务器通知，并在 App settings → Android SDK 中配置 Google Play 实时开发者通知。

纯文本文档索引文件

如果你需要为 LLM 提供超出单页范围的更广上下文，我们提供了列出或汇总所有 Adapty 文档的索引文件：

llms.txt：列出所有页面的 .md 链接。这是一项新兴标准，旨在让 LLM 更方便地访问网站内容。请注意，某些 AI 智能体（如 ChatGPT）需要先下载 llms.txt，再以文件形式上传到对话中。
llms-full.txt：将整个 Adapty 文档站合并为单一文件。体积较大——仅在需要完整内容时使用。
Capacitor 专属版本 capacitor-llms.txt 与 capacitor-llms-full.txt：平台专属子集，相比完整站点可节省 token 用量。