控制 iOS SDK 中的 App Store 消息

App Store 有时需要向用户显示订阅相关消息：请求用户同意价格上涨、告知账单问题，或展示赢回优惠。默认情况下，StoreKit 会在应用打开时自行显示这些消息——即使在付费墙、用户引导或结账页面上方也会弹出。

如需自行决定展示时机，可将 Adapty SDK 切换为手动消息处理模式。SDK 会将每条消息加入待处理列表，应用在调用 showStoreMessages 时统一展示。

开始之前

您需要：

• Adapty iOS SDK 4.2 或更高版本：早期版本不支持 store messages API。
• 用户设备系统版本为 iOS 16、Mac Catalyst 16 或 visionOS 1 及以上：StoreKit 不会向运行早期版本的应用传递消息。macOS 不支持 store messages API。

启用手动处理

要捕获 App Store 消息，请在激活 SDK 时将 storeMessagesHandling 设置为 .manual：

let configurationBuilder = AdaptyConfiguration
    .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
    .with(storeMessagesHandling: .manual) // .auto is the default

SDK 在激活时开始捕获消息，并将其保存在当前应用会话的内存中。使用默认值 .auto 时，SDK 不会捕获任何内容，getPendingStoreMessageTypes 和 showStoreMessages 也不会执行任何操作。

获取待处理消息类型

如需查询是否有待处理的消息，请调用 getPendingStoreMessageTypes。该方法会返回待处理消息的类型，但不会展示或移除它们：

let pendingTypes = await Adapty.getPendingStoreMessageTypes()

if pendingTypes.contains(.billingIssue) {
    // For example, skip the upsell and show the billing message first
}

每条消息的类型为以下之一：

SDK 无法识别的消息类型，其原始值为 storekit_<number>。

显示待处理消息

当应用到达不会打断用户的时机时——例如用户关闭流程或完成用户引导后——调用 showStoreMessages：

struct HomeView: View {
    @Environment(\.displayStoreKitMessage) private var displayStoreKitMessage

    var body: some View {
        Text("Home")
            .task {
                do {
                    try await Adapty.showStoreMessages(using: displayStoreKitMessage)
                } catch {
                    // handle the error
                }
            }
    }
}

do {
    try await Adapty.showStoreMessages(in: view.window?.windowScene)
} catch {
    // handle the error
}

SDK 会逐条显示消息。StoreKit 显示某条消息后，SDK 会将其从待处理列表中移除。如果 StoreKit 未能显示某条消息，SDK 会将错误写入 Adapty 日志，保留该消息以供下次调用，并继续处理其他消息。

仅显示特定类型的消息

如需只显示部分待处理消息，请在 for 中传入对应类型。其余消息仍保持待处理状态：

try await Adapty.showStoreMessages(
    for: [.billingIssue, .priceIncreaseConsent],
    using: displayStoreKitMessage
)

不传 for 时，SDK 会显示所有待处理消息，包括它无法识别的类型。

错误

showStoreMessages 会抛出一个 AdaptyError，错误码如下：