在 Unity SDK 中控制商店消息

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

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

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

Warning

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

开始之前

你需要:

  • 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 及更高版本上调用它们:
#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

启用手动处理

如需仅在应用调用 Adapty.ShowStoreMessages 时才显示 Store 消息,请在激活 SDK 时使用 AdaptyStoreMessagesHandling.Manual 调用 SetStoreMessagesHandling:

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 将没有任何内容可返回或显示。

获取待处理的消息类型

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

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符合条件的赢回优惠。适用于 iOS 18 及更高版本。

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

显示消息

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

Adapty.ShowStoreMessages((error) => {
    if (error != null) {
        // handle the error
    }
});
  • iOS:SDK 会逐条显示待处理消息。StoreKit 显示某条消息后,SDK 会将其从待处理列表中移除。若 StoreKit 无法显示某条消息,SDK 会保留该消息留待下次调用,并继续处理其他消息。
  • Android:SDK 会针对当前 Activity 向 Google Play 请求消息。是否显示消息由 Google Play 决定,因此请求不一定会触发消息展示。若用户通过消息修复了支付方式,SDK 会将用户的购买记录同步至 Adapty,您的用户画像监听器将收到更新后的访问等级。

在 Android 上启动时显示消息

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

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 上,调用会失败。

仅显示部分消息类型

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

var iosFilter = new List<AdaptyStoreMessageType> {
    AdaptyStoreMessageType.BillingIssue,
    AdaptyStoreMessageType.PriceIncreaseConsent,
};

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

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

错误

Adapty.ShowStoreMessages 可能会失败,并返回带有以下错误码的 AdaptyError。除 WrongParam 外,其余错误仅在 iOS 上出现:

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