Конфигурация Flutter SDK

Все примеры рассчитаны на gravity_sdk 0.24.0. Импорт:

import 'package:gravity_sdk/gravity_sdk.dart';

Инициализация

До runApp() вызовите WidgetsFlutterBinding.ensureInitialized(), затем дождитесь initialize(). Инициализация настраивает клиент и запускает очередь доставки; серверный UID появляется после первого успешного запроса, а не просто после initialize().

await GravitySDK.instance.initialize(
  apiKey: 'YOUR_API_KEY',
  section: 'YOUR_SECTION_ID',
  logLevel: LogLevel.info,
  gravityEventCallback: (event) {
    // Диагностика; обработку навигации добавьте по быстрому старту.
    print(event.runtimeType);
  },
);

Перед вызовами трекинга и получения контента SDK должен быть инициализирован. Исключения для работы до инициализации: API серверного UID и presentation lock, перечисленные в справочнике.

Глобальные настройки

GravitySDK.instance.setOptions(
  options: const Options(
    isReturnUserInfo: true,
  ),
  contentSettings: const ContentSettings(
    skusOnly: false,
    fields: ['name', 'price', 'imageUrl'],
  ),
  isFetchContentOnTrack: true,
  offlineQueue: const OfflineQueueSettings(
    enabled: true,
    maxEntries: 500,
    maxAge: Duration(days: 7),
  ),
  staleContentTimeout: const Duration(seconds: 10),
);

setOptions() заменяет только явно переданные настройки. Объекты Options и ContentSettings заменяются целиком, а не объединяются с предыдущими. Пропущенные параметры сохраняют прежние значения. Через proxyUrl можно задать базовый URL прокси, обслуживающего SDK endpoints; null не сбрасывает ранее заданный URL.

Options

Изменения серверных опций аналитики согласуйте с моделью учёта проекта. Они не заменяют обработку фактической видимости собственного UI, описанную в headless-гайде.

ContentSettings.skusOnly по умолчанию false; fields — список атрибутов товара из фида либо null. Доступные имена полей определяет ваш фид.

isFetchContentOnTrack

В версии 0.24.0 этот флаг проверяют только trackViewNoShow() и triggerEventNoShow(). При false они отправляют просмотр или событие и возвращают null без последующего получения контента.

Флаг не отключает автопоказ обычных trackView() и triggerEvent(). Для временной блокировки такого показа используйте presentation lock.

staleContentTimeout

По умолчанию — 10 секунд. Ответ /visit или /event, пришедший позже порога, не запускает загрузку контента. В обычном автопоказе SDK также проверяет актуальность перед отображением после загрузки и задержки кампании; её настроенная задержка учитывается отдельно.

Этот параметр ограничивает бюджет повторных попыток /visit, /event и /choose, но не является жёстким сетевым таймаутом и не гарантирует отмену запроса при смене экрана. В собственной отрисовке проверяйте mounted и актуальность запроса самостоятельно.

Логирование

Уровни: none, error, warn, info, debug. Для диагностики используйте LogLevel.debug при инициализации. Он включает тела запросов и ответов; для обычной работы выбирайте нужную приложению детализацию.

Callback и действия

Рабочая навигация приведена в быстром старте. Для собственных бизнес-событий используйте CustomEvent; повторно отправлять tracking уже обработанной SDK кнопки не нужно.

gravityContentCallback задаётся в initialize(). Его вызывают успешные getContentBySelectorWithDetails() и getContentByCampaignIdWithDetails(), в том числе при получении контента через NoShow. Выберите один путь обновления UI — callback или возвращённое значение — чтобы не обрабатывать один ответ дважды.

Push-уведомления

GravitySDK.instance.setNotificationPermissionStatus(
  NotificationPermissionStatus.granted,
);

Возможные значения: granted, denied, unknown; по умолчанию unknown. SDK передаёт статус серверу, но не запрашивает разрешение и не заменяет push-провайдер приложения. Обновляйте статус после проверки или изменения разрешения ОС.

Блокировка автопоказа

Например, на время оплаты:

GravitySDK.instance.lockPresentation();
try {
  await showDialog<void>(
    context: context,
    builder: (context) => AlertDialog(
      title: const Text('Оплата'),
      actions: [
        TextButton(
          onPressed: () => Navigator.of(context).pop(),
          child: const Text('Закрыть'),
        ),
      ],
    ),
  );
} finally {
  GravitySDK.instance.unlockPresentation();
}

Этот фрагмент используется внутри Flutter-экрана с импортом package:flutter/material.dart.

Блокировка действует на автопоказ из trackView() и triggerEvent(). Загрузка контента и contentLoaded продолжаются: запрос выбора может расходовать серверные лимиты частоты даже без показа. Уже открытая кампания не закрывается.

Блокировка не распространяется на GravityAnchor/fetchAnchorContent(), переходы между шагами открытой кампании и ручную отрисовку. Пропущенный контент не появляется после unlockPresentation(). Состояние хранится в памяти и сбрасывается при перезапуске; блокировка — один boolean, без счётчика вложенных операций.

isPresentationLocked возвращает состояние, setPresentationLockListener() устанавливает один listener. Он вызывается при каждом вызове lock/unlock, включая повторные; null снимает подписку.