Офлайн-доставка событий
В gravity_sdk 0.25.0 очередь включена по умолчанию. SDK сохраняет запрос события на устройстве перед отправкой и повторяет доставку при временных ошибках. Это помогает сохранить действия при нестабильной сети и перезапуске приложения.
Что сохраняется
Запись соответствует запросу, а не одному событию: список events может включать несколько действий. Для модального WRIMP запись соответствует открытию окна. Повторные попытки сетевых запросов и постоянная очередь — разные механизмы.
Модальные показы WRIMP
С 0.25.0 SDK сохраняет visible impression модальных окон, bottom sheet и полноэкранных in-app до первой отправки. Показ определяется по первому подтверждённому кадру, а не по длительности просмотра. Переходы OPEN_STEP используют один WRIMP на открытие.
- Доставка повторяется до 7 дней от показа, независимо от
OfflineQueueSettings.maxAgeиenabled. - Локальная защита кампании для исходного пользователя сохраняется после закрытия/перезапуска до подтверждения, постоянной ошибки или максимум 24 часов от показа. Истечение защиты не удаляет WRIMP.
- Запись хранит исходные tracking URL и хеши окружения/личности. Смена аккаунта не меняет URL и не переносит защиту на новый профиль. При смене API key несовместимая запись удаляется вместо отправки с другим ключом.
pendingDeliveriesучитывает WRIMP,flushQueue()отправляет его даже при выключенной очереди,clearQueue()удаляет вместе с остальными ожидающими запросами.- При сбое хранилища SDK пробует отправить показ сразу, но доставка после перезапуска для несохранённой записи не обеспечивается. Отсутствующий WRIMP URL отмечается в диагностике.
При переполнении сначала удаляются обычные события, затем старейшие WRIMP. Постоянная ошибка, истечение срока или очистка не означают подтверждённый показ на сервере. Механизм не гарантирует exactly-once и не превращает остальные engagement в постоянную очередь.
Настройки
GravitySDK.instance.setOptions(
offlineQueue: const OfflineQueueSettings(
enabled: true,
maxEntries: 500,
maxAge: Duration(days: 7),
),
);
maxEntries должен быть положительным. Для отключения задайте OfflineQueueSettings(enabled: false). Уже сохранённые бизнес-события остаются на диске, но не отправляются, пока очередь снова не включена. Модальный WRIMP продолжает сохраняться и доставляться. Отключение не равно очистке.
Если хотите изменить настройки до первой отправки старых записей, вызовите setOptions() перед initialize(). Не переключайте ключ/секцию для накопленных запросов одной и той же локальной установки: доставка и очистка очереди должны соответствовать выбранному окружению.
Когда повторяется отправка
SDK пытается доставить очередь:
- при запуске после
initialize(); - при возвращении приложения на передний план;
- после успешного онлайн-запроса, который показывает, что сеть снова доступна;
- по таймеру повторных попыток;
- после включения очереди или ручного
flushQueue().
Очередь не устанавливает отдельный монитор подключения ОС. Если приложение уже следит за сетью, из его callback можно вызвать:
await GravitySDK.instance.flushQueue();
final int pending = await GravitySDK.instance.pendingDeliveries;
flushQueue() дожидается опустошения очереди либо остановки из-за ошибки; его завершение не гарантирует, что всё доставлено. При отключённой очереди он отправляет только модальные WRIMP. pendingDeliveries показывает число сохранённых ожидающих запросов, включая находящиеся в отправке, а не число отдельных событий. С 0.25.0 сюда входят и модальные WRIMP.
Это не системная фоновая служба. Когда приложение не работает, SDK сам отправку не выполняет. Восстановление сети без пробуждения приложения не гарантирует немедленную доставку.
Время и пользователь
Если eventTime задан, SDK сохраняет это время. Иначе фиксирует время вызова события. Повторная доставка не заменяет его временем отправки.
Для записи бизнес-события сохраняется исходная идентификация пользователя, чтобы событие предыдущего аккаунта не приписалось новому. Не сбрасывайте профиль ради повторной отправки и не пересоздавайте уже поставленное в очередь событие при каждом пробуждении приложения.
В 0.24.1 событие привязывается к личности, известной SDK в момент вызова, даже если resetUser() или restoreUserId() выполняется во время подготовки запроса. Пока UID ещё неизвестен при холодном старте, событие может ожидать инициализацию сессии. Сбой запроса, открывающего сессию, не заставляет остальные ожидающие запросы принять ту же ошибку: они могут заново открыть сессию.
Результаты отложенной доставки не запускают запоздалый показ in-app. Очередь доставляет события; получение актуального контента для нового экрана — отдельный запрос.
Очистка
await GravitySDK.instance.clearQueue();
Метод удаляет ожидающие запросы, включая модальные WRIMP, без восстановления; работает и при отключённой очереди. Вызывайте его только когда приложение действительно должно отказаться от доставки этих действий, например на общем устройстве по правилам удаления данных.
resetUser() сам очередь не очищает. Последовательность выхода с очисткой:
await GravitySDK.instance.clearQueue();
await GravitySDK.instance.resetUser();
На время операции остановите создание новых событий. В 0.24.1 успешно завершённый clearQueue() также останавливает события, ещё ожидающие сессию, запись личности или паузу перед повторной отправкой. Уже отправленный в сеть запрос не отменяется и после очистки не добавляется обратно в очередь. События, созданные после очистки, могут отправляться как обычно.
Если хранилище отказало в очистке, clearQueue() выбрасывает исключение — не считайте данные удалёнными. Сбой первого обращения к хранилищу не отключает сохранение до перезапуска: следующая операция пробует обратиться к нему снова. Это не гарантирует сохранение события, для которого запись уже завершилась ошибкой.
Ограничения и повторная доставка
Временные сетевые ошибки и ответы 408/429/5xx допускают повторные попытки. Другие 4xx, ошибки парсинга и отмена не исправляются обычным повтором. Серверные ошибки имеют ограниченное число попыток; постоянная недоставка не хранится бесконечно.
Если сервер обработал событие, но ответ потерялся, возможен дубль. SDK не обещает exactly-once. Для покупки используйте постоянный уникальный uniqueTransactionId заказа. Не генерируйте новый ID при повторной отправке.
Переполнение, истечение срока, очистка и ошибки локального хранилища могут привести к потере записи. Нулевой размер очереди сам по себе не доказывает успешную доставку всех действий. Проверяйте диагностику и события на стороне сервера.
Проверка на устройстве
- Отправьте покупку при недоступной сети с уникальным ID тестового заказа.
- Проверьте, что число ожидающих запросов увеличилось.
- Перезапустите приложение без сети: запись должна остаться, если не истёк срок хранения.
- Восстановите соединение и вызовите
flushQueue(). - Проверьте доставку с исходным временем и пользователем.
- Повторите со сменой аккаунта; отдельно проверьте явную очистку.
- Убедитесь, что старые in-app сообщения после доставки не появляются.
Для формы аналогично проверяется доставка ответа. Её остальные tracking URL в постоянную очередь не попадают; модальный WRIMP сохраняется отдельно.
Проверка модальных показов
- Загрузите in-app и отключите сеть перед его появлением.
- Сразу после первого кадра закройте окно: проверьте один WRIMP в
pendingDeliveries. - Перезапустите приложение без сети с теми же ключом, секцией и пользователем: запись и защита в пределах 24 часов сохраняются.
- Восстановите связь, вызовите
flushQueue()и проверьте исходный tracking URL на сервере. - Повторите с
OfflineQueueSettings(enabled: false): WRIMP также сохраняется и отправляется. - Отдельно проверьте отмену до первого кадра и переходы
OPEN_STEP: отмена не создаёт показ, шаг не добавляет новый WRIMP.