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

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

In-App кампании

SDK автоматически отображает in-app-кампании, если они приходят в ответ на trackView(...) или triggerEvent(...).

Автопоказ поддерживает MODAL, BOTTOM_SHEET, FULL_SCREEN и SNACK_BAR. Ответ должен содержать непустой variables.elements; INLINE в этот flow не выводится. SDK проверяет, что Activity не уничтожена и не завершается, и учитывает presentation lock.

Если ответ содержит несколько кампаний, SDK перебирает их по убыванию приоритета. С 1.3.0 отсутствующий приоритет считается нулём, а при равном приоритете сохраняется порядок сервера, как в headless-режиме.

Чтобы получить контент для собственного UI вместо автопоказа, используйте headless-режим.

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

Жизненный цикл показа в 1.3.0

  • Модальное окно, bottom sheet, fullscreen и snackbar остаются открытыми при пересоздании Activity из-за смены конфигурации, например поворота экрана. SDK переносит показ в новую Activity без повторных impression, visible impression, видимости товаров и close.
  • Пока кампания показана, SDK не показывает её повторно, в том числе после истечения резервации или подтверждения visible impression. После закрытия кампанию снова можно показать.
  • Close отправляется только после фактического появления контента и ровно один раз, в том числе когда несколько кнопок закрытия используют одно действие onClose. Закрытие до появления close не создаёт.
  • Если окно приложения окончательно удалило уже показанный in-app или нативный диалог, SDK отправляет один close. Восстановленные окна закрытием не считаются.
  • OPEN_STEP заменяет текущий шаг modal, bottom sheet, fullscreen или snackbar следующим шагом независимо от closeOnClick, а не открывает его поверх. Заменённый шаг close не отправляет; итоговое закрытие отправляет один close.
  • Неизвестные действия кнопок и контента игнорируются при выборе tracking-событий, поэтому SDK не отправит событие для действия, которое не поддерживает.

Приложение отвечает за:

  • корректный PageContext;
  • корректный activityContext;
  • обработку действий пользователя через gravityEventCallback. Блокировка новых in-app показов описана в Конфигурации.

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

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

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

SDK предотвращает повторный автоматический показ одной кампании во время её подготовки, показа и ожидания подтверждения visible impression. С 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 один раз. Полный сценарий отзывов о покупках.

GravityInlineView

Используйте GravityInlineView, если экран построен на XML.

<ai.gravityfield.gravity_sdk.ui.GravityInlineView
    android:id="@+id/recommendationsView"
    android:layout_width="match_parent"
    android:layout_height="250dp"
    app:selector="homepage-recs"
    app:color="#FFF1F1F1"
    app:cornerRadius="20dp" />

После инфлейта обязательно передайте PageContext:

val inlineView = findViewById<GravityInlineView>(R.id.recommendationsView)
inlineView.init(
    PageContext(
        type = ContextType.HOMEPAGE,
        data = emptyList(),
        location = "app://homepage",
    )
)

Поддерживаемые XML-атрибуты:

Атрибут Описание
app:selector Селектор кампании.
app:color Цвет фона контейнера.
app:cornerRadius Единый радиус скругления.
app:cornerRadiusTopStart Радиус верхнего левого угла.
app:cornerRadiusTopEnd Радиус верхнего правого угла.
app:cornerRadiusBottomStart Радиус нижнего левого угла.
app:cornerRadiusBottomEnd Радиус нижнего правого угла.
app:loaderLayout Кастомный layout для состояния загрузки.

GravityInlineCompose

Используйте GravityInlineCompose, если экран написан на Jetpack Compose.

GravityInlineCompose(
    modifier = Modifier
        .fillMaxWidth()
        .height(250.dp),
    selector = "homepage-recs",
    pageContext = PageContext(
        type = ContextType.HOMEPAGE,
        data = emptyList(),
        location = "app://homepage",
    ),
    loader = { CircularProgressIndicator() },
)

loader - это composable для состояния загрузки. Если placeholder не нужен, можно передать loader = null.

GravityInlineListView

GravityInlineListView используется для отображения нескольких inline-элементов из одной группы.

<ai.gravityfield.gravity_sdk.ui.GravityInlineListView
    android:id="@+id/inlineListView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:groupSelector="homepage-group" />
val inlineListView = findViewById<GravityInlineListView>(R.id.inlineListView)
inlineListView.init(
    PageContext(
        type = ContextType.HOMEPAGE,
        data = emptyList(),
        location = "app://homepage",
    )
)

Этот компонент полезен для сценариев, где несколько блоков должны быть загружены одной группой кампаний.

Кэш inline-блоков

GravityInlineView и GravityInlineListView используют кэш, чтобы восстановить контент и позицию скролла при пересоздании view. GravityInlineCompose этот кэш не использует. Это важно для экранов с RecyclerView, повторным использованием view и несколькими inline-блоками на одном экране.

Кэш привязан к полному ключу:

  • для GravityInlineView - selector + PageContext;
  • для GravityInlineListView - groupSelector + PageContext.

SDK не очищает inline-кэш автоматически, потому что не знает, закрыт экран окончательно или view будет переиспользована. При закрытии экрана сбросьте кэш самостоятельно:

class InlineDemoActivity : AppCompatActivity() {
    private val pageContext = PageContext(
        type = ContextType.HOMEPAGE,
        data = emptyList(),
        location = "app://homepage",
    )

    override fun onDestroy() {
        if (isFinishing) {
            GravitySDK.instance.resetInlineViewCache(
                selector = "homepage-recs",
                pageContext = pageContext,
            )
        }
        super.onDestroy()
    }
}

Для GravityInlineListView используйте отдельный метод:

GravitySDK.instance.resetInlineListViewCache(
    groupSelector = "homepage-group",
    pageContext = pageContext,
)

Если на экране несколько inline-блоков, сбрасывайте кэш для каждого selector или groupSelector, который использовался на этом экране. Для Fragment/Compose выбирайте момент окончательного выхода из маршрута; уничтожение view при смене конфигурации не всегда означает закрытие экрана. Сброс удаляет данные кэша, но не запускает повторную загрузку уже отображённого view.

Используйте то же значение selector/groupSelector и тот же PageContext, что при загрузке. Отличие любого поля контекста создаёт другой ключ. Блоки с заданными rules кэш не используют.

С 1.3.0, если пользователь сменился во время загрузки, inline-блок повторяет запрос для текущего пользователя и до ответа сохраняет уже показанный контент. Временное отсоединение View не отменяет запрос; удалённый блок повторяет загрузку после повторного присоединения.

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

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

val rules = listOf(
    RtRule(
        type = "filter",
        conditions = listOf(
            RtRuleCondition(
                field = "category",
                arguments = listOf(RtRuleArgument(action = "in", value = listOf("shoes"))),
            ),
        ),
    ),
)

val response = GravitySDK.instance.getContentBySelector(
    selector = "category_recommendations",
    pageContext = PageContext(
        type = ContextType.CATEGORY,
        data = listOf("shoes"),
        location = "app://category/shoes",
    ),
    rules = rules,
)

rules принимают перегрузки getContentBySelector, getContentByCampaignId, getContentByGroupSelector, getContentBySelectorWithDetails и getContentByCampaignIdWithDetails. SDK отправляет их в data[].rules запроса POST /v2/choose в том же формате, что Flutter SDK. null не добавляет ключ rules, как вызов без параметра; пустой список отправляется как [].

У RtRule есть необязательные id и slots; у условия — field и arguments; у аргумента — action и список строк value. Универсального набора операторов SDK не задаёт.

Для inline-блоков:

// Compose
GravityInlineCompose(
    modifier = Modifier.fillMaxWidth(),
    selector = "category_recommendations",
    pageContext = pageContext,
    loader = null,
    rules = rules,
)

// XML: GravityInlineView или GravityInlineListView
inlineView.setRules(rules)
inlineView.init(pageContext)

Смена rules перезагружает блок: прежний запрос и контент отбрасываются, новый контент отправляет свой impression. Контент, загруженный для другого набора правил, не переиспользуется. setRules(null) возвращает запрос без правил.

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

ProductViewBuilder нужен для отображения карточек товара в блоке рекомендаций. Для карточек в дизайне приложения передайте SDK свой шаблон. Если builder отсутствует, товарная строка Android использует демонстрационную GravityProduct, а ячейки сетки с 1.3.0 остаются пустыми; не рассчитывайте на демонстрационную карточку как на карточку вашего приложения.

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

После этого SDK использует переданный шаблон для каждого товара в product/recommendation-блоках: вызывает 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.

Важно:

  • SDK автоматически отслеживает visible impression товара во встроенном блоке;
  • клик по товару в кастомной карточке нужно отправлять вручную через sendProductEngagement(...).

Пример шаблона карточки для Jetpack Compose:

Полный пример: product_view_builder.kt. Он использует Coil 3.1.0; зависимости для загрузки изображений. Замените package на package приложения, реализуйте openProduct и передайте MyComposeProductViewBuilder в initialize.

Кнопки, строки и сетки товаров

С 1.3.0 встроенный рендерер Android отображает эти элементы так же, как iOS и Flutter:

  • Цвет текста активной кнопки — textStyle.color. Если он не задан, используется основной цвет текста: чёрный, в тёмной теме белый. В 1.2.0 Android использовал белый цвет Material. textColor верхнего уровня к кнопкам по-прежнему не применяется.
  • В товарной строке size.height — внешняя высота блока вместе с padding. Фон заполняет этот блок, margin остаётся снаружи. Товары обрезаются по блоку и не перекрывают соседние элементы, поэтому карточка из ProductViewBuilder должна помещаться в эту высоту.
  • Строка или сетка без товаров (products или slots отсутствуют либо slots: []) не отображается: у неё нет высоты, отступов и фона. Контейнер без типа считается строкой.
  • Сетка читает gridSettings (columns, horizontalSpacing, verticalSpacing), а без него — прежний gridColumns. По умолчанию 2 колонки и отступы 8; допустимо от 1 до 12 колонок, некорректный или отрицательный отступ заменяется на 8. Карточки сетки квадратные независимо от size, из стилей контейнера на сетку влияет только padding.
  • Карточки сетки строит ProductViewBuilder приложения; без билдера ячейки сетки остаются пустыми, демонстрационная карточка используется только в строке. Visible impression товара отправляется один раз на слот при видимости минимум половины карточки в пределах обрезанной области в течение секунды.
  • Высокая сетка в sheet ограничивается областью ниже status bar.
  • Бесконечные и нечисловые значения размеров, отступов и радиусов скругления игнорируются, как незаданные.

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

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

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

Для inline/товаров Android ждёт видимость не менее 50% в течение секунды; после выхода и возвращения событие может повториться. Для модальных форматов действует правило первого кадра выше.