Кампании и рекомендации в 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-атрибуты:
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% в течение секунды; после выхода и возвращения событие может повториться. Для модальных форматов действует правило первого кадра выше.