Конфигурация Android SDK
Инициализируйте SDK один раз при старте приложения. Установка и минимальное приложение; точные сигнатуры собраны в справочнике API.
Инициализация
Основной метод настройки SDK. Вызывается один раз при старте приложения.
С 1.3.0 GravitySDK.instance до initialize(...) не выбрасывает исключение, а возвращает заглушку. В ней доступны методы серверного UID и настройки headless-режима; остальные методы, например trackView, setOptions или getContentBySelector, по-прежнему выбрасывают GravitySDK has not been initialized. Проверить состояние можно через GravitySDK.isInitialized. Inline-компоненты, добавленные на экран до инициализации, ждут её и затем загружают контент.
initialize(context, ...) также настраивает хранилище серверного UID. Повторный вызов сбрасывает пользователя из setUser.
Подготовка in-app перед показом
Передайте inAppPreparation, если до показа нужно дождаться API приложения: например, проверить, о каких покупках ещё можно оставить отзыв. Обработчик возвращает контент для показа или null для пропуска. По умолчанию на подготовку отведено 5 секунд; ошибка и таймаут также пропускают in-app. Без обработчика дополнительного ожидания нет.
Обработчик работает после productFilter, content load tracking и задержки кампании. Перед показом SDK повторно проверяет Activity, пользователя и presentation lock. Ограничивайте обработку нужной кампанией; для остальных возвращайте исходный контент. Сигнатуры и полный пример отзывов.
Логирование SDK
Android SDK поддерживает параметр logLevel в initialize(...). Он управляет только внутренними логами SDK и не влияет на gravityEventCallback, отправку событий или логи приложения.
Логи пишутся через Android Log с тегом GravitySDK.
LogLevel.DEBUGвключает HTTP debug-логи SDK и сообщения об ошибках. С 1.3.0 HTTP-лог содержит только метод, endpoint без учётных данных и статус ответа, без тел запросов и ответов, значений заголовков и текста исключений; заголовок авторизации отмечается как скрытый.LogLevel.INFOвключает информационные сообщения, например о блокировке показа кампаний, и ошибки.LogLevel.ERRORоставляет только ошибки SDK.LogLevel.NONEотключает локальный вывод SDK. Отправка внутренних ошибок вsdk-sentry.gravityfield.ai/errorвыполняется отдельно и не отключается уровнем логирования. С 1.3.0 отчёт об HTTP-ошибке содержит только метод, endpoint без учётных данных и HTTP-статус, без тела ответа и стека исключения; значенияAuthorizationи URL с учётными данными очищаются. SDK отправляет не больше 10 отчётов в минуту и не повторяет одинаковые отчёты в течение 60 секунд после успешной отправки.
По умолчанию используется LogLevel.NONE. При стандартной production-инициализации SDK не пишет в системный лог HTTP-запросы, ответы и API key. В 1.2.0 LogLevel.DEBUG выводил полные request/response; с 1.3.0 тела запросов в лог не попадают, поэтому содержимое запроса проверяйте через прокси или на backend.
Глобальные настройки
Метод задает глобальные настройки, которые применяются ко всем последующим вызовам trackView(...), triggerEvent(...) и getContentBySelector(...).
Пример:
GravitySDK.instance.setOptions(
options = Options(
isReturnUserInfo = true,
isReturnAnalyticsMetadata = true,
),
contentSettings = ContentSettings(
skusOnly = false,
fields = listOf("name", "price", "imageUrl"),
),
proxyUrl = "https://my-proxy.example.com/v2",
)
Что настраивается через Options
Что настраивается через ContentSettings
Практически это означает следующее:
- если
skusOnly = true, SDK запрашивает только SKU; приложение само догружает товарные данные; - если
fieldsзадан, SDK запрашивает только указанные товарные поля; - если
setOptions(...)не вызывается, используются стандартные значенияOptions()иContentSettings().
setOptions(...) заменяет настройки целиком; null сбрасывает соответствующий объект к значениям по умолчанию. SDK также передаёт isBuildEngagementUrl = true; через публичный конструктор Options этот флаг не меняется.
proxyUrl задаёт полный базовый URL API, например https://my-proxy.example.com/v2, без завершающего /. SDK добавляет /visit, /event или /choose. Tracking URL из ответа и адрес отправки ошибок этим параметром не заменяются. Без proxyUrl используется https://evs-01.gravityfield.ai/v2.
У текущей реализации Android /choose есть особенности сериализации, в том числе для ContentSettings. С 1.3.0 selector, group и campaign ID передаются обычными строками.
Настройки headless-режима isFetchContentOnTrack и staleContentTimeoutMillis задаются отдельно от setOptions(...): headless-режим.
Кастомизация UI
Настройка шрифта
Встроенные UI-компоненты SDK можно стилизовать через UISettings.
val uiSettings = UISettings(fontResId = R.font.my_custom_font)
GravitySDK.initialize(
context = this,
apiKey = "YOUR_API_KEY",
section = "YOUR_SECTION_ID",
gravityEventCallback = ::handleGravityEvent,
uiSettings = uiSettings,
)
После этого встроенные текстовые элементы SDK будут использовать указанный шрифт.
Подключение исходного модуля
Если нужно собирать SDK из исходников, скопируйте gravity_sdk, подключите include(":gravity_sdk") и implementation(project(":gravity_sdk")). Дополнительно перенесите version catalog gravity_sdk/gradle/libs.versions.toml как gravitySdk в settings.gradle.kts и задайте SDK_VERSION=1.3.1 в gradle.properties:
dependencyResolutionManagement {
// Используйте блок repositories вашего проекта.
versionCatalogs {
create("gravitySdk") {
from(files("gravity_sdk/gradle/libs.versions.toml"))
}
}
}
Версии Android Gradle Plugin, Kotlin и Compose compiler согласуйте с основным проектом. Простого копирования модуля без его catalog и SDK_VERSION недостаточно.
Обработка обратных вызовов (Callbacks)
Подпишитесь на события SDK через gravityEventCallback в initialize(...). SDK доставляет tracking callbacks через главный поток; навигацию выполняйте в контексте актуального экрана.
Справочник по событиям TrackingEvent
Пример обработки:
private fun handleGravityEvent(event: TrackingEvent) {
when (event) {
is FollowUrlEvent -> {
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(event.url))
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
startActivity(intent)
}
is FollowDeeplinkEvent -> {
// Выполните навигацию по deeplink
}
is RequestPushEvent -> {
// При необходимости обработайте событие в аналитике
}
else -> Unit
}
}
Передача статуса Push-уведомлений
Если таргетинг кампаний зависит от статуса push-разрешения, передавайте его в SDK.
setNotificationPermissionStatus()
Допустимые значения:
NotificationPermissionStatus.GRANTEDNotificationPermissionStatus.DENIEDNotificationPermissionStatus.UNKNOWN
Пример:
import androidx.core.app.NotificationManagerCompat
val areNotificationsEnabled =
NotificationManagerCompat.from(context).areNotificationsEnabled()
val status = if (areNotificationsEnabled) {
NotificationPermissionStatus.GRANTED
} else {
NotificationPermissionStatus.DENIED
}
GravitySDK.instance.setNotificationPermissionStatus(status)
SDK добавляет это значение в device.permission последующих запросов. Для базовой интеграции этот шаг не обязателен, но он необходим, если push-статус участвует в таргетинге.
Блокировка показа in-app кампаний
Используйте presentation lock, когда приложение показывает собственную модалку, bottom sheet, onboarding или другой приоритетный слой интерфейса, который не должен перекрываться кампанией Gravity.
private fun showCheckoutBottomSheet() {
GravitySDK.instance.lockPresentation()
CheckoutBottomSheet(
onDismiss = {
GravitySDK.instance.unlockPresentation()
}
).show(supportFragmentManager, "checkout")
}
Пока блокировка активна, SDK может загрузить контент, но не будет показывать новую in-app кампанию поверх текущего интерфейса. Уже открытый Gravity-контент этим вызовом не закрывается.
Если приложению нужно отслеживать состояние блокировки, подпишитесь на изменения:
GravitySDK.instance.setPresentationLockListener { locked ->
// Обновите состояние приложения, если это нужно вашему UI
}
Это один Boolean-флаг, счётчика вложенных блокировок нет. Повторный lock не требует дополнительного unlock. Пропущенная кампания не ставится в очередь и не появится автоматически после разблокировки. Ручная загрузка и inline-компоненты не блокируются. В 1.1.0 переход OPEN_STEP также проходит подготовку и проверяет presentation lock.
Вызов lockPresentation() делает ожидающий показ неактуальным: снятие блокировки не возвращает прежний результат в очередь. После разблокировки выполните новый trackView или triggerEvent. При навигации внутри одной Activity используйте блокировку, чтобы запоздалый результат не появился на другом экране.
Listener вызывается синхронно на потоке вызывающего кода при lock/unlock; при подписке текущее состояние не отправляется. Для снятия подписки передайте null. При dispose() listener очищается.