---
title: "在 Unity SDK 中控制商店消息"
description: "选择 Unity 应用何时显示 App Store 和 Google Play 关于价格上涨、账单问题及付款失败的消息，以免它们打断流程或用户引导。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

App Store 和 Google Play 有时需要向用户显示与其订阅相关的消息：

- **App Store**: 一条价格上涨授权请求、账单问题通知或赢回优惠消息。默认情况下，StoreKit 会在应用打开时自动显示这些消息。
- **Google Play**: 一条订阅付款被拒绝、需要更新支付方式的通知。从 SDK 4.3.0 起，Adapty SDK 默认会在每次应用的 `Activity` 启动后（包括应用返回前台、流程或用户引导打开或关闭时）自动请求这些消息。

无论如何，消息都可能显示在流程、用户引导或结账页面之上。如需自行控制显示时机，请将 Adapty SDK 切换为手动消息处理模式，并在不影响用户体验的时机调用 `Adapty.ShowStoreMessages`。

:::warning
在手动模式下，商店不会自行显示消息。如果你的应用从未调用 `Adapty.ShowStoreMessages`，用户将永远看不到价格上涨确认请求、账单问题通知或付款失败通知。
:::

## 开始之前 \{#before-you-start\}

你需要：

- **Adapty Unity SDK 4.3.0 或更高版本**：早期版本不支持 store messages API。
- **iOS 16 或更高版本**（用于 App Store 消息）：StoreKit 不会向运行早期版本的应用投递消息。在 iOS 15 上，`Adapty.GetPendingStoreMessageTypes` 和 `Adapty.ShowStoreMessages` 会返回 `DecodingFailed` 错误，因此如果你的应用支持 iOS 15，请仅在 iOS 16 及更高版本上调用它们：

```csharp showLineNumbers title="C#"
#if UNITY_IOS && !UNITY_EDITOR
var iosMajorVersion = int.Parse(UnityEngine.iOS.Device.systemVersion.Split('.')[0]);
if (iosMajorVersion >= 16) {
    Adapty.ShowStoreMessages((error) => {
        // handle the error
    });
}
#endif
```

## 启用手动处理 \{#enable-manual-handling\}

如需仅在应用调用 `Adapty.ShowStoreMessages` 时才显示 Store 消息，请在[激活 SDK](sdk-installation-unity#activate-adapty-module-of-adapty-sdk) 时使用 `AdaptyStoreMessagesHandling.Manual` 调用 `SetStoreMessagesHandling`：

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetStoreMessagesHandling(AdaptyStoreMessagesHandling.Manual); // Auto is the default

Adapty.Activate(builder.Build(), (error) => {
    // handle the error
});
```

在 iOS 上，SDK 会将每条 App Store 消息加入当前应用会话的待处理列表。在 Android 上，SDK 会停止自主请求 Google Play 消息。若使用默认的 `Auto` 值，SDK 不会捕获 App Store 消息，因此在 iOS 上，`Adapty.GetPendingStoreMessageTypes` 和 `Adapty.ShowStoreMessages` 将没有任何内容可返回或显示。

## 获取待处理的消息类型 \{#get-pending-message-types\}

在 iOS 上，若要检查是否有待处理的 App Store 消息，请调用 `Adapty.GetPendingStoreMessageTypes`。该方法会返回待处理消息的类型，但不会显示或移除这些消息：

```csharp showLineNumbers title="C#"
Adapty.GetPendingStoreMessageTypes((pendingTypes, error) => {
    if (error != null) {
        // handle the error
        return;
    }

    if (pendingTypes == null) {
        // Android: Google Play decides whether a message applies when you show it
    } else if (pendingTypes.Contains(AdaptyStoreMessageType.BillingIssue)) {
        // For example, skip the upsell and show the billing message first
    }
});
```

在 Android 上，该方法返回 `null` 且不报告错误：Google Play 不会主动上报待处理消息，仅在应用主动请求时才会判断消息是否适用。空列表表示 iOS 上没有待处理消息。在 `Adapty.Activate` 完成之前，列表始终为空。

每条 App Store 消息都属于以下类型之一：

| 类型 | 消息 |
|:-----|:--------|
| `AdaptyStoreMessageType.Generic` | 通用 App Store 消息。 |
| `AdaptyStoreMessageType.PriceIncreaseConsent` | 订阅价格上涨同意请求。 |
| `AdaptyStoreMessageType.BillingIssue` | 订阅账单问题通知。适用于 iOS 16.4 及更高版本。 |
| `AdaptyStoreMessageType.WinBackOffer` | 符合条件的[赢回优惠](app-store-offers#win-back-offers)。适用于 iOS 18 及更高版本。 |

新的 StoreKit 消息类型会以 `RawValue` 为 `storekit_<number>` 的形式到达。要检查某个类型，请将其与上述值之一用 `==` 进行比较，对于其他任何值，则将其视为 SDK 无法识别的类型。

## 显示消息 \{#show-messages\}

当应用到达不会打断用户的时机时——例如，用户关闭某个流程或完成用户引导之后——调用 `Adapty.ShowStoreMessages`：

```csharp showLineNumbers title="C#"
Adapty.ShowStoreMessages((error) => {
    if (error != null) {
        // handle the error
    }
});
```

- **iOS**：SDK 会逐条显示待处理消息。StoreKit 显示某条消息后，SDK 会将其从待处理列表中移除。若 StoreKit 无法显示某条消息，SDK 会保留该消息留待下次调用，并继续处理其他消息。
- **Android**：SDK 会针对当前 `Activity` 向 Google Play 请求消息。是否显示消息由 Google Play 决定，因此请求不一定会触发消息展示。若用户通过消息修复了支付方式，SDK 会将用户的购买记录同步至 Adapty，您的[用户画像监听器](unity-listen-subscription-changes)将收到更新后的访问等级。

### 在 Android 上启动时显示消息 \{#show-messages-at-launch-on-android\}

在默认的 `Auto` 模式下，在激活之前启动的 `Activity` 不会触发请求，因此 Google Play 消息不会在启动时显示。要在启动时显示这些消息，请在 `Adapty.Activate` 完成后，仅在 Android 上调用一次 `Adapty.ShowStoreMessages`：

```csharp showLineNumbers title="C#"
Adapty.Activate(builder.Build(), (error) => {
    if (error != null) {
        // handle the error
        return;
    }

#if UNITY_ANDROID
    Adapty.ShowStoreMessages((showError) => {
        // handle the error
    });
#endif
});
```

不要在 iOS 上调用此方法：在 `Auto` 模式下，它没有任何内容可显示；而在 iOS 15 上，调用会失败。

### 仅显示部分消息类型 \{#show-only-some-message-types\}

若只需显示部分待处理的 App Store 消息，可将消息类型作为第一个参数传入。其余消息仍保持待处理状态：

```csharp showLineNumbers title="C#"
var iosFilter = new List<AdaptyStoreMessageType> {
    AdaptyStoreMessageType.BillingIssue,
    AdaptyStoreMessageType.PriceIncreaseConsent,
};

Adapty.ShowStoreMessages(iosFilter, (error) => {
    // handle the error
});
```

不设置过滤器或传入 `null` 时，SDK 会显示所有待处理消息，包括未知类型的消息。传入空列表则不显示任何消息。Android 会忽略过滤器，请求所有 Google Play 消息。

### 错误 \{#errors\}

`Adapty.ShowStoreMessages` 可能会失败，并返回带有以下错误码的 [`AdaptyError`](error-handling-on-flutter-react-native-unity)。除 `WrongParam` 外，其余错误仅在 iOS 上出现：

| 代码 | 名称 | 原因 |
|:-----|:-----|:------|
| 2006 | `DecodingFailed` | 设备运行的是 iOS 15 或更早版本。请仅在 iOS 16 及以上版本调用此方法。 |
| 3201 | `OperationInProgress` | 另一个 `Adapty.ShowStoreMessages` 调用仍在显示消息，而本次调用也有消息需要显示。请等待第一个调用完成后再重试。 |
| 3202 | `ResolverFailure` | SDK 未找到处于前台活跃状态的窗口场景来显示消息。请在应用处于前台时重新调用此方法。 |
| 3001 | `WrongParam` | 过滤列表中包含 `null`。SDK 在请求到达应用商店之前已拒绝此次调用。 |