Справочник 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
)
Поле Options По умолчанию
isReturnCounter false
isReturnUserInfo false
isReturnAnalyticsMetadata false
isImplicitPageview false
isImplicitImpression true
isBuildEngagementUrl true, без публичного параметра для изменения

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(),
)

Ответ и модели

Тип/поле Содержание
ContentResponse Опциональный user и список data с кампаниями
Campaign.payload Список вариантов CampaignVariation
CampaignVariation Идентификаторы решения и список contents
CampaignContent contentId, deliveryMethod, step, variables, products, items, custom, events
content.variables Типизированные frameUI, elements и действия жизненного цикла; может отсутствовать
GravityDataResponse<ContentResponse> data — модель; json: Map<String, Any?> — исходный JSON того же ответа; delayTime — задержка кампании в headless-режиме
content.rawVariables Map<String, Any?> со всеми ключами variables, включая неизвестные модели и null
content.variables?.raw / content.variables?.get("key") Полный объект переменных / чтение отдельного ключа
content.variables?.valueOf<T>("key") Чтение ключа с проверкой типа T, без преобразования значения
content.custom?.json Строка пользовательского JSON, разбирается приложением
Slot item, strId, опциональный slotId, fallback и tracking-события

С 1.2.0 доступны rawVariables и два метода WithDetails. С 1.3.0 есть headless-режим trackViewNoShow/triggerEventNoShow; ContentLoadEvent.delayTime содержит задержку кампании для принятого headless-результата и 0 в остальных случаях.

События TriggerEvent

С 1.2.0 у всех событий есть необязательные customProps: Map<String, String>? и eventTime: java.util.Date?. Значения свойств — только строки. SDK отправляет время в UTC (RFC 3339); если время не указано, фиксирует момент вызова triggerEvent(...), до асинхронной отправки. Пример.

Событие Описание Основные параметры
AddToCartEvent Добавление товара в корзину value, productId, quantity, currency?, cart?
PurchaseEvent Успешная покупка uniqueTransactionId, value, cart, currency?
RemoveFromCartEvent Удаление товара из корзины value, productId, quantity, currency?, cart?
SyncCartEvent Передача актуального состава корзины value, currency?, cart?
AddToWishlistEvent Добавление в избранное value, productId
SignUpEvent Регистрация пользователя hashedEmail?, cuid?, cuidType?
LoginEvent Авторизация пользователя hashedEmail?, cuid?, cuidType?
CustomEvent Кастомное событие type, name, customProps?

Для LoginEvent и SignUpEvent рекомендуется передавать cuid и cuidType, даже если на уровне класса эти поля не обязательны.

Engagement-типы

Содержимое Публичные типы
Контент ContentImpressionEngagement, ContentVisibleImpressionEngagement, ContentCloseEngagement
Товары ProductClickEngagement, ProductVisibleImpressionEngagement

Передавайте исходные content, campaign и slot из ответа SDK. Публичного ContentClickEngagement нет; ручная отправка engagement не вызывает tracking callback. Условия учёта показов.

UI-компоненты

Компонент Параметры
GravityInlineCompose Обязательные modifier, selector, pageContext, nullable loader; с 1.3.0 перегрузка с rules
GravityInlineView XML-атрибут selector, затем init(pageContext); с 1.3.0 setRules(rules)
GravityInlineListView XML-атрибут groupSelector, затем init(pageContext); с 1.3.0 setRules(rules)
UISettings fontResId: Int?
@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
}

Примеры карточек.