Кампании и рекомендации в iOS

Сначала подключите SDK и опубликуйте кампанию в приложении. Навигация по URL/deeplink реализуется в приложении через callback.

In-App кампании

SDK автоматически показывает кампании с deliveryMethod:

  • fullScreen
  • modal
  • bottomSheet
  • snackBar

Что требуется для автопоказа:

  • подходящая активная кампания на backend;
  • корректный PageContext;
  • доступный UIViewController в момент показа после загрузки и задержки кампании;
  • заполненный variables.elements в ответе и снятая presentation lock. Блокировка новых in-app показов описана в Конфигурации.

Кампании из ответа SDK перебирает по убыванию priority и перед показом выдерживает delayTime кампании. С 1.3.0 дробные числа и числовые строки в priority и delayTime усекаются до целого, некорректные значения игнорируются и больше не ломают весь ответ на просмотр или событие. Отрицательная задержка означает показ без ожидания, очень большая ограничивается максимально поддерживаемой. Если во время задержки сменились экран или пользователь либо включена presentation lock, ожидающий показ отменяется.

С 1.3.1 SDK пропускает автоматический показ модального окна, bottom sheet и полноэкранного in-app, если поверх текущего экрана уже открыт другой контроллер. Snackbar также пропускается, если открыт другой контроллер или уже показан любой in-app SDK. Открытый Snackbar не блокирует остальные три формата.

Учёт модальных показов

С 1.2.0 modal, bottomSheet и fullScreen фиксируют visible impression при первом подтверждённом кадре содержимого в активном приложении, без минимальной длительности. Быстрое закрытие после появления и переходы OPEN_STEP дают один показ на открытие. Отмена до появления не считается показом. WRIMP сохраняется до отправки и повторяется при временных ошибках до 7 дней, в том числе после перезапуска. Сроки защиты и доставки.

В 1.3.0 уточнён учёт показов и закрытий:

  • impression модального окна, bottom sheet и полноэкранного in-app отправляется один раз на показ, даже если приложение перекрыло окно своим контроллером, а затем убрало перекрытие. Пока окно перекрыто, видимость не учитывается;
  • close отправляется только после подтверждённого появления содержимого и ровно один раз — в том числе когда кнопка закрытия также запускает действие onClose. Отмена до первого кадра close не создаёт;
  • если приложение убрало показанный in-app средствами UIKit, минуя dismissInApp, SDK отправляет close один раз;
  • действие open_step всегда заменяет текущий шаг модального окна, bottom sheet или полноэкранного in-app, независимо от closeOnClick. Заменённый шаг close не отправляет, показ сохраняет один visible impression, close отправляется при закрытии последнего шага;
  • SnackBar отправляет impression при первом видимом кадре, а visible impression — когда не менее 50% содержимого видно в течение одной секунды в активном приложении. Visible impression сохраняется до отправки так же, как WRIMP модальных форматов. SnackBar, закрытый до первого видимого кадра, не отправляет ни impression, ни close.

Подготовка и защита от повторного показа

SDK предотвращает повторный автоматический показ одной кампании во время её подготовки, показа и ожидания подтверждения visible impression. С 1.3.0 кампания, чей in-app ещё открыт, не открывается повторно, даже если эти сроки уже истекли. С 1.2.0 защита модального показа сохраняется после закрытия и перезапуска до подтверждения, постоянной ошибки или максимум 24 часов от показа. Запоздалые ответы от уже неактуальных запросов не должны создавать второй in-app. Эта защита дополняет серверные ограничения частоты, но не заменяет их и не запрещает повторный показ кампании навсегда.

Перед UI можно подключить inAppPreparation: дождаться API приложения, отфильтровать исходные товары через filteringProducts или пропустить контент. SDK повторно проверяет экран, пользователя и presentation lock после ожидания. Если контент пропущен, impression и visible impression не отправляются; content load tracking по-прежнему означает загрузку.

Из обычного ProductViewBuilder можно вызвать dismissInApp с contentId, чтобы сначала закрыть in-app, а затем открыть экран приложения. При повторном вызове во время закрытия completion получает false; close отправляет SDK один раз. Полный сценарий отзывов о покупках.

Inline-компоненты

iOS SDK предоставляет компоненты для загрузки по selector и группе:

  • GravityInlineSwiftUIView — для SwiftUI-экранов;
  • GravityInlineView — для UIKit-экранов, включая ячейки UITableView;
  • GravityInlineListView — горизонтальный список блоков из группы кампаний для UIKit.

С 1.3.0 все три компонента принимают необязательные правила рекомендаций rules.

SwiftUI:

GravityInlineSwiftUIView(
    selector: "homepage-recommendations",
    pageContext: PageContext(
        type: .homepage,
        data: [],
        location: "app://homepage"
    )
)

UIKit:

let inlineView = GravityInlineView(selector: "homepage-recommendations")

inlineView.initialize(
    pageContext: PageContext(
        type: .homepage,
        data: [],
        location: "app://homepage"
    )
)

Что важно учесть:

  • selector должен совпадать с selector кампании на backend;
  • PageContext должен соответствовать таргетингу кампании;
  • если backend не вернул подходящий контент, компонент останется пустым;
  • для UIKit-компонента нужно корректно настроить constraints и вызвать initialize(pageContext:);
  • высота inline-блока может обновляться по frameUI.container.style.size.height, если это значение пришло с backend.

Оба одиночных компонента поддерживают loader:

GravityInlineSwiftUIView(selector: "homepage-recommendations", pageContext: pageContext) {
    ProgressView()
}

inlineView.initialize(pageContext: pageContext) {
    ProgressView()
}

Для группы кампаний:

let listView = GravityInlineListView(groupSelector: "homepage-group")
listView.initialize(pageContext: pageContext) {
    ProgressView()
}

У UIKit list-компонента высота берётся из максимального frameUI.container.style.size.height среди загруженных блоков. Если ни у одного блока высота не задана, SDK устанавливает 0; задайте размер в кампании.

После успешной загрузки эти компоненты сохраняют полученный контент. С 1.3.0 новый PageContext на том же экземпляре повторяет загрузку, только если прежняя ещё не завершилась или вернула пустой результат; уже показанный контент остаётся. Для смены товара/контекста с заменой показанного блока создайте новый UIKit view или измените identity SwiftUI view через .id(...). Изменение rules очищает блок и загружает контент заново. Публичных методов сброса inline-кэша, как в Android SDK, здесь нет.

Товарная сетка

С 1.3.0 встроенный рендерер отображает товарный контейнер в layout row и grid. Сетку настраивает style.gridSettings (GridSettings):

Поле Значение
columns Число колонок от 1 до 12; дробное значение усекается
horizontalSpacing, verticalSpacing Отступы между карточками; по умолчанию 8

Если gridSettings.columns отсутствует или некорректен, SDK использует прежнее поле gridColumns (число или строка с px, от 1 до 12), иначе — 2 колонки. Карточки в сетке квадратные; style.padding задаёт внутренний отступ контейнера. Каждую карточку рисует ProductViewBuilder. Visible impression товара отправляется один раз на слот, когда видно не менее половины карточки в области прокрутки.

Ряд или сетка без товаров (нет объекта products или список слотов пуст) ничего не рисуют, включая margin, padding и фон контейнера.

Карточки товаров

ProductViewBuilder нужен для отображения карточек товара в product-based или recommendation-блоках. Это обязательная часть интеграции товарных рекомендаций: приложение должно передать SDK шаблон карточки, иначе SDK не знает, какой UI использовать для товара в вашем приложении.

SDK получает блок рекомендаций, управляет контейнером, списком слотов и tracking-контекстом, но сам шаблон товарной карточки задает приложение. Разработчик реализует ProductViewBuilder или LegacyProductViewBuilder и передает его в GravitySDK.initialize(...) через параметр productViewBuilder.

После этого SDK использует переданный шаблон для каждого товара в блоке: вызывает builder для каждого slot и передает в него slot, content и campaign. Поэтому карточка отображается как native UI приложения, а не как готовая карточка, нарисованная SDK.

slot содержит данные одного рекомендованного товара:

  • slot.item - словарь с полями товара из фида или из запрошенных fields: например sku, name, price, old_price, image_url, url, brand, currency и другие кастомные поля;
  • slot.strId и slot.slotId - идентификаторы позиции товара в выдаче;
  • slot.fallback - признак, что товар пришел из fallback-логики;
  • slot.events - tracking-данные товара, которые SDK использует при отправке engagement.

Названия ключей в slot.item должны совпадать с вашим фидом и настройкой fields. Например, если в ответе приходит imageUrl, читайте imageUrl; если используется поле фида image_url, читайте image_url.

В товарной сетке карточка получает квадратную ячейку: учитывайте это в вёрстке шаблона.

Сигнатуры протоколов — в справочнике API.

Пример шаблона карточки:

Полный пример: product_view_builder.swift. Реализуйте openProduct и передайте MyProductBuilder в initialize. Изображения через SwiftUI.AsyncImage доступны с iOS 15; для iOS 14 подключите свой загрузчик.

Что важно учесть:

  • ProductViewBuilder получает slot, content и campaign, поэтому карточка товара может учитывать контекст кампании и content block;
  • если в приложении уже есть UIKit-карточка товара, используйте LegacyProductViewBuilder и верните UIView из createView(...);
  • SDK автоматически отслеживает visible impression товара во встроенном блоке, а tap по кастомной карточке приложение отправляет вручную через sendProductEngagement(...) перед навигацией;
  • productFilter применяется к Products.slots при декодировании ответа SDK. Используйте его только для простого клиентского исключения слотов, когда это действительно нужно в приложении.

Правила рекомендаций

С 1.3.0 запрос контента может передавать правила рекомендаций rules — например, фильтры каталога, выбранные пользователем. SDK отправляет их в поле rules элемента запроса /choose. Поле и оператор должны поддерживаться вашим проектом:

let rules = [
    RtRule(
        type: "filter",
        conditions: [
            RtRuleCondition(
                field: "price",
                arguments: [
                    RtRuleArgument(action: "gte", value: ["1000"]),
                    RtRuleArgument(action: "lte", value: ["5000"])
                ]
            )
        ]
    )
]

let pageContext = PageContext(type: .category, data: ["Обувь"], location: "app://category/shoes")
let response = await GravitySDK.instance.getContentBySelector(
    selector: "category_recommendations",
    pageContext: pageContext,
    rules: rules
)

// Inline: SwiftUI — параметр rules, UIKit — init(selector:rules:) или свойство rules.
GravityInlineSwiftUIView(selector: "category_recommendations", pageContext: pageContext, rules: rules)
inlineView.rules = rules // Блок очищается и загружается заново.

rules поддерживают getContentBySelector, getContentByCampaignId, getContentByGroupSelector, getContentBySelectorWithDetails, getContentByCampaignIdWithDetails и все inline-компоненты. У RtRule есть необязательные id и slots; у условия — field и arguments; у аргумента — action и список строк value. Универсального набора операторов SDK не задаёт. Когда пользователь меняет фильтры, передайте новые rules: inline-блок сам перезагрузит контент. Сигнатуры.

Кто отправляет engagement

Успешная загрузка автоматически отправляет content load tracking. Встроенные UI-компоненты отправляют показы контента, видимость товаров и tracking для поддерживаемых действий. Карточка из ProductViewBuilder уже обёрнута detector SDK: вручную отправляйте её клик перед навигацией, не дублируйте visible impression.

Ручные вызовы engagement не генерируют tracking callback. Для собственного UI используйте отдельные правила аналитики.

Для inline/товаров iOS учитывает не менее 50% площади в окне сразу, один раз на экземпляр detector; в товарной сетке — один раз на слот. Для модальных форматов действует правило первого кадра выше, для SnackBar — 50% в течение одной секунды.