Справочник Flutter SDK 0.24.0

Основной импорт — package:gravity_sdk/gravity_sdk.dart. Клиент — GravitySDK.instance. Полная документация типов: API Reference опубликованного пакета.

Инициализация и настройки

Future<void> initialize({
  required String apiKey,
  required String section,
  ProductWidgetBuilder? productWidgetBuilder,
  GravityEventCallback? gravityEventCallback,
  GravityContentCallback? gravityContentCallback,
  LogLevel logLevel = LogLevel.info,
});

void setOptions({
  Options? options,
  ContentSettings? contentSettings,
  String? proxyUrl,
  bool? isFetchContentOnTrack,
  OfflineQueueSettings? offlineQueue,
  Duration? staleContentTimeout,
});

Это сигнатуры для справки, а не исполняемый фрагмент приложения. Значения по умолчанию и поведение параметров — Конфигурация.

Идентификация и разрешения

Сигнатура	Поведение
`void setUser(String userId, String sessionId)`	Задать внешний ID и управляемую приложением сессию
`Future<void> resetUser()`	Сбросить идентификацию и сессию; очередь не очищать
`Future<String?> getUserId()`	Прочитать серверный UID; может ждать инициализацию сессии
`void setUserIdListener(void Function(String? uid)? listener)`	Один listener изменений UID, `null` снимает
`Future<void> restoreUserId(String uid)`	Восстановить серверный UID; сбросить сессию и ручного пользователя
`void setNotificationPermissionStatus(NotificationPermissionStatus status)`	Задать `granted` / `denied` / `unknown`

getUserId(), setUserIdListener() и restoreUserId() доступны до initialize(). Примеры и сценарии выхода: Идентификация.

Просмотры и события

Future<void> trackView({
  required BuildContext context,
  required PageContext pageContext,
});

Future<void> triggerEvent({
  required BuildContext context,
  required List<TriggerEvent> events,
  required PageContext pageContext,
});

Future<GravityDataResponse<ContentResponse>?> trackViewNoShow({
  required PageContext pageContext,
});

Future<GravityDataResponse<ContentResponse>?> triggerEventNoShow({
  required List<TriggerEvent> events,
  required PageContext pageContext,
});

Обычные методы могут показывать in-app; NoShow возвращает данные без UI. Флаг isFetchContentOnTrack применяется только к NoShow.

Получение контента

Все методы ниже требуют PageContext и поддерживают необязательные List<RtRule>? rules:

Метод и обязательный параметр	Возвращаемый тип
`getContentBySelector({required String selector, required PageContext pageContext, List<RtRule>? rules})`	`Future<ContentResponse>`
`getContentByCampaignId({required String campaignId, required PageContext pageContext, List<RtRule>? rules})`	`Future<ContentResponse>`
`getContentByGroup({required String group, required PageContext pageContext, List<RtRule>? rules})`	`Future<ContentResponse>`
`getContentBySelectorWithDetails({required String selector, required PageContext pageContext, List<RtRule>? rules})`	`Future<GravityDataResponse<ContentResponse>>`
`getContentByCampaignIdWithDetails({required String campaignId, required PageContext pageContext, List<RtRule>? rules})`	`Future<GravityDataResponse<ContentResponse>>`

Методы WithDetails также вызывают глобальный gravityContentCallback. Ошибки запроса пробрасываются в вызывающий код.

В обычных selector-запросах SDK использует батчинг/дедупликацию совместимых конкурентных запросов. WithDetails обращается напрямую за полным JSON; не считайте его поведение по числу запросов идентичным обычному selector-методу.

Ответы и переменные

Тип/поле	Содержание
`GravityDataResponse<T>`	`T data` и `Map<String, dynamic> json`
`ContentResponse`	`User user` и `List<Campaign> data`
`Campaign`	`String? selector` и `List<CampaignVariation> payload`
`CampaignVariation`	`campaignId`, `experienceId`, `variationId`, `decisionId` и `List<CampaignContent> contents`
`CampaignContent`	`contentId`, `deliveryMethod`, `variables`, `products`, `events`, `placeholderId`, `custom`, `step`
`content.rawVariables`	`Map<String, dynamic>` с полным исходным объектом variables
`content.variables[key]`	`Object?`; без преобразования типа
`content.variables.valueOf<T>(key)`	`T?`; `null` при отсутствии или несовпадении типа
`Slot`	Карта `item`, `fallback`, `strId`, nullable `slotId` и product `events`

step == null определяет корневой контент. Для engagement передавайте исходные объекты ответа, не DTO, собранные из отдельных идентификаторов.

События TriggerEvent

У всех событий доступны Map<String, String>? customProps и DateTime? eventTime.

Событие	Обязательные поля	Необязательные поля
`AddToCartEvent`	`double value`, `String productId`, `int quantity`	`currency`, `cart`
`RemoveFromCartEvent`	`value`, `productId`, `quantity`	`currency`, `cart`
`PurchaseEvent`	`String uniqueTransactionId`, `double value`, `List<CartItem> cart`	`currency`
`SyncCartEvent`	`double value`	`currency`, `cart`
`AddToWishlistEvent`	`double value`, `String productId`	—
`LoginEvent` / `SignUpEvent`	В конструкторе нет; сервер требует идентификатор	`hashedEmail`, `cuid`, `cuidType`
`CustomEvent`	`String type`, `String name`	`cuid`, `cuidType`, `cart`

CartItem требует String productId, int quantity и double itemPrice. Примеры: Контекст и события.

Engagement и tracking URL

void sendContentEngagement(ContentEngagement engagement);
void sendProductEngagement(ProductEngagement engagement);
Future<void> triggerTrackingUrl(String url);

Content engagement: ContentImpressionEngagement, ContentVisibleImpressionEngagement, ContentClickEngagement, ContentCloseEngagement — каждый принимает (CampaignContent content, Campaign campaign).

Product engagement: ProductClickEngagement, ProductVisibleImpressionEngagement — принимают (Slot slot, CampaignContent content, Campaign campaign).

triggerTrackingUrl() отправляет предоставленный URL, но не рисует UI и не сохраняет его в постоянной очереди. В SDK-интеграции предпочитайте типизированный engagement. Кто отправляет аналитику.

Callback

typedef GravityEventCallback = void Function(TrackingEvent event);
typedef GravityContentCallback =
    void Function(GravityDataResponse<ContentResponse> response);

TrackingEvent включает ContentLoadEvent, ContentImpressionEvent, ContentVisibleImpressionEvent, ContentCloseEvent, CopyEvent, CancelEvent, FollowUrlEvent, FollowDeeplinkEvent, RequestPushEvent и ProductImpressionEvent. События содержат campaign и соответствующие объекты контента/товара.

У FollowUrlEvent есть url и FollowUrlType type (browser или webview; по умолчанию browser); у FollowDeeplinkEvent — deeplink; у CopyEvent — copiedValue. Для ручного ContentClickEngagement отдельного click-callback нет.

Виджеты и показ

API	Основные параметры
`GravityInlineWidget`	Обязательные `selector`, `pageContext`; `placeholderId`, `width`, `height`, `showLoading = true`, `loadingWidget`, `backgroundColor`, `onLoaded`, `rules`
`GravityInlineListWidget`	Обязательные `group`, `pageContext`; `height`, `showLoading = true`, `loadingWidget`, `showIndicator = true`, цвета индикаторов
`GravityAnchor`	Обязательные `selector` и `builder`; необязательный `pageContext`
`ProductWidgetBuilder.build()`	Обязательные именованные `context`, `Slot product`, `CampaignContent content`, `Campaign campaign`; возвращает `Widget`
`fetchAnchorContent({required BuildContext context, required String selector, PageContext? pageContext})`	`Future<void>`; требует существующий якорь

GravityAnchorBuilder — Widget Function(BuildContext context, VoidCallback onReady). При отсутствии контекста у fetchAnchorContent используется OTHER с пустыми data/location. Для корректного таргетинга задавайте свой контекст.

openStep() используется встроенным рендерером для перехода к дополнительному контенту кампании. Для типовой интеграции форм и многошаговых кампаний вызывать его из приложения не требуется.

Presentation lock

void lockPresentation(), void unlockPresentation(), bool get isPresentationLocked и void setPresentationLockListener(void Function(bool locked)? listener).

Доступны до инициализации. Не блокируют inline, tooltip и собственный UI. Поведение и серверные лимиты.

Очередь

Future<void> flushQueue(), Future<void> clearQueue() и Future<int> get pendingDeliveries требуют инициализацию.

OfflineQueueSettings: enabled = true, maxEntries = 500, maxAge = Duration(days: 7). Поведение при ошибках.