Свой 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(...) обязательны:
selector;pageContext.type;pageContext.data;pageContext.location.
Опциональны:
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или/eventSDK перебирает кампании из ответа по убыванию приоритета; отсутствующий приоритет считается нулём, при равенстве сохраняется порядок сервера; - для каждой кампании выполняется запрос по campaign ID; возвращается первая кампания с корневым контентом (без
step). Ошибка запроса или ответ без корневого контента переводят SDK к следующему кандидату; - результат —
GravityDataResponse<ContentResponse>?: модельdata, исходный JSON/chooseвjsonиdelayTime— неотрицательная задержка выбранной кампании в миллисекундах. SDK не ждёт эту задержку, ожидание и момент отрисовки определяет приложение; nullозначает, что ни один кандидат не дал контента, отправка просмотра или события не удалась, загрузка контента выключена или результат устарел: прошло большеstaleContentTimeoutMillis, сменился пользователь, SDK повторно инициализирован или вызванdispose(). При выключенной загрузке и устаревшем результате просмотр или событие всё равно отправляются.
Настройки headless-режима задаются у GravitySDK.instance:
Обе настройки действуют на весь процесс: их можно задать до 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 после фактического взаимодействия:
Порог и дедупликацию реализует приложение. Встроенный Android detector для inline/товаров использует 50% площади в течение секунды; полный пример дополнительно дедуплицирует показ каждого размещения.
Публичного ContentClickEngagement нет. sendContentEngagement/sendProductEngagement вызывают tracking URL, но не gravityEventCallback. Для бизнес-действий отправляйте TriggerEvent отдельно. Справочник engagement.