在 Unity SDK 中控制商店消息
App Store 和 Google Play 有时需要向用户显示与其订阅相关的消息:
- App Store: 一条价格上涨授权请求、账单问题通知或赢回优惠消息。默认情况下,StoreKit 会在应用打开时自动显示这些消息。
- Google Play: 一条订阅付款被拒绝、需要更新支付方式的通知。从 SDK 4.3.0 起,Adapty SDK 默认会在每次应用的
Activity启动后(包括应用返回前台、流程或用户引导打开或关闭时)自动请求这些消息。
无论如何,消息都可能显示在流程、用户引导或结账页面之上。如需自行控制显示时机,请将 Adapty SDK 切换为手动消息处理模式,并在不影响用户体验的时机调用 Adapty.ShowStoreMessages。
在手动模式下,商店不会自行显示消息。如果你的应用从未调用 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 上出现:
| 代码 | 名称 | 原因 |
|---|---|---|
| 2006 | DecodingFailed | 设备运行的是 iOS 15 或更早版本。请仅在 iOS 16 及以上版本调用此方法。 |
| 3201 | OperationInProgress | 另一个 Adapty.ShowStoreMessages 调用仍在显示消息,而本次调用也有消息需要显示。请等待第一个调用完成后再重试。 |
| 3202 | ResolverFailure | SDK 未找到处于前台活跃状态的窗口场景来显示消息。请在应用处于前台时重新调用此方法。 |
| 3001 | WrongParam | 过滤列表中包含 null。SDK 在请求到达应用商店之前已拒绝此次调用。 |