# Справочник Android SDK 1.0.4

Сигнатуры сверены с [публичным исходным кодом](https://github.com/Gravity-Field/gravity-sdk-android/blob/d60aadf67afd85dc8d87a9f56bd3f0b3b1ee2dbc/gravity_sdk/src/main/java/ai/gravityfield/gravity_sdk/GravitySDK.kt). Примеры настройки — в [Конфигурации](./configuration.md), бизнес-сценарии — в [Контексте и событиях](./events.md).

## Инициализация и настройки

```kotlin
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

```kotlin
typealias ProductFilter = (Slot) -> Boolean
typealias GravityEventCallback = (TrackingEvent) -> Unit
```

Доступ к экземпляру: `GravitySDK.instance: GravitySDK`. До initialize он выбрасывает исключение.

## Идентификация

```kotlin
fun setUser(userId: String, sessionId: String)
```

`setUser` задаёт `custom`/`ses` для просмотров и событий. Его ограничение для `/choose` описано в [Идентификации](./identity.md#ограничение-setuser).

## Просмотры и события

```kotlin
fun trackView(
    pageContext: PageContext,
    activityContext: Context,
    )

fun triggerEvent(
    events: List<TriggerEvent>,
    pageContext: PageContext,
    activityContext: Context,
    )
```

## Загрузка контента

```kotlin
suspend fun getContentBySelector(
    selector: String,
    pageContext: PageContext,
    ): ContentResponse?

suspend fun getContentByGroupSelector(
    groupSelector: String,
    pageContext: PageContext,
    ): ContentResponse?

suspend fun getContentByCampaignId(
    campaignId: String,
    pageContext: PageContext,
    ): ContentResponse?
```

Ошибка возвращает `null`; успешный ответ может содержать пустой `data`. Значения selector/group/строкового ID кодируйте по [правилу Android 1.0.4](./custom_ui.md#формат-selector-в-android-104). Эти методы не показывают UI, но отправляют content load tracking.

## Engagement

```kotlin
fun sendContentEngagement(engagement: ContentEngagement)

fun sendProductEngagement(engagement: ProductEngagement)
```

## Presentation lock

```kotlin
fun lockPresentation()

fun unlockPresentation()

fun setPresentationLockListener(listener: ((Boolean) -> Unit)?)
```

## Кэш и завершение работы

```kotlin
fun resetInlineViewCache(selector: String, pageContext: PageContext)

fun resetInlineListViewCache(groupSelector: String, pageContext: PageContext)

fun dispose()
```

## Настройки запросов

```kotlin
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

```kotlin
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` и действия жизненного цикла; может отсутствовать |
| `content.custom?.json` | Строка пользовательского JSON, разбирается приложением |
| `Slot` | `item`, `strId`, опциональный `slotId`, `fallback` и tracking-события |

Native SDK не предоставляет аналоги Flutter `rawVariables`, `WithDetails`, `trackViewNoShow` или `triggerEventNoShow`. Используйте [свой UI и Custom JSON](./custom_ui.md) с доступными native-методами.

## События 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. [Условия учёта показов](./custom_ui.md#аналитика-собственного-ui).

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

| Компонент | Параметры |
|---|---|
| `GravityInlineCompose` | Обязательные `modifier`, `selector`, `pageContext`, nullable `loader` |
| `GravityInlineView` | XML-атрибут `selector`, затем `init(pageContext)` |
| `GravityInlineListView` | XML-атрибут `groupSelector`, затем `init(pageContext)` |
| `UISettings` | `fontResId: Int?` |

```kotlin
@Composable
fun GravityInlineCompose(
    modifier: Modifier,
    selector: String,
    pageContext: PageContext,
    loader: (@Composable () -> Unit)?,
)

// GravityInlineView и GravityInlineListView
fun init(pageContext: PageContext)
```

```kotlin
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
}
```

[Примеры карточек](./campaigns.md#карточки-товаров).