Управление сообщениями стора в Capacitor SDK

App Store и Google Play иногда показывают пользователям сообщения о состоянии их подписки:

  • App Store: Запрос на согласие с повышением цены, уведомление о проблемах с оплатой или win-back offer. По умолчанию StoreKit показывает эти сообщения самостоятельно, пока приложение открыто.
  • Google Play: Уведомление о том, что платёж по подписке был отклонён и нужно обновить способ оплаты. Начиная с SDK 4.3.0, Adapty SDK запрашивает эти сообщения по умолчанию каждый раз, когда Activity вашего приложения запускается после activate, в том числе при возврате приложения на передний план.

В любом случае сообщение может появиться поверх флоу, онбординга или чекаута. Чтобы контролировать момент показа, переключите SDK в режим ручной обработки сообщений и вызывайте showStoreMessages тогда, когда сообщение не прервёт пользователя.

Warning

В ручном режиме сторы не показывают сообщения самостоятельно. Если приложение никогда не вызывает showStoreMessages, пользователи никогда не увидят запрос на согласие с повышением цены, уведомление о проблемах с оплатой или отказе платежа.

Перед началом

Вам потребуется:

  • Adapty Capacitor SDK 4.3.0 или выше: более ранние версии не поддерживают API сообщений стора.
  • iOS 16 или выше для сообщений App Store: StoreKit не доставляет сообщения приложениям на более ранних версиях. На iOS 15 getPendingStoreMessageTypes и showStoreMessages возвращают ошибку decodingFailed, поэтому если ваше приложение поддерживает iOS 15, обрабатывайте эту ошибку — как показано в примерах ниже.

Включить ручную обработку

Чтобы сообщения стора отображались только когда ваше приложение вызывает showStoreMessages, установите storeMessagesHandling в значение 'manual' при активации SDK:


await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    storeMessagesHandling: 'manual', // 'auto' is the default
  },
});

На iOS SDK добавляет каждое сообщение App Store в список ожидающих для текущей сессии приложения. На Android SDK прекращает самостоятельно запрашивать сообщения Google Play. При значении 'auto' по умолчанию SDK не перехватывает сообщения App Store, поэтому на iOS getPendingStoreMessageTypes и showStoreMessages не имеют что возвращать или показывать.

Получение типов ожидающих сообщений

На iOS, чтобы узнать, есть ли ожидающие сообщения App Store, вызовите getPendingStoreMessageTypes. Метод возвращает типы ожидающих сообщений, не отображая и не удаляя их:

try {
  const pendingTypes = await adapty.getPendingStoreMessageTypes();

  if (pendingTypes === null) {
    // Android: Google Play decides whether a message applies when you show it
    await adapty.showStoreMessages();
  } else if (pendingTypes.includes('billing_issue')) {
    // For example, skip the upsell and show the billing message first
  }
} catch (error) {
  // On iOS 15, the call fails with decodingFailed (2006)
}

На Android метод возвращает null, не обращаясь к нативному SDK: Google Play не сообщает об ожидающих сообщениях и решает, применимо ли сообщение, только когда приложение его запрашивает. Пустой массив означает, что на iOS ожидающих сообщений нет. До завершения activate массив всегда пуст.

Каждое сообщение App Store имеет один из следующих типов:

ТипСообщение
genericОбщее сообщение App Store.
price_increase_consentЗапрос на согласие с повышением цены подписки.
billing_issueУведомление о проблеме с оплатой подписки. Доступно на iOS 16.4 и более поздних версиях.
win_back_offerДоступный win-back offer. Доступно на iOS 18 и более поздних версиях.

Новые типы сообщений StoreKit приходят со значением storekit_<number>. Любое значение, не указанное в этой таблице, следует обрабатывать как неизвестный SDK тип.

Показ сообщений

Когда приложение достигает точки, в которой сообщение стора не прервёт пользователя — например, после того как пользователь закрыл флоу или завершил онбординг, — вызовите showStoreMessages:

try {
  await adapty.showStoreMessages();
} catch (error) {
  // handle the error
}
  • iOS: SDK показывает ожидающие сообщения одно за другим. После того как StoreKit показывает сообщение, SDK удаляет его из списка ожидающих. Если StoreKit не может показать сообщение, SDK оставляет его для следующего вызова и продолжает обработку остальных сообщений.
  • Android: SDK запрашивает сообщения Google Play для текущего Activity. Google Play самостоятельно решает, применимо ли сообщение к пользователю, поэтому запрос не всегда приводит к показу сообщения. Вызов возвращается немедленно, не дожидаясь ответа Google Play, и не сообщает об ошибках Google Play. Если пользователь исправляет способ оплаты через сообщение, SDK синхронизирует покупки пользователя с Adapty, и ваш слушатель профиля получает обновлённый уровень доступа.

Отображение сообщений при запуске на Android

В режиме 'auto' по умолчанию Activity, в которой запускается ваше приложение, стартует раньше выполнения activate, поэтому запрос не отправляется и сообщения Google Play не отображаются при запуске. Чтобы показывать их при запуске, вызовите showStoreMessages один раз после activate, только на Android:


await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY' });

if (Capacitor.getPlatform() === 'android') {
  await adapty.showStoreMessages();
}

Не вызывайте это на iOS: в режиме 'auto' ему нечего показывать, а на iOS 15 вызов завершается ошибкой.

Показывать только некоторые типы сообщений

Чтобы показывать только часть ожидающих сообщений App Store, передайте нужные типы в ios.filter. Остальные сообщения останутся в очереди:

await adapty.showStoreMessages({
  ios: { filter: ['billing_issue', 'price_increase_consent'] },
});

Без filter SDK показывает все ожидающие сообщения, включая типы, которые он не распознаёт. Пустой массив не показывает ни одного. Android игнорирует filter и запрашивает все сообщения Google Play.

Ошибки

На iOS showStoreMessages выбрасывает AdaptyError с одним из следующих кодов:

КодНазваниеПричина
2006decodingFailedУстройство работает на iOS 15 или более ранней версии. Вызывайте метод только на iOS 16 и выше.
3201operationInProgressДругой вызов showStoreMessages ещё отображает сообщения, а этот вызов также содержит сообщения для показа. Дождитесь завершения первого вызова, затем повторите попытку.
3202resolverFailureSDK не нашёл активного оконного сцены на переднем плане для отображения сообщений. Сообщения, показанные до ошибки, удаляются из очереди. Вызовите метод снова, когда приложение будет на переднем плане, чтобы показать оставшиеся.