借助 AI 将 Adapty 集成到 Kotlin Multiplatform 应用

本指南将带你逐步完成将 Adapty 集成到 Kotlin Multiplatform 应用的全过程，借助 AI 编程工具——按正确顺序向它提供相应的 Adapty 文档即可。

开始之前：看板配置

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

技能方式（推荐）

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

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

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

看板配置方式

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

连接应用商店：在 Adapty 看板中，前往 App settings → General。如果你的 KMP 应用同时面向两个平台，请同时连接 App Store 和 Google Play。这是购买功能正常运行的必要步骤。连接应用商店
复制您的 Public SDK key：在 Adapty 看板中，前往 App settings → General，找到 API keys 部分。在代码中，这就是您传入 Adapty 配置构建器的字符串。
至少创建一个产品：在 Adapty 看板中，前往 Products 页面。您无需在代码中直接引用产品 —— Adapty 会通过付费墙来下发产品。添加产品
创建付费墙和版位：在 Adapty 看板中，在 Paywalls 页面创建付费墙，然后在 Placements 页面将其分配到版位。在代码中，版位 ID 就是你传入 Adapty.getPaywall("YOUR_PLACEMENT_ID") 的字符串。创建付费墙
设置访问等级：在 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 文档。LLM 会根据你的提问自动获取相关文档，无需手动粘贴 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 Kotlin Multiplatform SDK

即使 Context7 省去了手动粘贴文档链接的步骤，实现顺序仍然很重要。请按照下方的实现步骤逐步操作，确保一切正常运行。

使用纯文本文档

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

下面实施流程中的每个阶段都包含一个”发送给你的 LLM”块，其中有可粘贴的 .md 链接。

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

实施流程

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

规划您的集成

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

告诉您的 LLM 您使用哪种购买方式——这会影响它应遵循的指南：

Adapty 付费墙编辑工具：在 Adapty 的无代码编辑工具中创建付费墙，SDK 会自动渲染。
手动创建付费墙：自行编写付费墙 UI，但仍使用 Adapty 获取产品并处理购买。
观察者模式：保留现有的购买基础设施，仅使用 Adapty 进行数据分析和集成。

不确定选哪个？请参阅快速入门中的对比表。

安装并配置 SDK

通过 Gradle 添加 Adapty SDK 依赖，并使用你的公共 SDK 密钥激活它。这是一切的基础——没有这一步，其他功能都无法正常使用。

指南： 安装并配置 Adapty SDK

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

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

Checkpoint

预期结果： 应用成功构建并运行。Logcat（Android）或 Xcode 控制台（iOS）显示 Adapty 激活日志。
常见问题： 出现 “Public API key is missing” 错误 → 检查是否已将占位符替换为 App settings 中的真实密钥。

展示付费墙并处理购买

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

建议边开发边在沙盒中测试每笔购买，不要等到最后再测。沙盒配置说明请参阅在沙盒中测试购买。

指南：

在编写代码之前，请阅读以下 Adapty 文档：
- https://adapty.io/docs/zh/kmp-quickstart-paywalls.md
- https://adapty.io/docs/zh/kmp-get-pb-paywalls.md
- https://adapty.io/docs/zh/kmp-present-paywalls.md
- https://adapty.io/docs/zh/kmp-handling-events.md
- https://adapty.io/docs/zh/kmp-handle-paywall-actions.md

Checkpoint

预期结果： 付费墙正常显示，并包含你配置的产品。点击某个产品会触发沙盒购买弹窗。
注意事项： 付费墙为空或 getPaywall 报错 → 请确认版位 ID 与看板中完全一致，且该版位已分配目标受众。

指南：

Read these Adapty docs before writing code:
- https://adapty.io/docs/zh/observer-vs-full-mode.md
- https://adapty.io/docs/zh/implement-observer-mode-kmp.md
- https://adapty.io/docs/zh/report-transactions-observer-mode-kmp.md

检查点

预期结果： 使用现有购买流程完成沙盒购买后，该交易应出现在 Adapty 看板的 Event Feed 中。
注意事项： 没有事件 → 请确认您已向 Adapty 上报交易，并且两个应用商店的服务端通知均已配置。

检查订阅状态

购买后，检查用户画像中的活跃访问等级，以限制高级内容的访问。

指南： 检查订阅状态

发送给你的 LLM：

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

检查点

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

关联用户

将应用的用户账户与 Adapty 用户画像绑定，让购买记录可以跨设备同步。

如果你的应用无需身份验证，请跳过此步骤。

指南： 关联用户

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

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

检查点

预期结果： 调用 Adapty.identify("your-user-id") 后，看板的 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 文档站合并为单个文件。体积较大——仅在需要完整内容时使用。
Kotlin Multiplatform 专属的 kmp-llms.txt 和 kmp-llms-full.txt：特定平台的子集，相比完整站点可节省 token 用量。