Публичный API SDK

SDK собран из модулей: обязательного Core и опциональных Push, Target, Profile, In-App. Каждый модуль подключается отдельной зависимостью и открывается через соответствующее свойство объекта AltcraftSDK:

AltcraftSDK          // Core: инициализация, аутентификация, события, очистка
AltcraftSDK.auth     // Core: аутентификация пользователя
AltcraftSDK.push     // Push: подписки, токены, уведомления
AltcraftSDK.target   // Target: отправка целей
AltcraftSDK.profile  // Profile: поля профиля
AltcraftSDK.inApp    // In-App: кампании и подписки

Core (обязательный модуль)

object AltcraftSDK

AltcraftSDK
// Инициализация SDK и установка конфигурации
├─ fun initialization(context: Context, configuration: AltcraftConfiguration, complete: ((Result<Unit>) -> Unit)? = null): Unit
// Полная очистка данных SDK (БД, SP, фоновые задачи)
├─ fun clear(context: Context, onComplete: (() -> Unit)? = null): Unit
// Разрешить переинициализацию retry-операций и проверки токена в текущей сессии
├─ fun unlockInitialOperationsInThisSession(): Unit
// Доступ к аутентификации пользователя
├─ val auth: AuthAPI
// Доступ к событиям SDK (один подписчик)
└─ val sdkEvents: SDKEvents

object AuthAPI

AuthAPI
// Установить провайдера JWT-токенов (null — снять)
├─ fun setJWTProvider(provider: JWTInterface?): Unit
// Аутентификация пользователя
├─ fun authenticate(context: Context): Unit
// Выход пользователя (восстановление анонимной сессии)
├─ fun logOut(context: Context): Unit
// Проверка статуса аутентификации
└─ suspend fun isAuthenticated(context: Context): Boolean

object SDKEvents

SDKEvents
// Доступ к подписке на события SDK
├─ val subscription: Events.Subscription
// Типы событий Core-модуля
└─ val moduleEvents: CoreEvents

object Events.Subscription

Events.Subscription
// Подписаться на события SDK (заменяет существующего подписчика)
├─ fun subscribe(newSubscriber: (Event) -> Unit): Unit
// Отписаться от событий SDK
└─ fun unsubscribe(): Unit

object CoreEvents — публичные события Core-модуля

CoreEvents
// Общие события SDK
├─ val configIsSet: SDKEvent             // SDK configuration is installed
├─ val sdkCleared: SDKEvent              // SDK data has been cleared
├─ val notAuthenticatedError: SDKEvent   // User is not authenticated
├─ val userLogOut: SDKEvent              // User logged out. Anonymous session started.
├─ val roomMigrationError: SDKEvent      // Room database migration failed. The local SDK database will be recreated.
// Успешные API-запросы
├─ val authenticateSuccessful: SDKEvent  // successful request: profile/authenticate
// Неудачные API-запросы
└─ val pushStatusRequestFailed: SDKEvent // failed request: push/status

Внутренние события Core (ошибки состояния, парсинга JWT, отсутствия сети и т.п.) в перечислении есть, но в публичном API не документируются.

class AltcraftConfiguration

com.altcraft.sdk.config
└─ class AltcraftConfiguration private constructor(...)
   // Класс конфигурации Altcraft SDK: URL API, ресурсный токен, сведения о
   // приложении, флаг логов и конфигурации опциональных модулей.

   ├─ val apiUrl: String
   ├─ val rToken: String?
   ├─ val appInfo: AppInfo?
   └─ val enableLogging: Boolean?

   └─ class Builder(
        apiUrl: String,                    // Базовый URL Altcraft API (обязательный)
        rToken: String? = null,            // Ролевой токен (опционально)
        appInfo: AppInfo? = null,          // Сведения о приложении (опционально)
        enableLogging: Boolean? = null     // Включает/отключает ведение логов (опционально)
      )
      // Добавить конфигурацию опционального модуля (повторный вызов для того
      // же модуля заменяет предыдущую конфигурацию)
      ├─ fun addModuleConfiguration(configuration: ModuleConfiguration): Builder
      // Построить валидную конфигурацию
      └─ fun build(): AltcraftConfiguration

Push (опциональный модуль)

object Push

Push
// Доступ к API push-токенов
├─ val token: TokenAPI
// Доступ к событиям push (доставка, открытие)
├─ val pushEvents: EventAPI
// Типы событий Push-модуля
├─ val moduleEvents: ModuleEvents
// Доступ к приёму входящих push-уведомлений
├─ val receiver: PushReceiverApi
// Доступ к подпискам на push-уведомления
├─ val subscription: SubscriptionAPI
// Запрос разрешения на отправку уведомлений (Android 13+)
└─ fun requestNotificationPermission(context: Context, activity: ComponentActivity): Unit

object PushReceiverApi

PushReceiverApi
// Проверить, принадлежит ли push-уведомление Altcraft
├─ fun isAltcraftPush(message: Map<String, String>): Boolean
// Передать входящее push-уведомление в SDK
└─ fun takePush(context: Context, message: Map<String, String>): Unit

open class PushReceiver

PushReceiver
// Обработка входящего push-уведомления.
// Переопределяется для кастомного показа уведомления. SDK ищет реализации
// рефлексией в пакетах, указанных в PushConfiguration.pushReceiverModules;
// при отсутствии находит стандартную реализацию и вызывает pushHandler.
└─ open suspend fun pushHandler(context: Context, message: Map<String, String>): Unit

object TokenAPI

TokenAPI
// Зарегистрировать провайдера FCM (null — снять)
├─ fun setFCMTokenProvider(provider: FCMInterface?): Unit
// Зарегистрировать провайдера HMS (null — снять)
├─ fun setHMSTokenProvider(provider: HMSInterface?): Unit
// Зарегистрировать провайдера RuStore (null — снять)
├─ fun setRuStoreTokenProvider(provider: RustoreInterface?): Unit
// Получить текущий токен устройства
├─ suspend fun getToken(context: Context): TokenData?
// Удалить токен у выбранного провайдера
├─ suspend fun deleteToken(context: Context, provider: String): Unit
// Форс-обновление токена (удалить → обновить)
├─ suspend fun forcedTokenUpdate(context: Context): Unit
// Сохранить токен провайдера вручную
├─ suspend fun setToken(context: Context, provider: String?, token: String?): Unit
// Изменить приоритет провайдеров и обновить токен
└─ suspend fun changeProviderPriority(context: Context, priority: List<String>): Unit

object EventAPI

EventAPI
// Зафиксировать доставку Altcraft-push (вызывает delivery-ивент)
├─ suspend fun deliveryEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit
// Зафиксировать открытие Altcraft-push (вызывает open-ивент)
└─ suspend fun openEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit

object SubscriptionAPI

SubscriptionAPI
// Статусы push-подписки
├─ val status: StatusAPI
// Подписка на push-уведомление (status = SUBSCRIBED)
├─ fun subscribe(context: Context, sync: Boolean = true, profileFields: Map<String, Any?>? = null, customFields: Map<String, Any?>? = null, cats: List<CategoryData>? = null, replace: Boolean? = null, skipTriggers: Boolean? = null): Unit
// Приостановка подписки на push-уведомления (status = SUSPENDED)
├─ fun suspend(context: Context, sync: Boolean = true, profileFields: Map<String, Any?>? = null, customFields: Map<String, Any?>? = null, cats: List<CategoryData>? = null, replace: Boolean? = null, skipTriggers: Boolean? = null): Unit
// Отписка от push-уведомлений (status = UNSUBSCRIBED)
├─ fun unsubscribe(context: Context, sync: Boolean = true, profileFields: Map<String, Any?>? = null, customFields: Map<String, Any?>? = null, cats: List<CategoryData>? = null, replace: Boolean? = null, skipTriggers: Boolean? = null): Unit
// Смена статуса подписки указанной в JWT с suspended на subscribed, остальные
// подписки, содержащие указанный push-токен, сменят статус с subscribed на suspended
├─ suspend fun unSuspend(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
// Добавить функциональное поле профиля (set/incr/...)
└─ fun actionField(key: String): ActionFieldBuilder

object StatusAPI

StatusAPI
// Статус последней подписки профиля
├─ suspend fun latest(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
// Статус подписки с текущим токеном устройства
├─ suspend fun current(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
// Статус последней подписки профиля по указанному провайдеру push-уведомлений
└─ suspend fun latestForProvider(context: Context, provider: String? = null): ResponseWithHttpCode<ResponseWithProfile>?

Конфигурация Push-модуля

com.altcraft.sdk.push.config
// Настройки push-модуля передаются в Builder напрямую:
└─ fun AltcraftConfiguration.Builder.pushConfig(
     icon: Int? = null,                        // ID ресурса иконки уведомлений (опционально)
     providerPriority: List<String> = emptyList(), // Приоритет провайдеров push-уведомлений (опционально)
     pushReceiverModules: List<String> = emptyList(), // Пакеты, где может быть переопределён PushReceiver (опционально)
     pushChannelName: String? = null,          // Имя канала push-уведомлений (опционально)
     pushChannelDescription: String? = null    // Описание канала push-уведомлений (опционально)
   ): AltcraftConfiguration.Builder

Target (опциональный модуль)

object Target

Target
// Типы событий Target-модуля
├─ val moduleEvents: ModuleEvents
// Отправить цель (target-событие) на сервер
└─ fun sendTarget(
       context: Context,
       sid: String,
       eventName: String,
       sendMessageId: String? = null,
       payload: Map<String, Any?>? = null,
       matching: Map<String, Any?>? = null,
       matchingType: String? = null,
       profileFields: Map<String, Any?>? = null,
       subscription: Subscription? = null,
       utm: UTM? = null
     ): Unit

Profile (опциональный модуль)

object Profile

Profile
// Типы событий Profile-модуля
├─ val moduleEvents: ModuleEvents
// Обновить поля профиля
└─ fun updateProfileFields(context: Context, profileFields: Map<String, Any?>? = null, skipTriggers: Boolean? = null): Unit

In-App (опциональный модуль)

object InApp

InApp
// Управление подписками на In-App уведомления
├─ val subscription: SubscriptionAPI
// Подписка на In-App кампании с JSON-содержимым для внешней отрисовки
├─ val jsonContent: JsonContentAPI
// Типы событий In-App-модуля
├─ val moduleEvents: ModuleEvents
// Настроить анимацию In-App уведомления
├─ fun animation(block: Animator.() -> Unit): Unit
// Установить маркер текущего экрана (используется при фильтрации In-App кампаний)
├─ fun setScreen(context: Context, screen: String): Unit
// Триггер кастомной In-App кампании по имени
├─ fun trigger(context: Context, name: String): Unit
// Запрос доступных In-App placements
└─ fun getPlacements(context: Context): Unit

object SubscriptionAPI (In-App)

SubscriptionAPI
// Подписка на In-App уведомления (status = SUBSCRIBED)
├─ fun subscribe(context: Context, sync: Boolean = true, profileFields: Map<String, Any?>? = null, customFields: Map<String, Any?>? = null, cats: List<CategoryData>? = null, replace: Boolean? = null, skipTriggers: Boolean? = null): Unit
// Отписка от In-App уведомлений (status = UNSUBSCRIBED)
├─ fun unSubscribe(context: Context, sync: Boolean = true, profileFields: Map<String, Any?>? = null, customFields: Map<String, Any?>? = null, cats: List<CategoryData>? = null, replace: Boolean? = null, skipTriggers: Boolean? = null): Unit
// Статус подписки на In-App уведомления
└─ suspend fun getSubscriptionStatus(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

object JsonContentAPI

JsonContentAPI
// Подписаться на JSON In-App кампаний (заменяет существующего подписчика)
├─ fun subscribe(newSubscriber: (String) -> Unit): Unit
// Отписаться от JSON In-App кампаний
└─ fun unsubscribe(): Unit

interface Animator

Animator
// Идентификатор размещения, к которому относится аниматор
├─ val companyId: Int
// Применить блок к In-App view мгновенно, без запуска анимации
├─ fun prepare(block: View.() -> Unit): Unit
// Настроить и запустить property-анимацию для In-App view
└─ fun animate(block: ViewPropertyAnimator.() -> Unit): Unit

Конфигурация In-App модуля

com.altcraft.sdk.inapp.config
// Настройки In-App модуля передаются в Builder напрямую:
└─ fun AltcraftConfiguration.Builder.inAppConfig(
     inAppAutoRequest: Boolean = true,        // Автоматический запрос In-App placements (опционально)
     placementsRequestInterval: Duration = 30 минут, // Интервал автоматических запросов (опционально)
     maxPlacements: Int = 500                 // Максимум placements в локальном хранилище (опционально)
   ): AltcraftConfiguration.Builder

Модели данных

Event Classes

Event
// Базовое событие SDK (универсальная телеметрия)
function: String
event: SDKEvent?
eventMessage: String?
eventValue: Map<String, Any?>?
date: Date
internal: Boolean


Error
// Ошибка SDK, наследует Event
function: String
event: SDKEvent?
eventMessage: String?
eventValue: Map<String, Any?>?
date: Date


RetryError
// Ошибка запроса, для которого предусмотрен автоматический повтор и выполнение
function: String
event: SDKEvent?
eventMessage: String?
eventValue: Map<String, Any?>?
date: Date

Data Classes (Core)

// Опциональные данные для Firebase Analytics (если используется)
data class AppInfo(
    appID: String = "",
    appIID: String = "",
    appVer: String = ""
)


// Обёртка ответа API вместе с HTTP-кодом
data class ResponseWithHttpCode<T : ResponseData>(
    httpCode: Int?,
    response: T?
)


// Ответ запроса (реализация BaseResponseData)
data class ResponseWithProfile(
    error: Int? = null,
    @SerialName("error_text") errorText: String? = null,
    profile: ProfileData? = null
)


// Данные профиля пользователя
data class ProfileData(
    id: String? = null,
    status: String? = null,
    acid: String? = null,
    @SerialName("is_test") isTest: Boolean? = null,
    subscription: SubscriptionData? = null
)


// Текущая подписка профиля
data class SubscriptionData(
    @SerialName("subscription_id") subscriptionId: String? = null,
    @SerialName("hash_id") hashId: String? = null,
    provider: String? = null,
    status: String? = null,
    fields: Map<String, JsonElement>? = null,
    cats: List<CategoryData>? = null
)


// Категория подписки (имя, заголовок, флаги)
data class CategoryData(
    name: String?,
    title: String? = null,
    steady: Boolean? = null,
    active: Boolean?
)

Data Classes (Push)

// Токен push-провайдера устройства
data class TokenData(
    provider: String,
    token: String
)

Data Classes (Target)

com.altcraft.sdk.target.data.models.TargetModels

// Контейнер UTM-параметров для атрибуции целей (все поля опциональны)
data class UTM(
    campaign: String? = null,
    content: String? = null,
    keyword: String? = null,
    medium: String? = null,
    source: String? = null,
    temp: String? = null
)


object SubscriptionModel {
    // Базовый интерфейс всех типов подписок, добавляемых целью
    sealed interface Subscription {
        @SerialName("resource_id")
        val resourceId: Int
        val status: String?
        val priority: Int?
        @SerialName("custom_fields")
        val customFields: Map<String, @Contextual Any?>?
        val cats: List<String>?
        val channel: String
    }

    // Подписка на канал Email
    data class EmailSubscription(
        @SerialName("resource_id") override val resourceId: Int,
        val email: String,
        override val status: String? = null,
        override val priority: Int? = null,
        @SerialName("custom_fields") override val customFields: Map<String, @Contextual Any?>? = null,
        override val cats: List<String>? = null,
    ) : Subscription {
        @SerialName("channel")
        override val channel: String = "email"
    }

    // Подписка на канал SMS
    data class SmsSubscription(
        @SerialName("resource_id") override val resourceId: Int,
        val phone: String,
        override val status: String? = null,
        override val priority: Int? = null,
        @SerialName("custom_fields") override val customFields: Map<String, @Contextual Any?>? = null,
        override val cats: List<String>? = null,
    ) : Subscription {
        @SerialName("channel")
        override val channel: String = "sms"
    }

    // Подписка на push-канал
    data class PushSubscription(
        @SerialName("resource_id") override val resourceId: Int,
        val provider: String,
        @SerialName("subscription_id") val subscriptionId: String,
        override val status: String? = null,
        override val priority: Int? = null,
        @SerialName("custom_fields") override val customFields: Map<String, @Contextual Any?>? = null,
        override val cats: List<String>? = null,
    ) : Subscription {
        @SerialName("channel")
        override val channel: String = "push"
    }

    // Подписка с cc_data (Telegram, WhatsApp, Viber, Notify)
    data class CcDataSubscription(
        @SerialName("resource_id") override val resourceId: Int,
        @SerialName("channel") override val channel: String,
        @SerialName("cc_data") val ccData: JsonObject,
        override val status: String? = null,
        override val priority: Int? = null,
        @SerialName("custom_fields") override val customFields: Map<String, @Contextual Any?>? = null,
        override val cats: List<String>? = null,
    ) : Subscription
}

Constants

com.altcraft.sdk.push.data
└─ object Constants
   // Провайдеры push-уведомлений
   ├─ const val FCM_PROVIDER: String = "android-firebase"
   ├─ const val HMS_PROVIDER: String = "android-huawei"
   └─ const val RUS_PROVIDER: String = "android-rustore"

Interfaces

JWTInterface (Core):

JWTInterface
// Доступ к текущему JWT
└─ fun getJWT(): String?
   // Возвращает JWT или null

FCMInterface (Push):

FCMInterface
// Контракт операций с FCM-токеном
├─ suspend fun getToken(): String?
│  // Возвращает токен FCM или null
└─ fun deleteToken(completion: (Boolean) -> Unit)
   // Удаляет токен FCM

HMSInterface (Push):

HMSInterface
// Контракт операций с HMS-токеном
├─ suspend fun getToken(context: Context): String?
│  // Возвращает токен HMS или null
└─ fun deleteToken(context: Context, complete: (Boolean) -> Unit)
   // Удаляет токен HMS

RuStoreInterface (Push):

RustoreInterface
// Контракт операций с RuStore-токеном
├─ suspend fun getToken(): String?
│  // Возвращает токен RuStore или null
└─ fun deleteToken(complete: (Boolean) -> Unit)
   // Удаляет токен RuStore

Subscription (Target):

Subscription (sealed interface)
// Базовый контракт модели подписки для всех каналов
├─ val resourceId: Int
│  // Обязательный ID ресурса Altcraft (JSON: "resource_id")
├─ val status: String?
│  // Необязательный статус подписки
├─ val priority: Int?
│  // Необязательный приоритет
├─ val customFields: Map<String, @Contextual Any?>?
│  // Необязательные стандартные и кастомные поля (JSON: "custom_fields")
├─ val cats: List<String>?
│  // Необязательные категории подписки
└─ val channel: String
   // Обязательный тип канала (например, "email", "sms", "push", "telegram_bot", ...)