配置 App Store 集成
要将您的 iOS 应用连接到 Adapty,请在 App settings > iOS SDK 中填写 App Store 凭据。Adapty 随后将:
- 验证购买。
- 接收订阅事件。
- 保持您的产品与 App Store Connect 同步。
如果购买或订阅事件停止到达 Adapty,请逐项检查凭据。
开始之前:
- 您需要在 App Store Connect 中访问目标应用。如果应用尚未创建,请先配置 App Store Connect。如果您没有平台访问权限,请向相关人员申请。
- 您的团队需要访问 App Store Connect API——这是生成所需访问密钥的必要条件。如果团队尚未获得访问权限,请联系 Account Holder 申请开通。Apple 会对每个申请进行审核。
- 请打开两个浏览器标签页:一个打开 App Store Connect 中的应用页面,另一个打开 Adapty 中的 App settings > iOS SDK。在本指南的操作过程中,您需要在两个标签页之间复制相关信息。
概述
本指南中的每项凭据都是必需的。Adapty 将每项凭据用于与 App Store 数据交换的不同环节。要完成配置,请按以下七个步骤操作:
- 输入 Bundle ID 和 Apple App ID
- 输入 App 专属共享密钥
- 使用 Adapty 提供的 URL 启用 App Store 服务器通知
- 添加 App 内购买密钥
- 添加 App Store Connect API 密钥
- 安装 Adapty SDK 并进行沙盒购买
- 验证所有凭据
输入 Bundle ID 和 Apple App ID
在 App Store Connect 中,有两个值用于标识你的应用:Bundle ID 和 Apple ID(在 Adapty 中标记为 Apple App ID)。Adapty 需要 Bundle ID 来处理购买。有了 Apple ID,Adapty 可以:
- 在 App Store Connect 中查找你的产品,并在那里创建新产品。
- 显示你的产品在 App Store 中的状态和价格。
- 为留存消息提供实时消息服务。
- 向 AppsFlyer 等归因集成标识你的应用。
当您将应用添加到 App Store Connect 时,Apple 会分配 Apple ID,因此请在应用上架 App Store 之前就填写该 ID。
-
打开 App Store Connect,选择你的应用,进入 General > App Information 页面。
-
在 General Information 子版块中复制 Bundle ID。
只复制标识符本身——反向 DNS 格式,不含空格,例如
com.company.app。App Store Connect 在某些视图(如应用列表)中会在旁边显示应用名称,请勿将应用名称误粘贴,否则 Adapty 与 App Store 之间的连接验证将会失败。
- 从 Adapty 顶部菜单打开 App settings > iOS SDK 标签页,将复制的值粘贴到 Bundle ID 字段中。
- 返回 App Store Connect 中的 App information 页面,复制其中的 Apple ID。
- 在 Adapty 看板的 App settings > iOS SDK 页面中,将该 ID 粘贴到 Apple App ID 字段。
输入应用专用共享密钥
Adapty 需要应用专用共享密钥来验证购买凭证,并在 App Store Connect 中创建产品。
-
在 App Store Connect 中,打开应用的 App Information 页面。在 App-Specific Shared Secret 部分,点击 Manage。
-
复制密钥。如果该应用尚未生成密钥,请先点击 Generate。生成密钥需要在 App Store Connect 中拥有 Account Holder 或 Admin 角色。如果您没有上述角色,请联系拥有该角色的人员生成密钥并发送给您。
除非您是通过应用转让接收该应用,否则请勿点击 Regenerate:点击后,当前密钥将在所有使用该密钥的地方立即失效。
-
在 Adapty 中,将密钥粘贴到 App Store Connect shared secret 字段。
-
点击 Save。
使用 Adapty 提供的 URL 启用 App Store 服务器通知
主要文章:启用 App Store 服务器通知
Apple 会在续订、退款及其他订阅事件发生时,将服务器通知实时推送给 Adapty。即使您的应用未上报任何交易,Adapty 也会记录这些事件。
如果 Apple 已在向某台服务器发送这些通知,请在 App Store Connect 中替换其 URL 之前,先设置好转发。在 Adapty 中,将该服务器的 URL 填入 URL for forwarding raw Apple events 字段,然后点击 Save。Adapty 随后会将从 Apple 收到的通知转发到该服务器。
如果您的后端必须在 App Store Connect 中保留其 URL,请改为从后端将通知传递给 Adapty。
-
在 Adapty 中,打开你要连接的应用:每个 Adapty 应用都有自己独立的通知 URL。前往 App settings > iOS SDK。在 App Store server notifications 部分,从 URL for App Store server notifications 字段中复制 URL。
-
在 App Store Connect 中,打开你的应用的 App Information 页面。
-
在 App Store Server Notifications 部分,找到 Production Server URL。如果已有 URL,点击 Edit;否则点击 Set Up URL。
-
粘贴来自 Adapty 的 URL,然后点击 Save。
-
若要让沙盒测试中的通知也能到达 Adapty,请对 Sandbox Server URL 重复步骤 3 和 4。
添加应用内购买密钥
主要文章:将应用内购买密钥添加到 Adapty
Adapty 使用应用内购买密钥来验证购买并为促销活动签名。如果你还没有密钥文件,请先在 App Store Connect 中生成密钥。将密钥添加到 Adapty 的步骤如下:
-
要查找密钥的 Issuer ID 和 Key ID,请在 App Store Connect 中前往 Users and Access > Integrations > In-App Purchase。如果是其他人生成了密钥并将 Issuer ID、Key ID 和文件发送给您,请跳过此步骤。
-
在 Adapty 中,前往 App settings > iOS SDK。在 In-app purchase API (StoreKit 2) 部分,填写以下字段:
- Issuer ID:从 App Store Connect 的 In-App Purchase 页面复制。
- Key ID:从 In-App Purchase 页面的 Active 列表中复制,位于您下载的密钥旁边。
- Private key (.p8 file):上传您下载的文件。
-
Adapty 使用 In-App Purchase 密钥为促销活动签名。在 App Store promotional offers 部分,再次输入密钥:
- Subscription key ID:步骤 2 中的 Key ID。
- Subscription key (.p8 file):步骤 2 中的文件。
若使用了不同的密钥,保存时不会报错,但用户将无法收到促销活动。
-
点击 Save。Adapty 在保存页面之前,会通过 Apple 验证 In-app purchase API (StoreKit 2) 部分中的密钥。如果 Apple 拒绝该密钥,页面将显示”The provided field values are incorrect”:请检查相关值。
添加 App Store Connect API 密钥
Adapty 使用 App Store Connect API 密钥在 App Store Connect 中创建产品,并同步产品状态和价格。该密钥与内购密钥不同,但两者共享 Issuer ID 和 Key ID 这两个字段名称。
Adapty 需要一个具有 Admin 访问权限的团队密钥。如果你还没有,请先在 App Store Connect 中生成它。要在 Adapty 中连接该密钥:
-
要查找团队密钥的 Issuer ID 和 Key ID,请在 App Store Connect 中前往 Users and Access > Integrations > App Store Connect API,然后打开 Team Keys 标签页。如果其他人已生成密钥并将 Issuer ID、Key ID 和文件发送给您,请跳过此步骤。
-
在 Adapty 中,前往 App settings > iOS SDK。在 App Store Connect API key 部分,点击 Connect API Key。
-
填写以下字段:
- Issuer ID:从 App Store Connect 的 Team Keys 标签页复制。
- Key ID:从 Team Keys 标签页的 Active 列表中复制,位于您下载的密钥旁边。
- Private key (.p8 file):上传您为团队密钥下载的文件。
-
您可以稍后替换已连接的密钥,但无法将其移除。请确保该密钥来自拥有此应用的 App Store Connect 团队,然后点击 Connect。之后,您可以直接从 App Store Connect 的产品中选择每个 App Store Product ID,而无需手动输入。
Adapty 在您连接密钥时不会向 Apple 验证该密钥。错误的密钥不会给出任何关于密钥的提示信息:产品将不显示 App Store 状态,且 App Store Product ID 下拉列表保持为空。如需修复错误密钥,请替换它。
检查每个凭据是否有效
要确认 Adapty 能验证购买,请先在应用中安装 Adapty SDK,再进行沙盒购买。
沙盒购买只会用到部分凭据。请在购买后逐一验证,每当购买或订阅事件无法送达 Adapty 时,也请重新核查:
- Bundle ID、Apple App ID 和 App Store Connect shared secret:将这三个值与 App Store Connect App Information 页面上的 Bundle ID、Apple ID 以及 App-Specific Shared Secret 下的密钥进行比对。
- App Store server notifications:一旦有购买或续订通知到达 Adapty,该部分的状态会显示为 Active。如果显示其他状态,请检查服务器 URL。
- In-app purchase API (StoreKit 2):Adapty 在您保存时会向 Apple 验证密钥。如果之后应用内购买未能解锁任何访问等级,说明密钥可能已失效,请更换密钥。
- App Store promotional offers:确认 Subscription key ID 与 In-app purchase API (StoreKit 2) 部分中的 Key ID 一致。如果不一致,请在两个部分中输入相同的密钥。
- App Store Connect API key:Products 页面的 App Store status 列会显示每个 App Store 产品的状态。如果某个产品显示横线或 Not Connected,请检查密钥和 Apple App ID。
刚完成设置后,Analytics 中统计到的试用和购买数量可能多于安装量,也可能多于 Event Feed 中显示的数量。这是因为存在没有用户画像的交易:这些购买来自尚未打开过集成了 Adapty SDK 版本应用的用户。
Adapty 与应用商店报告之间的其他差异,源于各自统计购买的方式,而非凭据配置问题。
下一步
在发布应用前,请查看发布检查清单。
如果你的应用同时上架 Google Play,请连接该商店。