# Android SDK: обзор и быстрый старт

Gravity Field SDK передаёт просмотры экранов и события, получает персонализированный контент и показывает кампании в приложении. Выбор кампаний и A/B-вариантов выполняет сервер; приложение отвечает за навигацию и может рисовать контент самостоятельно.

Руководство сверено 2 октября 2026 года с публичным кодом и опубликованным AAR **Android SDK 1.0.4**, коммит [`d60aadf`](https://github.com/Gravity-Field/gravity-sdk-android/tree/d60aadf67afd85dc8d87a9f56bd3f0b3b1ee2dbc). В модуле SDK заданы **minSdk 21**, **compileSdk 35**, JVM target **11**. Для версии `1.0.4` SDK использует Compose BOM `2024.09.00`.

[Репозиторий SDK](https://github.com/Gravity-Field/gravity-sdk-android) · [История изменений](https://github.com/Gravity-Field/gravity-sdk-android/blob/d60aadf67afd85dc8d87a9f56bd3f0b3b1ee2dbc/CHANGELOG.md)

| Задача | Раздел |
|---|---|
| Настроить SDK, callback и разрешения | [Конфигурация](./configuration.md) |
| Связать пользователя между каналами | [Идентификация](./identity.md) |
| Передавать контекст и события | [Контекст и события](./events.md) |
| Показать кампанию или рекомендации | [Кампании и рекомендации](./campaigns.md) |
| Рисовать контент самостоятельно | [Свой UI и Custom JSON](./custom_ui.md) |
| Проверить варианты интерфейса | [A/B через JSON](./ab_testing.md) |
| Менять структуру виджета с сервера | [Backend-Driven UI](./bdui.md) |

## Установка

### Готовый Maven-артефакт

В публичном репозитории SDK есть Maven-папка с AAR, POM и Gradle metadata. Чтобы подключить именно `1.0.4`:

1. Скачайте репозиторий по коммиту `d60aadf67afd85dc8d87a9f56bd3f0b3b1ee2dbc` и скопируйте `gravity_sdk/repository` в корень своего проекта под именем `gravity-sdk-repository`.
2. В `settings.gradle.kts` добавьте локальный Maven-репозиторий рядом с `google()` и `mavenCentral()`:

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("gravity-sdk-repository") }
    }
}
```

3. В `app/build.gradle.kts` добавьте SDK. Для Compose-примера также нужны Activity Compose и Material 3:

```kotlin
dependencies {
    implementation("ai.gravityfield:gravity-sdk:1.0.4")
    implementation("androidx.activity:activity-compose:1.9.2")
    implementation(platform("androidx.compose:compose-bom:2024.09.00"))
    implementation("androidx.compose.material3:material3")
}
```

Включите `buildFeatures { compose = true }` и плагин `org.jetbrains.kotlin.plugin.compose` той же версии, что Kotlin в вашем проекте. Опубликованный POM SDK содержит Kotlin `2.0.21`. Не подключайте один AAR через `files(...)`: при таком подключении Gradle не получит транзитивные зависимости из POM/metadata.

Разрешение `android.permission.INTERNET` уже присутствует в manifest библиотеки и объединяется с manifest приложения. Проверьте его наличие в merged manifest release-сборки.

## Минимальное приложение

1. Получите `apiKey` и `section` проекта.
2. Опубликуйте inline-кампанию с selector `product_recommendations` и контекстом `PRODUCT`, SKU `sku-123`, location `app://product/sku-123`.
3. Для проверки автопоказа опубликуйте in-app кампанию по просмотру этого экрана или событию `add-to-cart-v1`.
4. Добавьте [quick_start.kt](./examples/quick_start.kt) в Compose-проект. Замените package, API key, секцию и SKU, если в вашем фиде используется другой товар.
5. Зарегистрируйте `GravityDemoApplication` и `MainActivity` в manifest; удалите старую launcher-Activity или перенесите код в неё:

```xml
<application android:name="com.example.gravitydemo.GravityDemoApplication">
    <activity android:name="com.example.gravitydemo.MainActivity" android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>
```

Пример передаёт просмотр один раз при входе в Compose-экран, отправляет событие по кнопке и встраивает рекомендации. Карточка товара реализована в том же файле; навигацию подключите к роутеру приложения. В реальном приложении событие добавления в корзину отправляйте после успешного изменения корзины.
Кодирование selector в примере соответствует [ограничению Android 1.0.4](./custom_ui.md#формат-selector-в-android-104). Исходный модуль можно подключить по [отдельной инструкции](./configuration.md#подключение-исходного-модуля).

Настройка форматов и сценариев в кабинете: [Кампании в приложении](/personalization/Campaigns/app_campaigns/getting_started.md).

<a id="page-context"></a>

## PageContext

Поля контекста, SKU, категории и регион описаны в [Контексте и событиях](./events.md#pagecontext).

<a id="android-sdk-logging"></a>

## Логирование SDK

Уровни логирования, debug-диагностика и телеметрия ошибок описаны в [Конфигурации](./configuration.md#логирование-sdk).

<a id="presentation-lock"></a>

## Блокировка показа in-app кампаний

[Presentation lock и её ограничения](./configuration.md#блокировка-показа-in-app-кампаний).

<a id="inline-cache"></a>

## Кэш inline-блоков

[Ключи кэша и очистка при выходе с экрана](./campaigns.md#кэш-inline-блоков).

<a id="sdk-context-attributes"></a>

## Служебные атрибуты

[app_version, sdk_version и app_platform](./events.md#pagecontext).

## Следующие шаги

- [Сеть и жизненный цикл](./network.md).
- [Справочник API](./api_reference.md).
- [Проверка интеграции перед выпуском](./troubleshooting.md).