Управление сообщениями стора в Unity SDK
App Store и Google Play иногда показывают пользователям сообщения о подписке:
- App Store: Запрос согласия на повышение цены, уведомление о проблеме с оплатой или win-back offer. По умолчанию StoreKit показывает эти сообщения самостоятельно, пока открыто ваше приложение.
- Google Play: Уведомление о том, что платёж по подписке не прошёл и нужно обновить способ оплаты. Начиная с SDK 4.3.0, Adapty SDK запрашивает эти сообщения по умолчанию каждый раз, когда
Activityвашего приложения запускается после активации — в том числе при возврате приложения на передний план, а также при открытии или закрытии флоу или онбординга.
В любом случае сообщение может появиться поверх флоу, онбординга или чекаута. Чтобы самостоятельно выбирать момент, переключите SDK в режим ручной обработки сообщений и вызывайте Adapty.ShowStoreMessages тогда, когда сообщение не прервёт пользователя.
В ручном режиме сторы не показывают сообщения самостоятельно. Если ваше приложение никогда не вызывает Adapty.ShowStoreMessages, пользователи не увидят ни запрос на согласие с изменением цены, ни уведомление о проблеме с оплатой, ни уведомление об отклонённом платеже.
Перед началом работы
Вам потребуется:
- Adapty Unity SDK 4.3.0 или выше: более ранние версии не поддерживают 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 в вашем приложении, вызовите SetStoreMessagesHandling с параметром AdaptyStoreMessagesHandling.Manual при активации SDK:
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 | Подходящий win-back offer. Доступно на iOS 18 и выше. |
Новые типы сообщений StoreKit приходят с RawValue вида storekit_<number>. Чтобы проверить тип, сравните его с == с одним из значений выше, а любое другое значение обрабатывайте как нераспознанный тип.
Показ сообщений
Когда ваше приложение достигает момента, в котором сообщение стора не прервёт пользователя — например, после того как пользователь закрыл флоу или завершил онбординг — вызовите Adapty.ShowStoreMessages:
Adapty.ShowStoreMessages((error) => {
if (error != null) {
// handle the error
}
});
- iOS: SDK показывает ожидающие сообщения одно за другим. После того как StoreKit отображает сообщение, SDK удаляет его из списка ожидающих. Если StoreKit не может показать сообщение, SDK сохраняет его до следующего вызова и продолжает обработку остальных сообщений.
- Android: SDK запрашивает сообщения Google Play для текущего
Activity. Google Play самостоятельно решает, применимо ли сообщение к данному пользователю, поэтому запрос не всегда приводит к показу сообщения. Если пользователь исправит способ оплаты через сообщение, SDK синхронизирует покупки пользователя с Adapty, и ваш слушатель профиля получит обновлённый уровень доступа.
Показ сообщений при запуске на Android
В режиме Auto по умолчанию Activity, запущенная до активации, не инициирует запрос, поэтому сообщения Google Play не отображаются при запуске. Чтобы показывать их при запуске, вызовите Adapty.ShowStoreMessages один раз после завершения Adapty.Activate, только на Android:
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 отклоняет вызов до его передачи в стор. |