Свой UI и Custom JSON в Android

Используйте этот путь, когда приложение само рисует кампанию или рекомендации. SDK получает контент и отправляет content load tracking; видимость, клики и навигацию определяет приложение. Сначала выполните инициализацию.

getContentBySelector(...)

Для getContentBySelector(...) требуется корректно заполненный PageContext.

Пример:

lifecycleScope.launch {
    val response = GravitySDK.instance.getContentBySelector(
        selector = "homepage-banner-json",
        pageContext = PageContext(
            type = ContextType.HOMEPAGE,
            data = emptyList(),
            location = "app://home",
        )
    )

    if (response != null && response.data.isNotEmpty()) {
        val campaign = response.data.first()
        val variation = campaign.payload.firstOrNull()
        val content = variation?.contents?.firstOrNull()
        // Отрисуйте content в своем UI
    }
}

Метод возвращает null при сетевой ошибке, неуспешном HTTP-статусе или ошибке разбора ответа; успешный ответ без подходящей кампании содержит пустой data. С 1.3.0 null возвращается и тогда, когда пользователь сменился (setUser, resetUser, restoreUserId) до получения ответа. Успешная загрузка автоматически отправляет content load tracking для всех contents, но не показывает UI.

Для выбора по ID и группе доступны getContentByCampaignId(...) и getContentByGroupSelector(...): сигнатуры.

Все три метода используют общие Options/ContentSettings и отправляют content load tracking. С 1.3.0 у них есть перегрузки с параметром rules для фильтрации рекомендаций: правила рекомендаций.

Формат selector в Android 1.3.0

С 1.3.0 selector, group и campaignId отправляются в /choose как точные строки. Передавайте значение так же, как оно задано в кампании:

val response = GravitySDK.instance.getContentBySelector(
    selector = "homepage-recommendations",
    pageContext = pageContext,
)

Правило действует для всех getContentBy* и WithDetails, для GravityInlineCompose, GravityInlineView, GravityInlineListView и для методов сброса inline-кэша.

При переходе с 1.2.0 уберите обход прежней версии:

  • JSONObject.quote(...) вокруг selector, group и campaign ID;
  • " в XML-атрибутах app:selector и app:groupSelector;
  • собственные helper-функции, которые добавляли JSON-кавычки.

Заранее закавыченное значение, например "\"homepage-recs\"", в 1.3.0 отправляется буквально, вместе с кавычками, и не совпадёт с selector кампании: контент не загрузится. Строки, похожие на числа, например campaign ID "101", и пустая строка отправляются как строки, а не как числа.

SDK также сериализует ContentSettings под ключом option внутри data, в то время как iOS использует options. Если интеграция зависит от fields или skusOnly, проверьте фактический запрос и результат на вашем backend; документация не гарантирует, что backend применит эти настройки в Android 1.3.0.

Какие параметры нужны для получения контента

Для вызова getContentBySelector(...) обязательны:

Опциональны:

  • lng;
  • pageNumber;
  • referrer;
  • utm;
  • attributes.

skusOnly и fields не передаются в метод напрямую. Они задаются один раз через setOptions(...) в ContentSettings и затем сериализуются в последующих запросах choose. Применение этих полей сервером в 1.3.0 проверьте с учётом ключа option, описанного выше.

Как устроен ответ ContentResponse

Упрощенно структура ответа выглядит так:

ContentResponse
  -> data: List<Campaign>
      -> payload: List<CampaignVariation>
          -> contents: List<CampaignContent>
              -> products?.slots: List<Slot>

Это важно для manual rendering и engagement:

  • campaign берите из response.data;
  • content берите из campaign.payload[*].contents[*];
  • slot берите из content.products?.slots[*].

decisionId присутствует в CampaignVariation, но публичные методы sendContentEngagement(...) и sendProductEngagement(...) не требуют передавать его отдельным параметром.

Исходный JSON и переменные кампании

С 1.2.0 getContentBySelectorWithDetails(...) и getContentByCampaignIdWithDetails(...) возвращают модель и исходный JSON одного ответа. Внутри coroutine, для кампании с ключом button_title в variables:

val pageContext = PageContext(
    type = ContextType.HOMEPAGE,
    data = emptyList(),
    location = "app://home",
)
val details = GravitySDK.instance.getContentBySelectorWithDetails(
    selector = "homepage-banner-json",
    pageContext = pageContext,
)
if (details != null) {
    val response = details.data // ContentResponse; кампании находятся в response.data.
    val rawResponse = details.json // Map<String, Any?> всего ответа.
    val content = response.data.firstOrNull()?.payload?.firstOrNull()?.contents?.firstOrNull()
    val title = content?.rawVariables?.get("button_title") as? String ?: "Подробнее"
    val sameTitle = content?.variables?.valueOf<String>("button_title")
    // Постройте UI приложения; campaign и content сохраните для engagement.
}

val byId = GravitySDK.instance.getContentByCampaignIdWithDetails(
    campaignId = "YOUR_CAMPAIGN_ID",
    pageContext = pageContext,
)

rawVariables имеет тип Map<String, Any?>; неизвестные модели ключи, вложенные объекты, массивы и null сохраняются. Чтобы отличить отсутствующий ключ от явного null, используйте containsKey(...). valueOf<T>() проверяет тип без преобразования: для числа используйте Number, затем toInt() или toDouble(). Если variables отсутствует, создан вручную или через copy(), исходный словарь пуст. Типизированные variables.frameUI и variables.elements доступны как раньше.

rawVariables доступен и после обычного getContentBy*: WithDetails нужен, когда требуется JSON всего ответа. Это отдельный источник данных от строки content.custom?.json, описанной ниже. Загрузка автоматически отправляет content load tracking; фактический показ и клики собственного UI отправляет приложение.

Custom JSON

Пользовательский JSON приходит в content.custom?.json как строка. Для кампании с JSON { "variant": "compact" } приложение само разбирает конфигурацию:

val campaign = response?.data?.firstOrNull()
val content = campaign?.payload?.firstOrNull()?.contents?.firstOrNull()
val config = content?.custom?.json?.let { raw ->
    runCatching { JSONObject(raw) }.getOrNull()
}
val variant = config?.optString("variant", "control") ?: "control"
// Покажите UI для variant; неизвестное значение обработайте своим fallback.

Вариант A/B выбирает сервер. Сохраняйте campaign/content для engagement; impression отправляйте после фактического показа выбранного варианта, бизнес-события — в момент действия.

Методы выбора контента сами не показывают UI, но обычные trackView(...) и triggerEvent(...) могут запустить in-app кампанию. Если кампанию по просмотру или событию нужно нарисовать самостоятельно, используйте headless-режим. Presentation lock не отменяет HTTP-запросы и content load tracking.

Headless-режим

С 1.3.0 в Android SDK есть headless-режим: suspend-методы trackViewNoShow(pageContext) и triggerEventNoShow(events, pageContext) отправляют просмотр или событие и возвращают контент кампании, но не показывают UI. Activity им не нужна, presentation lock на них не влияет.

lifecycleScope.launch {
    // Для события: GravitySDK.instance.triggerEventNoShow(listOf(event), pageContext).
    val result = GravitySDK.instance.trackViewNoShow(pageContext)
        ?: return@launch // нет контента, ошибка или устаревший результат

    delay(result.delayTime.toLong()) // задержку кампании выдерживает приложение
    val campaign = result.data.data.first()
    val content = campaign.payload.first().contents.first { it.step == null }
    // Отрисуйте content; после фактического показа отправьте ContentImpressionEngagement.
}

Как SDK выбирает результат:

  • после успешного /visit или /event SDK перебирает кампании из ответа по убыванию приоритета; отсутствующий приоритет считается нулём, при равенстве сохраняется порядок сервера;
  • для каждой кампании выполняется запрос по campaign ID; возвращается первая кампания с корневым контентом (без step). Ошибка запроса или ответ без корневого контента переводят SDK к следующему кандидату;
  • результат — GravityDataResponse<ContentResponse>?: модель data, исходный JSON /choose в json и delayTime — неотрицательная задержка выбранной кампании в миллисекундах. SDK не ждёт эту задержку, ожидание и момент отрисовки определяет приложение;
  • null означает, что ни один кандидат не дал контента, отправка просмотра или события не удалась, загрузка контента выключена или результат устарел: прошло больше staleContentTimeoutMillis, сменился пользователь, SDK повторно инициализирован или вызван dispose(). При выключенной загрузке и устаревшем результате просмотр или событие всё равно отправляются.

Настройки headless-режима задаются у GravitySDK.instance:

Свойство По умолчанию Назначение
isFetchContentOnTrack: Boolean true false отключает загрузку контента: методы только отправляют просмотр или событие и возвращают null
staleContentTimeoutMillis: Long 10_000 Максимальный возраст результата от вызова метода; отрицательное значение заменяется на 0

Обе настройки действуют на весь процесс: их можно задать до initialize(...), и они сохраняются при повторной инициализации. На обычные trackView/triggerEvent и getContentBy* они не влияют.

Аналитика в headless-режиме:

  • SDK не открывает UI и не отправляет клиентские impression, visible impression и close: после фактического показа отправляйте engagement собственного UI;
  • ContentLoadEvent и onLoad tracking отправляются только для принятого результата; ContentLoadEvent.delayTime совпадает с delayTime ответа;
  • Options из setOptions(...) передаются без изменений, поэтому неявный серверный impression определяет isImplicitImpression (по умолчанию true).

Для одного просмотра или действия вызывайте один метод: trackViewNoShow вместо trackView, triggerEventNoShow вместо triggerEvent. Иначе просмотр или событие будут отправлены дважды. Сигнатуры.

Аналитика собственного UI

Загрузка не означает показ. Сохраните исходные campaign/content и при работе с товарами slot. Передавайте их в engagement после фактического взаимодействия:

Действие Тип engagement
Контент появился в интерфейсе ContentImpressionEngagement
Контент достиг порога видимости ContentVisibleImpressionEngagement
Контент закрыт ContentCloseEngagement
Карточка товара достигла порога видимости ProductVisibleImpressionEngagement
Пользователь нажал на товар ProductClickEngagement

Порог и дедупликацию реализует приложение. Встроенный Android detector для inline/товаров использует 50% площади в течение секунды; полный пример дополнительно дедуплицирует показ каждого размещения.

Публичного ContentClickEngagement нет. sendContentEngagement/sendProductEngagement вызывают tracking URL, но не gravityEventCallback. Для бизнес-действий отправляйте TriggerEvent отдельно. Справочник engagement.