Кампании и рекомендации во Flutter
Готовый UI рендерит SDK; приложение передаёт контекст, размещает inline-блоки и обрабатывает навигацию. Для собственного UI используйте headless, для полного цикла in-app — отдельный гайд. Настройка кампании в кабинете: Кампании в приложении.
In-app
trackView() и triggerEvent() отправляют запрос активации, затем SDK получает контент подходящей кампании. Кандидаты проверяются по убыванию приоритета до первого с доступным корневым контентом. SDK учитывает задержку кампании, актуальность ответа, состояние контекста и presentation lock.
Поддерживаются модальное окно, bottom sheet, полноэкранный формат и SnackBar. Tooltip загружается через якорь. Контент с методом доставки JSON SDK сам не рисует.
Начиная с 0.24.1 SDK не открывает загружаемую кампанию прежнего пользователя после setUser(), resetUser(), restoreUserId() или замены GravitySDK.instance.user. Также пропускается показ, если экран вызова перекрыт другим маршрутом, включая вложенные Navigator. Проверка выполняется после загрузки и задержки кампании; пропуск отмечается в логах. Используйте BuildContext соответствующего экрана. Для собственного headless UI актуальность проверяет приложение.
Чтобы временно не показывать in-app, используйте presentation lock. Это не останавливает запросы контента.
Загрузка inline/tooltip в 0.25.0 не отменяет ожидающий модальный показ с текущего экрана; проверки маршрута и пользователя сохраняются.
Учёт модальных показов
С 0.25.0 модальное окно, bottom sheet и полноэкранный in-app фиксируют visible impression (WRIMP) при первом подтверждённом кадре содержимого в активном приложении, без минимальной длительности. Быстрое явное закрытие после появления окна учитывается; отмена до первого кадра — нет. При временном inactive ещё не показанное окно ждёт resumed; paused, hidden и detached отменяют неподтверждённый показ.
На одно открытие приходится один модальный WRIMP: переходы OPEN_STEP используют исходные URL открытия и не создают новые показы. ContentVisibleImpressionEvent вызывается один раз после сохранения, до первой HTTP-попытки; это не подтверждение доставки.
SDK сохраняет WRIMP на устройстве и повторяет доставку до 7 дней, включая после перезапуска. Локальная защита от повторного открытия кампании для того же пользователя действует до подтверждения, постоянной ошибки или максимум 24 часов от показа. Она не заменяет серверные ограничения частоты. При истечении 24 часов ожидающий WRIMP остаётся в очереди.
Для SnackBar, inline, tooltip, товаров и собственного UI это правило первого кадра не применяется. Очередь, ограничения и управление доставкой.
Inline-блок
GravityInlineWidget(
selector: 'product_recommendations',
height: 280,
pageContext: const PageContext(
type: ContextType.product,
data: ['sku-123'],
location: 'app://product/sku-123',
),
showLoading: true,
loadingWidget: const Center(child: CircularProgressIndicator()),
)
Импорты для виджетов: package:flutter/material.dart и package:gravity_sdk/gravity_sdk.dart.
Без placeholderId выбирается корневой контент без placeholder. С placeholderId — корневой контент с точно совпавшим значением. Контент шагов не выбирается как корневой.
При ошибке, отсутствии подходящего контента или пустых товарах блок скрывается. onLoaded сообщает о загрузке, а не о фактической видимости и не заменяет impression.
Запрос выполняется при создании состояния виджета. При смене selector, товара, контекста или пользователя пересоздавайте блок с новым Key, например ValueKey('user-42:sku-123'); одна лишь замена параметров существующего состояния не гарантирует новую загрузку.
В 0.24.1, если пользователь сменился во время незавершённой загрузки, GravityInlineWidget и GravityInlineListWidget отбрасывают прежний ответ и запрашивают контент заново. Это не обновляет уже загруженный блок: для него по-прежнему нужен новый Key.
Группа inline-блоков
GravityInlineListWidget(
group: 'homepage_group',
height: 250,
pageContext: const PageContext(
type: ContextType.homepage,
data: [],
location: 'app://homepage',
),
showIndicator: true,
)
Виджет получает кампании группы, выбирает корневые контенты и располагает их в горизонтальной карусели по variables.index. Доступны настройки загрузки и цвета индикаторов. Параметров rules, placeholderId и onLoaded у этого виджета нет.
Tooltip
GravityAnchor оборачивает элемент, относительно которого будет показана подсказка. Вызовите переданный onReady, когда якорь готов. Пример: сначала загрузить inline-контент, затем подсказку:
GravityAnchor(
selector: 'profile_tooltip',
pageContext: const PageContext(
type: ContextType.other,
data: [],
location: 'app://profile',
),
builder: (context, onReady) => GravityInlineWidget(
selector: 'profile_banner',
height: 120,
pageContext: const PageContext(
type: ContextType.other,
data: [],
location: 'app://profile',
),
onLoaded: onReady,
),
)
Для обычного собственного виджета сообщите о готовности после его layout через addPostFrameCallback. Не вызывайте onReady как побочный эффект каждого build().
Запросить подсказку вручную можно через fetchAnchorContent(context: ..., selector: ..., pageContext: ...). Якорь с тем же selector должен существовать. Не запускайте одновременно ручную загрузку и автоматическую загрузку того же якоря. Presentation lock на этот путь не действует.
Если во время загрузки пользователь сменился, а якорь остаётся на текущем экране, SDK повторяет запрос для нового пользователя. При уходе с экрана запоздалая подсказка не показывается.
Карточки товаров
Передайте ProductWidgetBuilder при инициализации. Slot.item — карта атрибутов из фида; названия полей и значения зависят от проекта. В примере используются name, price и imageUrl:
class ShopProductBuilder extends ProductWidgetBuilder {
const ShopProductBuilder({required this.onOpenProduct});
final void Function(Slot product) onOpenProduct;
@override
Widget build({
required BuildContext context,
required Slot product,
required CampaignContent content,
required Campaign campaign,
}) {
final item = product.item;
final imageUrl = item['imageUrl'];
return InkWell(
onTap: () {
GravitySDK.instance.sendProductEngagement(
ProductClickEngagement(product, content, campaign),
);
onOpenProduct(product);
},
child: SizedBox(
width: 160,
child: Column(
children: [
if (imageUrl is String)
Image.network(imageUrl, height: 100, fit: BoxFit.cover),
Text(item['name']?.toString() ?? ''),
Text(item['price']?.toString() ?? ''),
],
),
),
);
}
}
onOpenProduct подключите к реальной навигации вашего каталога при создании билдера. Если билдер не передан, SDK использует стандартную карточку.
В контейнере товаров SDK уже отслеживает видимость карточек, включая созданные вашим билдером: ≥50% один раз для слота. Здесь вручную отправляйте клик, а не дополнительный product visible impression. Если вы самостоятельно рисуете весь список товаров вне контейнера SDK, ответственность за оба события лежит на приложении.
Правила рекомендаций
Пример запроса с фильтром; поле и оператор должны поддерживаться вашим проектом:
final rules = [
RtRule(
type: 'filter',
conditions: [
RtRuleCondition(
field: 'category',
arguments: [
RtRuleArgument(action: 'in', value: ['shoes']),
],
),
],
),
];
final response = await GravitySDK.instance.getContentBySelector(
selector: 'category_recommendations',
pageContext: const PageContext(
type: ContextType.category,
data: ['shoes'],
location: 'app://category/shoes',
),
rules: rules,
);
rules поддерживаются в GravityInlineWidget и методах getContentBySelector/CampaignId/Group, а также SelectorWithDetails/CampaignIdWithDetails. У RtRule есть необязательные id и slots; у условия — field и arguments; у аргумента — action и список строк value. Универсального набора операторов SDK не задаёт.
Многошаговые кампании и формы
Встроенный рендерер поддерживает переходы по шагам, выбор вариантов, текстовые поля, ограничения ввода и условную видимость элементов. Корневой контент не имеет step; дополнительные контенты — имеют. Переход open_step обрабатывает SDK. Tooltip в качестве дополнительного шага не поддерживается.
In-app формы настраиваются в кампании; отдельный вызов отправки ответа в приложении не нужен. SDK проверяет обязательные видимые поля и длину ввода, сериализует ответы в строковые свойства CustomEvent и отправляет результат, включая campaignId и experienceId. При временной ошибке результат может остаться в офлайн-очереди.
После отправки переход по URL/диплинку всё равно требует вашего callback. Закрытие формы или переход UI не означает, что результат уже доставлен серверу. Не дублируйте событие отправки формы в callback приложения.
Кто отправляет engagement
Отправка использует tracking-события из ответа сервера. Если нужных events/обработчиков нет, SDK не может построить событие самостоятельно. Подробности — Аналитика собственного UI.