Справочник Android SDK 1.3.0
Сигнатуры сверены с публичным исходным кодом. Примеры настройки — в Конфигурации, бизнес-сценарии — в Контексте и событиях.
Инициализация и настройки
fun initialize(
context: Context,
apiKey: String,
section: String,
gravityEventCallback: GravityEventCallback,
productViewBuilder: ProductViewBuilder? = null,
productFilter: ProductFilter? = null,
uiSettings: UISettings? = null,
logLevel: LogLevel = LogLevel.NONE,
)
fun setOptions(
options: Options?,
contentSettings: ContentSettings?,
proxyUrl: String?,
)
fun setNotificationPermissionStatus(status: NotificationPermissionStatus)
Типы callback
typealias ProductFilter = (Slot) -> Boolean
typealias GravityEventCallback = (TrackingEvent) -> Unit
Доступ к экземпляру: GravitySDK.instance: GravitySDK. С 1.3.0 до initialize он возвращает заглушку: доступны методы серверного UID и настройки headless-режима, остальные методы выбрасывают GravitySDK has not been initialized.
// В companion object GravitySDK, с 1.3.0
val isInitialized: Boolean // GravitySDK.isInitialized == true после initialize(...)
Идентификация
fun setUser(userId: String, sessionId: String)
setUser задаёт custom/ses для просмотров, событий и запросов контента, включая inline и автопоказ. Правила идентификации.
С 1.3.0 доступны методы серверного UID; их можно вызывать и до initialize:
suspend fun getUserId(): String?
fun setUserIdListener(listener: ((String?) -> Unit)?)
suspend fun resetUser()
suspend fun restoreUserId(uid: String)
restoreUserId обрезает пробелы и выбрасывает IllegalArgumentException для пустой строки. resetUser и restoreUserId сбрасывают сессию и пользователя из setUser; ошибки хранилища передаются вызывающему коду. Listener один на процесс и вызывается на главном потоке. Сценарии и правила.
Просмотры и события
fun trackView(
pageContext: PageContext,
activityContext: Context,
)
fun triggerEvent(
events: List<TriggerEvent>,
pageContext: PageContext,
activityContext: Context,
)
Headless-режим
suspend fun trackViewNoShow(
pageContext: PageContext,
): GravityDataResponse<ContentResponse>?
suspend fun triggerEventNoShow(
events: List<TriggerEvent>,
pageContext: PageContext,
): GravityDataResponse<ContentResponse>?
var isFetchContentOnTrack: Boolean // по умолчанию true
var staleContentTimeoutMillis: Long // по умолчанию 10_000, отрицательное значение -> 0
Методы доступны с 1.3.0. Они отправляют просмотр или событие и возвращают контент кампании с наибольшим приоритетом, у которой есть корневой контент; неудачные кандидаты пропускаются. Activity не нужна, UI не открывается, клиентские impression не отправляются. delayTime в ответе — задержка кампании в миллисекундах, её выдерживает приложение. Свойства задаются у GravitySDK.instance, действуют на весь процесс и сохраняются до и после initialize. Правила и пример.
Загрузка контента
suspend fun getContentBySelector(
selector: String,
pageContext: PageContext,
): ContentResponse?
suspend fun getContentByGroupSelector(
groupSelector: String,
pageContext: PageContext,
): ContentResponse?
suspend fun getContentByCampaignId(
campaignId: String,
pageContext: PageContext,
): ContentResponse?
// С 1.3.0: перегрузки с правилами рекомендаций
suspend fun getContentBySelector(
selector: String,
pageContext: PageContext,
rules: List<RtRule>?,
): ContentResponse?
suspend fun getContentByGroupSelector(
groupSelector: String,
pageContext: PageContext,
rules: List<RtRule>?,
): ContentResponse?
suspend fun getContentByCampaignId(
campaignId: String,
pageContext: PageContext,
rules: List<RtRule>?,
): ContentResponse?
Ошибка, включая неуспешный HTTP-статус, возвращает null; успешный ответ может содержать пустой data. С 1.3.0 selector, group и campaign ID передаются обычными строками, без JSON-кавычек: переход с 1.2.0. rules = null не добавляет ключ rules в запрос: правила рекомендаций. Эти методы не показывают UI, но отправляют content load tracking.
Загрузка исходного JSON
suspend fun getContentBySelectorWithDetails(
selector: String,
pageContext: PageContext,
): GravityDataResponse<ContentResponse>?
suspend fun getContentByCampaignIdWithDetails(
campaignId: String,
pageContext: PageContext,
): GravityDataResponse<ContentResponse>?
// С 1.3.0
suspend fun getContentBySelectorWithDetails(
selector: String,
pageContext: PageContext,
rules: List<RtRule>?,
): GravityDataResponse<ContentResponse>?
suspend fun getContentByCampaignIdWithDetails(
campaignId: String,
pageContext: PageContext,
rules: List<RtRule>?,
): GravityDataResponse<ContentResponse>?
data class GravityDataResponse<T>(
val data: T,
val json: Map<String, Any?>,
val delayTime: Int = 0,
)
GravityDataResponse.data — модель ContentResponse, json — весь ответ как Map<String, Any?>, включая неизвестные модели ключи и JSON null. delayTime (с 1.3.0) заполняется только в headless-режиме; у getContentBy*WithDetails он всегда 0.
Оба метода доступны с 1.2.0. Они возвращают модель и JSON одного ответа, отправляют content load tracking и не показывают UI. Ошибка запроса или разбора возвращает null. Версии WithDetails для группы нет.
Правила рекомендаций
data class RtRule(
val type: String,
val conditions: List<RtRuleCondition>,
val id: Int? = null,
val slots: List<Int>? = null,
)
data class RtRuleCondition(
val field: String,
val arguments: List<RtRuleArgument>,
)
data class RtRuleArgument(
val action: String,
val value: List<String>,
)
Типы находятся в пакете ai.gravityfield.gravity_sdk.models и доступны с 1.3.0. Правила отправляются в data[].rules запроса /choose; id и slots всегда присутствуют в JSON, при отсутствии значения — как null. Пример фильтра. Примеры чтения.
Engagement
fun sendContentEngagement(engagement: ContentEngagement)
fun sendProductEngagement(engagement: ProductEngagement)
Presentation lock
fun lockPresentation()
fun unlockPresentation()
fun setPresentationLockListener(listener: ((Boolean) -> Unit)?)
Подготовка и закрытие in-app
В 1.1.0 добавлена перегрузка initialize с последним параметром inAppPreparation. Остальные параметры и их значения по умолчанию совпадают с основной сигнатурой:
fun initialize(
context: Context,
apiKey: String,
section: String,
gravityEventCallback: GravityEventCallback,
productViewBuilder: ProductViewBuilder? = null,
productFilter: ProductFilter? = null,
uiSettings: UISettings? = null,
logLevel: LogLevel = LogLevel.NONE,
inAppPreparation: InAppPreparation?,
)
typealias InAppPreparationHandler =
suspend (CampaignContent, Campaign) -> CampaignContent?
class InAppPreparation(
val timeoutMillis: Long = 5_000,
private val handler: InAppPreparationHandler,
)
fun CampaignContent.filteringProducts(
predicate: (Slot) -> Boolean,
): CampaignContent?
fun dismissInApp(contentId: String, completion: (Boolean) -> Unit = {})
inAppPreparation выполняется перед автопоказом и при OPEN_STEP, после productFilter, content load tracking и задержки кампании. Возврат null, ошибка или таймаут пропускают этот in-app. Допустимый timeoutMillis: от 1 до 3 600 000; используйте отменяемые suspending-запросы. Ручные getContentBy* и inline не запускают подготовку.
filteringProducts сохраняет исходные слоты, их порядок, события и метаданные. Если товаров не осталось или товарного блока нет, возвращается null; SDK не догружает замену удалённым товарам.
dismissInApp закрывает показанный SDK in-app с указанным contentId. Completion получает true на главном потоке после закрытия UI; false — если подходящего показа нет или он уже закрывается. SDK отправляет close один раз, product click отправляет приложение. Inline не закрывается. Вызывайте метод до dispose().
Настройка и полный пример отзывов.
Кэш и завершение работы
fun resetInlineViewCache(selector: String, pageContext: PageContext)
fun resetInlineListViewCache(groupSelector: String, pageContext: PageContext)
fun dispose()
Настройки запросов
data class Options(
val isReturnCounter: Boolean = false,
val isReturnUserInfo: Boolean = false,
val isReturnAnalyticsMetadata: Boolean = false,
val isImplicitPageview: Boolean = false,
val isImplicitImpression: Boolean = true,
) {
val isBuildEngagementUrl: Boolean = true
}
data class ContentSettings(
val skusOnly: Boolean = false,
val fields: List<String>? = null
)
ContentSettings: skusOnly по умолчанию false, fields — null. Оба объекта заменяются целиком через setOptions.
PageContext
data class PageContext(
val type: ContextType,
val data: List<String>,
val location: String,
val lng: String? = null,
val pageNumber: Int? = null,
val referrer: String? = null,
val utm: Map<String, String>? = null,
val attributes: Map<String, String> = emptyMap(),
)
Ответ и модели
С 1.2.0 доступны rawVariables и два метода WithDetails. С 1.3.0 есть trackViewNoShow/triggerEventNoShow; ContentLoadEvent.delayTime содержит задержку кампании для принятого headless-результата и 0 в остальных случаях.
События TriggerEvent
С 1.2.0 у всех событий есть необязательные customProps: Map<String, String>? и eventTime: java.util.Date?. Значения свойств — только строки. SDK отправляет время в UTC (RFC 3339); если время не указано, фиксирует момент вызова triggerEvent(...), до асинхронной отправки. Пример.
Для LoginEvent и SignUpEvent рекомендуется передавать cuid и cuidType, даже если на уровне класса эти поля не обязательны.
Engagement-типы
Передавайте исходные content, campaign и slot из ответа SDK. Публичного ContentClickEngagement нет; ручная отправка engagement не вызывает tracking callback. Условия учёта показов.
UI-компоненты
@Composable
fun GravityInlineCompose(
modifier: Modifier,
selector: String,
pageContext: PageContext,
loader: (@Composable () -> Unit)?,
)
// С 1.3.0
@Composable
fun GravityInlineCompose(
modifier: Modifier,
selector: String,
pageContext: PageContext,
loader: (@Composable () -> Unit)?,
rules: List<RtRule>?,
)
// GravityInlineView и GravityInlineListView
fun init(pageContext: PageContext)
fun setRules(rules: List<RtRule>?) // с 1.3.0
Смена rules перезагружает блок и не переиспользует контент, загруженный для других правил.
interface ProductViewBuilder {
@Composable
fun Build(slot: Slot, content: CampaignContent, campaign: Campaign)
}
interface LegacyProductViewBuilder : ProductViewBuilder {
@Composable
override fun Build(slot: Slot, content: CampaignContent, campaign: Campaign)
fun createView(
context: Context,
slot: Slot,
content: CampaignContent,
campaign: Campaign,
): View
}