Функционал SDK

подсказка

Предварительно вам необходимо настроить SDK для работы с вашим приложением. Подробная инструкция находится здесь

SDK разделён на модули: core (авторизация, события), push, target (цели), profile и in-app. Каждый модуль подключается отдельной зависимостью и доступен через свой объект — AltcraftSDK.auth, AltcraftSDK.push, AltcraftSDK.target, AltcraftSDK.profile, AltcraftSDK.inApp.

Core: авторизация

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

Функции авторизации:

fun setJWTProvider() — устанавливает реализацию JWTInterface, через которую SDK получает JWT-токены. Чтобы снять провайдера, передайте null. Для работы без JWT используйте rToken из конфигурации.
fun authenticate() — аутентифицирует текущего пользователя: отправляет на сервер запрос с JWT-токеном и привязывает устройство к профилю пользователя. Метод работает только при JWT-авторизации — матчинг профиля передаётся в полезной нагрузке JWT, поэтому при авторизации ролевым токеном аутентификация недоступна. После успешной аутентификации пользователь получает доступ к персонализированным In-App уведомлениям.
fun logOut() — завершает текущую сессию аутентификации и переводит устройство в анонимный режим. В анонимном режиме недоступны персонализированные In-App уведомления и управление подпиской.
suspend fun isAuthenticated() — возвращает true, если текущий пользователь SDK авторизован, и false в противном случае.

Важно

Вызывайте authenticate() только тогда, когда пользователь действительно выполняет вход в приложение и известен для клиента (например, после успешной авторизации через форму логина, OAuth или другой механизм аутентификации вашего приложения). С logOut() — аналогично: только при реальном выходе пользователя.

Пример установки JWT-провайдера:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AltcraftSDK.auth.setJWTProvider(JWTProvider(applicationContext))
        // инициализация SDK
    }
}

Пример проверки статуса авторизации:

CoroutineScope(Dispatchers.IO).launch {
    val authenticated = AltcraftSDK.auth.isAuthenticated(context)
}

Очистка данных SDK

AltcraftSDK
// Полная очистка данных SDK (БД, SharedPreferences, фоновые задачи)
└── fun clear(
        context: Context,
        onComplete: (() -> Unit)? = null
    ): Unit

Функция выполняет полную очистку данных SDK: отменяет ожидающие фоновые задачи WorkManager, удаляет записи БД Room и очищает SharedPreferences. Необязательный параметр onComplete вызывается после завершения очистки.

Сброс запрета на retry-операции при инициализации SDK

Обратите внимание

При инициализации SDK выполняется запуск фоновых задач, выполняющих контроль и повторную отправку запросов, связанных с push-уведомлениями, целями, а также проверку и выполнение запроса на обновление push-токена устройства. Выполнение данной функции ограничено одним запуском в пределах одного жизненного цикла процесса приложения. Иногда может возникнуть необходимость сброса этого ограничения.

AltcraftSDK
// Разрешить переинициализацию фоновых задач в текущей сессии
└── fun unlockInitialOperationsInThisSession(): Unit

Функция сбрасывает флаг запрета на повторный запуск фоновых задач контроля и повторной отправки запросов.

Core: события SDK

// API событий SDK

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

В приложении может быть только один активный подписчик на события SDK.

Типы событий SDK:

Event — общее событие (информация, успешные запросы);
Error — событие об ошибке;
RetryError — событие об ошибке при выполнении запроса, для которого предусмотрен автоматический повтор на стороне SDK.

Каждое событие содержит поля:

function — имя функции, вызвавшей событие;
event — тип события SDK (SDKEvent, список см. в таблице ниже);
eventMessage — сообщение события;
eventValue — дополнительные данные, добавляемые к некоторым событиям;
date — время события;
internal — флаг, указывающий, является ли событие внутренним.

Подписка на события

fun subscribe(newSubscriber: (Event) -> Unit): Unit

Функция подписывает приложение на события SDK. При возникновении события SDK она вызывает переданный newSubscriber и передаёт в него экземпляр Event (или его наследника).

Пример использования:

AltcraftSDK.sdkEvents.subscription.subscribe { event ->
    // Обработка события
}

Классы событий SDK

open class Event(
    val function: String,
    val event: SDKEvent? = null,
    val eventMessage: String? = null,
    val eventValue: Map<String, Any?>? = null,
    val date: Date = Date(),
    val internal: Boolean = false
)

open class Error(
    function: String,
    event: SDKEvent? = null,
    eventMessage: String? = null,
    eventValue: Map<String, Any?>? = null,
    date: Date = Date(),
) : Event(function, event, eventMessage, eventValue, date)

class RetryError(
    function: String,
    event: SDKEvent? = null,
    eventMessage: String? = null,
    eventValue: Map<String, Any?>? = null,
    date: Date = Date(),
) : Error(function, event, eventMessage, eventValue, date)

Отписка от событий

fun unsubscribe(): Unit

Отменяет доставку событий SDK. Подписчик остаётся назначенным, но события больше не передаются.

Пример использования:

AltcraftSDK.sdkEvents.subscription.unsubscribe()

Список всех событий SDK

Список событий по модулям

События SDK доступны через объекты модулей: AltcraftSDK.moduleEvents (core), AltcraftSDK.push.moduleEvents, AltcraftSDK.target.moduleEvents, AltcraftSDK.profile.moduleEvents, AltcraftSDK.inApp.moduleEvents. Каждый элемент — объект SDKEvent со строковым сообщением (message).

Core:

Значение	Сообщение
`configIsSet`	SDK configuration is installed
`sdkCleared`	SDK data has been cleared
`notAuthenticatedError`	User is not authenticated
`userLogOut`	User logged out. Anonymous session started.
`roomMigrationError`	Room database migration failed. The local SDK database will be recreated.
`authenticateSuccessful`	successful request: profile/authenticate
`pushStatusRequestFailed`	failed request: push/status

Push:

Значение	Сообщение
`invalidConfig`	Invalid push configuration: unsupported push provider. Available providers: android-firebase, android-huawei, android-rustore.
`configIsNull`	push configuration is null
`invalidCustomFields`	invalid custom fields: not all values are primitives
`eventRetryLimit`	push event retry limit
`eventRequestDataIsNull`	push event request data is null
`eventRequestSuccessful`	successful request: event/push
`eventRequestFailed`	failed request: event/push
`pushUidIsNull`	push uid is null
`subscribeRetryLimit`	push subscribe retry limit
`subscribeRequestDataIsNull`	push subscribe request data is null
`subscribeRequestSuccessful`	successful request: push/subscribe
`subscribeRequestFailed`	failed request: push/subscribe
`suspendRequestSuccessful`	successful request: push/suspend
`suspendRequestFailed`	failed request: push/suspend
`unsubscribeRequestSuccessful`	successful request: push/unsubscribe
`unsubscribeRequestFailed`	failed request: push/unsubscribe
`tokenUpdateRequestDataIsNull`	token update request data is null
`tokenUpdateRequestSuccessful`	successful request: push/update
`tokenUpdateRequestFailed`	failed request: push/update
`pushTokenIsNull`	push token is null
`notUpdated`	push token not updated
`pushProviderSet`	push provider set -
`invalidPushProvider`	Invalid push provider. Available providers: android-firebase, android-huawei, android-rustore.
`statusRequestDataIsNull`	subscription status request data is null
`statusRequestSuccess`	successful request: push/status
`statusRequestFailed`	failed request: push/status
`unSuspendRequestDataIsNull`	unsuspend request data is null
`unSuspendRequestSuccessful`	successful request: push/unsuspend
`unSuspendRequestFailed`	failed request: push/unsuspend
`pushDataIsNull`	push data is null
`notificationErr`	notification error
`channelNotCreated`	notification channel not created
`pushPermissionDenied`	notification permission denied
`pushIsPosted`	push notification is posted
`acPush`	Altcraft push notification received
`notAcPush`	received a notification unrelated to the Altcraft Platform
`receiverRedefined`	push receiver redefined
`errorImgLoad`	error loading push image
`successImgLoad`	push image loaded successfully

Target:

Значение	Сообщение
`partsIsNull`	target request parts is null
`retryLimit`	target request retry limit
`invalidPayload`	invalid target payload: not all values are primitives
`requestDataIsNull`	target request data is null
`requestSuccessful`	successful target request: event/post
`requestFailed`	failed target request: event/post

Profile:

Значение	Сообщение
`requestDataIsNull`	profile update request data is null
`retryLimit`	profile update retry limit
`requestSuccessful`	successful request: profile/update
`requestFailed`	failed request: profile/update

In-App:

Значение	Сообщение
`subscribeRetryLimit`	in-app subscribe retry limit
`subscribeRequestDataIsNull`	in-app subscribe request data is null
`subscribeRequestSuccessful`	successful request: inapp/subscribe
`subscribeRequestFailed`	failed request: inapp/subscribe
`unsubscribeRequestSuccessful`	successful request: inapp/unsubscribe
`unsubscribeRequestFailed`	failed request: inapp/unsubscribe
`invalidCustomFields`	invalid custom fields: not all values are primitives
`statusRequestDataIsNull`	in-app status request data is null
`statusRequestSuccessful`	successful request: inapp/status
`statusRequestFailed`	failed request: inapp/status
`eventRetryLimit`	in-app event retry limit
`eventRequestDataIsNull`	in-app event request data is null
`smidIsNull`	send message ID is null
`eventRequestSuccessful`	successful request: inapp/event
`eventRequestFailed`	failed request: inapp/event
`placementsRequestDataIsNull`	in-app placements request data is null
`placementsRequestSuccessful`	successful request: inapp/placements
`placementsRequestFailed`	failed request: inapp/placements
`maxPlacementsInvalid`	Invalid in-app configuration: maxPlacements must be >= 1
`requestIntervalInvalid`	Invalid in-app configuration: placementsRequestInterval must be > Duration.ZERO
`placementsLimitExceeded`	in-app placements limit exceeded
`invalidStaticField`	invalid in-app static field
`inAppStaticErrorLoad`	error loading in-app notification static resources
`inAppContentErrorLoad`	error loading in-app notification content

Push: работа со статусами подписки

Изменение статуса подписки

AltcraftSDK
└─ val push: Push
   └─ val subscription: SubscriptionAPI
      // Подписка (статус = 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
      // Приостановка (статус = 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
      // Отписка (статус = 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
      // Переключение подписок между профилями (LogIn/LogOut)
      ├─ suspend fun unSuspend(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
      // Построение функциональных операций над полями профиля
      └─ fun actionField(key: String): ActionFieldBuilder

Функции изменения статуса подписки:

fun subscribe() — выполняет подписку на push-уведомления;
fun unsubscribe() — отменяет подписку на push-уведомления;
fun suspend() — приостанавливает подписку на push-уведомления (уведомления не приходят, но при этом не создаётся событие отписки в профиле пользователя);
suspend fun unSuspend() — используется для создания LogIn-, LogOut-переходов;
fun actionField() — создаёт ActionFieldBuilder для построения функциональных операций (set, unset, incr, add, delete, upsert) над полями профиля внутри profileFields.

Функции изменения статуса имеют одинаковую сигнатуру, содержащую следующие параметры:

context: Context

Обязательный: Да
Описание: Android Context.

sync: Boolean

По умолчанию: true
Обязательный: Нет
Описание: Флаг, устанавливающий синхронность выполнения запроса.

Успешное выполнение запроса:

В случае успешного выполнения запроса данной группы функций будет создано событие, содержащее в event.value данные ответа:

Если sync == true

ResponseWithProfile
  ├─ error: 0
  ├─ errorText: ""
  └─ profile
     ├─ id: "your id"
     ├─ status: "subscribed"
     ├─ isTest: false
     └─ subscription
        ├─ subscriptionId: "your subscriptionId"
        ├─ hashId: "7f31a9c4"
        ├─ provider: "android-firebase"
        ├─ status: "subscribed"
        ├─ fields
        │  ├─ _os_ver: {"raw":"14","ver":"[\"14.0\", \"0.0\", \"0.0\"]"}
        │  ├─ _device_type: "mob"
        │  ├─ _ad_track: true
        │  ├─ _device_name: "Pixel"
        │  ├─ _os_language: "en"
        │  ├─ _os_tz: "+0100"
        │  ├─ _os: "Android"
        │  ├─ _device_model: "Pixel 7"
        │  └─ _app_ver: "1.0.0"
        └─ cats
           └─ [ { name: "developer_news", title: "dev_news", steady: false, active: false } ]

При синхронном запросе в значении события event.value доступны:

error – внутренний код ошибки сервера (0, если ошибок нет);
errorText – текст ошибки (пустая строка, если ошибок нет);
profile – данные профиля, если запрос успешный:
- информация о профиле (ProfileData)
- подписка (SubscriptionData)
- категории подписки (CategoryData)
- если запрос завершился с ошибкой, то вернётся только profile = null

Структуры данных

data class ResponseWithProfile(
    val error: Int?,
    val errorText: String?,
    val profile: ProfileData?
)

data class ProfileData(
    val id: String?,
    val status: String?,
    val acid: String? = null,
    val isTest: Boolean?,
    val subscription: SubscriptionData?
)

data class SubscriptionData(
    val subscriptionId: String?,
    val hashId: String?,
    val provider: String?,
    val status: String?,
    val fields: Map<String, JsonElement>?,
    val cats: List<CategoryData>?
)

data class CategoryData(
    val name: String?,
    val title: String?,
    val steady: Boolean?,
    val active: Boolean?
)

Если sync == false

ResponseWithProfile
  ├─ error: Int?
  ├─ errorText: String?
  └─ profile: ProfileData? = null

При асинхронном запросе profile в значении события event.value всегда равен null.

Выполнение запроса с ошибкой:

Если запрос данной группы функций завершился ошибкой, будет создано событие с кодом ошибки:

subscribeRequestFailed — подписка на уведомления;
suspendRequestFailed — приостановка подписки;
unsubscribeRequestFailed — отписка.

Содержимое события:

только httpCode, если сервер Altcraft был недоступен;
error и errorText, если сервер вернул ошибку.

Получение значений событий

AltcraftSDK.sdkEvents.subscription.subscribe { event ->
    val sdkEvent = event.event ?: return@subscribe

    if (sdkEvent == AltcraftSDK.push.moduleEvents.subscribeRequestSuccessful ||
        sdkEvent == AltcraftSDK.push.moduleEvents.subscribeRequestFailed
    ) {
        val value = event.eventValue
        val error = value?.get("error")
        val errorText = value?.get("errorText")
        val profile = value?.get("profile") as? ProfileData
        val subscription = profile?.subscription
    }
}

profileFields:Map<String, Any?>?

По умолчанию: null
Обязательный: Нет
Описание: Словарь, содержащий поля профиля.

Параметр может принимать как системные поля (например, _fname — имя или _lname — фамилия), так и опциональные (заранее создаются вручную в интерфейсе платформы). Допустимые структуры (JSON-совместимые):

Скалярные значения:
- String
- Boolean
- Int
- Long
- Float
- Double
- null
Объекты: Map<String, *>
Списки: List<*>
Массивы карт: Array<Map<String, *>>

Если передано невалидное опциональное поле, запрос завершится с ошибкой:

http code: 400
error: 400
errorText: Platform profile processing error: with field "название_поля": Incorrect field

Для функциональных операций над полями профиля используйте actionField():

AltcraftSDK.push.subscription.subscribe(
    context = context,
    profileFields = mapOf(
        AltcraftSDK.push.subscription.actionField("orders_count").incr(1)
    )
)

customFields:Map<String, Any?>?

По умолчанию: null
Обязательный: Нет
Описание: Словарь, содержащий поля подписки.

Параметр может принимать как системные поля (например, _device_model — модель устройства или _os — операционная система), так и опциональные (заранее создаются вручную в интерфейсе платформы). Допустимые типы значений (JSON-совместимые, только скаляры):

String
Boolean
Int
Long
Float
Double
null

Если передано невалидное опциональное поле, запрос завершится с ошибкой:

http code: 400
error: 400
errorText: Platform profile processing error: field "название_поля" is not valid: failed convert custom field

Обратите внимание

Большая часть системных полей подписки автоматически собирается SDK и добавляется к push-запросам. К таким системным полям относятся: "_os", "_os_tz", "_os_language", "_device_type", "_device_model", "_device_name", "_os_ver", "_ad_track", "_ad_id".

cats:List<CategoryData>?

По умолчанию: null
Обязательный: Нет
Описание: Категории подписок.

Структура категории:

data class CategoryData(
    val name: String?,
    val title: String? = null,
    val steady: Boolean? = null,
    val active: Boolean?
)

При отправке push-запроса с указанием категорий используйте только поля name (название категории) и active (статус активности категории), другие поля не используются в обработке запроса. Поля title и steady заполняются при получении информации о подписке.

Пример запроса:

val cats = listOf(
    CategoryData(name = "football", active = true),
    CategoryData(name = "hockey",   active = true)
)

Категории, используемые в запросе, должны быть предварительно созданы и добавлены к ресурсу в платформе Altcraft. Если в запросе будет использована категория, которая не добавлена в ресурс, — запрос вернётся с ошибкой:

http code: 400
error: 400
errorText: Platform profile processing error: field "subscriptions.cats" is not valid: category not found in resource

replace:Boolean?

По умолчанию: null
Обязательный: Нет
Описание: При активации флага все подписки других профилей с тем же push-токеном в текущей базе данных переводятся в статус unsubscribed после успешного запроса.

skipTriggers:Boolean?

По умолчанию: null
Обязательный: Нет
Описание: При активации флага профиль, содержащий данную подписку, будет игнорироваться в триггерах рассылок и сценариев.

Примеры реализации запроса

Пример выполнения запроса подписки на push-уведомления

Минимальная рабочая настройка:

AltcraftSDK.push.subscription.subscribe(context)

Передача всех доступных параметров:

AltcraftSDK.push.subscription.subscribe(
    context = this,
    sync = true,
    profileFields = mapOf("_fname" to "Andrey", "_lname" to "Pogodin"),
    customFields  = mapOf("developer" to true),
    cats = listOf(CategoryData(name = "developer_news", active = true)),
    replace = false,
    skipTriggers = false
)

Обратите внимание

Для subscribe, suspend и unsubscribe предусмотрен автоматический повтор запроса со стороны SDK, если http-код ответа находится в диапазоне 500..599. Запрос не повторяется, если код ответа в этот диапазон не входит.

Функция unSuspend()

Функция suspend fun unSuspend() предназначена для создания LogIn-, LogOut-переходов. Она работает следующим образом:

проводит поиск подписок с тем же push-токеном, что и текущий, не относящихся к профилю, на который указывает текущий JWT-токен;
меняет статус найденных подписок с subscribed на suspended;
меняет статус в подписках профиля, на который указывает текущий JWT, с suspended на subscribed (если профиль, на который указывает JWT, существует и в нём содержатся подписки);
возвращает ResponseWithHttpCode<ResponseWithProfile>?, в котором response.profile — текущий профиль, на который указывает JWT (если профиля не существует, вернётся null).

Рекомендуемая реализация LogIn-, LogOut-переходов

LogIn-переход:

Анонимный пользователь входит в приложение. Данному пользователю присвоен JWT_1, указывающий на базу данных #1Anonymous;
Выполнена подписка на push-уведомления, профиль создан в базе данных #1Anonymous;
Пользователь регистрируется, ему присваивается JWT_2, указывающий на базу данных #2Registered;
Вызывается функция unSuspend() — подписка анонимного пользователя в базе данных #1Anonymous приостанавливается;
Выполняется поиск профиля в базе данных #2Registered для восстановления подписки;
Так как подписки с таким push-токеном в базе данных #2Registered не существует, функция unSuspend() вернёт профиль без подписки;
После этого можно выполнить запрос на подписку subscribe(), который создаст новый профиль в базе #2Registered.

LogOut-переход:

Пользователь выполнил выход из профиля на стороне приложения (LogOut);
Пользователю присваивается JWT_1, указывающий на базу данных #1Anonymous;
Вызывается функция unSuspend(), которая приостановит подписку в базе данных #2Registered и сменит статус подписки в базе #1Anonymous на subscribed;
Запрос вернёт непустой профиль — подписка уже существует, новая не требуется.

Пример реализации:

private suspend fun unSuspend(context: Context) {
    AltcraftSDK.push.subscription
        .unSuspend(context)
        ?.let { result ->
            if (result.httpCode == 200 && result.response?.profile?.subscription == null) {
                AltcraftSDK.push.subscription.subscribe(
                    context = context
                    // Укажите необходимые параметры
                )
            }
        }
}

fun logIn(context: Context)  = CoroutineScope(Dispatchers.IO).launch { unSuspend(context) }
fun logOut(context: Context) = CoroutineScope(Dispatchers.IO).launch { unSuspend(context) }

Запрос статуса подписки

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

Функции запроса статуса подписки:

suspend fun status.latest() — статус последней подписки профиля;
suspend fun status.current() — статус подписки для текущего push-токена и провайдера;
suspend fun status.latestForProvider() — статус последней подписки по указанному провайдеру. Если провайдер не указан (provider = null), используется провайдер текущего push-токена.

suspend fun status.latest(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

Функция получения статуса последней подписки профиля. Возвращает объект ResponseWithHttpCode<ResponseWithProfile>, содержащий response?.profile?.subscription — последнюю созданную подписку в профиле. Если такой подписки не существует, будет передан null.

Пример использования:

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.subscription.status.latest(context)
}

suspend fun status.current(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

Функция получения статуса подписки для текущего push-токена и провайдера. Возвращает объект ResponseWithHttpCode<ResponseWithProfile>, содержащий response?.profile?.subscription — подписку, найденную по текущему push-токену и провайдеру. Если такой подписки не существует, будет передан null.

Пример использования:

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.subscription.status.current(context)
}

suspend fun status.latestForProvider(context: Context, provider: String? = null): ResponseWithHttpCode<ResponseWithProfile>?

Функция получения статуса последней подписки по провайдеру. Возвращает объект ResponseWithHttpCode<ResponseWithProfile>, содержащий response?.profile?.subscription — последнюю созданную подписку с указанным провайдером push-уведомлений. Если провайдер не указан (provider = null), используется провайдер текущего push-токена. Если такой подписки не существует, будет передан null.

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.subscription.status.latestForProvider(context, provider = null)
}

Ниже представлен пример извлечения данных о профиле, подписке и категориях из ответа функций получения статуса. Данный подход актуален для всех функций получения статуса:

Данные из функций получения статуса

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.subscription
        .status.current(context)
        ?.let { it ->
            val httpCode = it.httpCode
            val response = it.response
            val error = response?.error
            val errorText = response?.errorText
            val profile = response?.profile
            val subscription = profile?.subscription
            val cats = subscription?.cats
        }
}

Push: управление push-токенами

AltcraftSDK
└── val push: Push
    │
    // Сохранить токен вручную (onNewToken)
    ├── suspend fun token.setToken(context: Context, provider: String?, token: String?): Unit
    │
    // Получить текущие данные токена устройства
    ├── suspend fun token.getToken(context: Context): TokenData?
    │
    // Установить провайдер Firebase Cloud Messaging (null — удалить)
    ├── fun token.setFCMTokenProvider(provider: FCMInterface?): Unit
    │
    // Установить провайдер Huawei Mobile Services (null — удалить)
    ├── fun token.setHMSTokenProvider(provider: HMSInterface?): Unit
    │
    // Установить провайдер RuStore (null — удалить)
    ├── fun token.setRuStoreTokenProvider(provider: RustoreInterface?): Unit
    │
    // Удалить токен push указанного провайдера
    ├── suspend fun token.deleteToken(context: Context, provider: String): Unit
    │
    // Принудительное обновление токена (удалить —> обновить)
    ├── suspend fun token.forcedTokenUpdate(context: Context): Unit
    │
    // Изменить список приоритетов провайдеров и инициировать обновление токена
    ├── suspend fun token.changeProviderPriority(context: Context, priority: List<String>): Unit
    │
    // Запросить у пользователя разрешение на уведомления
    └── fun requestNotificationPermission(context: Context, activity: ComponentActivity): Unit

Функции для работы с токеном провайдера в SDK:

suspend fun token.setToken() — ручная установка push-токена устройства и провайдера в локальном хранилище;
suspend fun token.getToken() — получение текущего push-токена;
fun token.setFCMTokenProvider() — установка и снятие провайдера Firebase Cloud Messaging;
fun token.setHMSTokenProvider() — установка и снятие провайдера Huawei Mobile Services;
fun token.setRuStoreTokenProvider() — установка и снятие провайдера RuStore;
suspend fun token.changeProviderPriority() — динамическая смена порядка провайдеров с обновлением push-токена подписки;
suspend fun token.deleteToken() — удаление push-токена указанного провайдера;
suspend fun token.forcedTokenUpdate() — удаление текущего push-токена с последующим обновлением;
fun requestNotificationPermission() — запрос у пользователя разрешения на отправку уведомлений (Android 13+).

suspend fun token.setToken(context: Context, provider: String?, token: String?): Unit

Функция предназначена для ручной установки push-токена устройства и провайдера. Должна выполняться в функции onNewToken() сервиса push-провайдера. Используется как упрощённый вариант передачи токена в SDK без реализации интерфейсов провайдеров.

Не рекомендуется использовать эту функцию для передачи токена. Рекомендуемый подход передачи push-токена в SDK — реализация FCMInterface, HMSInterface или RustoreInterface.

Пример использования:

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.token.setToken(context, provider, token)
}

Пример передачи токена в FCMService.onNewToken():

class FCMService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        super.onNewToken(token)
        
        // Передать новый токен вручную
        CoroutineScope(Dispatchers.IO).launch {
            AltcraftSDK.push.token.setToken(this@FCMService, FCM_PROVIDER, token)
        }
    }

    override fun onDeletedMessages() {}
    
    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)
        AltcraftSDK.push.receiver.takePush(this@FCMService, message.data)
    }
}

suspend fun token.getToken(context: Context): TokenData?

Функция возвращает текущие данные push-токена устройства и провайдера в виде data class TokenData(val provider: String, val token: String). Если токен недоступен — будет передано null.

Пример использования:

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.token.getToken(context).let {
        val provider = it?.provider
        val token = it?.token
    }
}

fun token.setFCMTokenProvider(provider: FCMInterface?): Unit

Функция устанавливает или снимает провайдера токенов Firebase Cloud Messaging. Чтобы отключить провайдера, передайте null.

Пример использования:

AltcraftSDK.push.token.setFCMTokenProvider(FCMProvider())

Важно

Вызывайте token.setFCMTokenProvider() в Application.onCreate() до вызова AltcraftSDK.initialization(). Это гарантирует регистрацию провайдера на старте процесса приложения, независимо от состояния жизненного цикла других компонентов и того, запущено приложение в foreground или background.

fun token.setHMSTokenProvider(provider: HMSInterface?): Unit

Функция устанавливает или снимает провайдера токенов Huawei Mobile Services. Чтобы отключить провайдера, передайте null.

Пример использования:

AltcraftSDK.push.token.setHMSTokenProvider(HMSProvider())

Важно

Вызывайте token.setHMSTokenProvider() в Application.onCreate() до вызова AltcraftSDK.initialization(). Это гарантирует регистрацию провайдера на старте процесса приложения, независимо от состояния жизненного цикла других компонентов и того, запущено приложение в foreground или background.

fun token.setRuStoreTokenProvider(provider: RustoreInterface?): Unit

Функция устанавливает или снимает провайдера токенов RuStore. Чтобы отключить провайдера, передайте null.

Пример использования:

AltcraftSDK.push.token.setRuStoreTokenProvider(RuStoreProvider())

Важно

Вызывайте token.setRuStoreTokenProvider() в Application.onCreate() до вызова AltcraftSDK.initialization(). Это гарантирует регистрацию провайдера на старте процесса приложения, независимо от состояния жизненного цикла других компонентов и того, запущено приложение в foreground или background.

suspend fun token.changeProviderPriority(context: Context, priority: List<String>): Unit

Функция, позволяющая выполнить динамическую смену push-провайдера с обновлением токена подписки. Для этого необходимо передать новый список с другим порядком провайдеров. Например: listOf(HMS_PROVIDER, RUSTORE_PROVIDER, FCM_PROVIDER).

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.token.changeProviderPriority(
        context,
        listOf(HMS_PROVIDER, RUSTORE_PROVIDER, FCM_PROVIDER)
    )
}

suspend fun token.deleteToken(context: Context, provider: String): Unit

Функция удаления push-токена указанного провайдера. Токен инвалидируется и удаляется из локального кеша на устройстве и с сервера push-провайдера. После удаления можно запросить новый токен.

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.token.deleteToken(context, provider)
}

suspend fun token.forcedTokenUpdate(context: Context): Unit

Функция удаления текущего push-токена с его последующим обновлением.

Пример использования:

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.token.forcedTokenUpdate(context)
}

fun requestNotificationPermission(context: Context, activity: ComponentActivity): Unit

Функция запрашивает у пользователя разрешение на отправку уведомлений. Требует ComponentActivity, через которое выводится системный диалог разрешения.

AltcraftSDK.push.requestNotificationPermission(this, activity)

Пример регистрации провайдеров

Мы не рекомендуем использовать функцию token.setToken для установки push-токена. Вместо этого настройте функции получения токена для каждого используемого провайдера. Ниже указан пример реализации этого метода:

Рекомендуемый способ регистрации провайдеров

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // установить провайдера JWT
        AltcraftSDK.auth.setJWTProvider(JWTProvider(applicationContext))
        
        // установить провайдер FCM
        AltcraftSDK.push.token.setFCMTokenProvider(FCMProvider())
        
        // установить провайдер HMS
        AltcraftSDK.push.token.setHMSTokenProvider(HMSProvider())
        
        // установить провайдер RuStore
        AltcraftSDK.push.token.setRuStoreTokenProvider(RuStoreProvider())
        
        // создать AltcraftConfiguration
        val config = AltcraftConfiguration.Builder(
            apiUrl = "your api url",
            rToken = "your r token",
            appInfo = AppInfo("app id", "app iid", "1.0.0"),
            enableLogging = false
        ).build()
        
        // Инициализация SDK
        AltcraftSDK.initialization(context = this@App, configuration = config)
    }
}

Push: передача push-уведомлений в SDK

AltcraftSDK
└── val push: Push
    └── val receiver: PushReceiverApi
        // Проверка, принадлежит ли уведомление Altcraft
        ├── fun isAltcraftPush(
        │       message: Map<String, String>
        │   ): Boolean
        // Точка входа в SDK для доставки push
        └── fun takePush(
                context: Context, 
                message: Map<String, String>
            ): Unit

Функции передачи push-уведомлений в SDK:

fun isAltcraftPush() — проверяет, относится ли полученное уведомление к Altcraft;
fun takePush() — принимает уведомления в сервисе push-провайдера для их дальнейшей обработки на стороне SDK.

Прием уведомления

fun takePush(context: Context, message: Map<String, String>): Unit

Функция, принимающая push-уведомления для их дальнейшей обработки на стороне SDK.

Пример использования:

override fun onMessageReceived(message: RemoteMessage) {
    super.onMessageReceived(message)

    AltcraftSDK.push.receiver.takePush(this@FCMService, message.data)
}
// message.data — payload сообщения

Обработка уведомления

Для настраиваемой обработки входящих push-уведомлений используйте класс PushReceiver — расширяйте его и переопределяйте функцию pushHandler():

open class PushReceiver {
    // Обработка входящего push
    open suspend fun pushHandler(
        context: Context, 
        message: Map<String, String>
    ): Unit
}

По умолчанию SDK создаёт стандартную реализацию PushReceiver и вызывает pushHandler(), отображая уведомление.

Передача произвольных данных в Intent extras при открытии push-уведомления

SDK поддерживает передачу произвольных данных из push-уведомления в приложение через специальный ключ "_extra". Значение _extra должно быть строкой, содержащей JSON-объект.

При клике по уведомлению SDK автоматически:

Извлекает значение _extra из push payload.
Добавляет его в Intent.
Передаёт в Activity, обрабатывающую открытие уведомления или deep link.

Таким образом, содержимое _extra становится обычным Intent extra и доступно в приложении через:

val extraJson = intent?.getStringExtra("_extra")

Поле _extra предназначено для передачи дополнительных параметров, которые не должны быть частью URL, но необходимы при обработке открытия уведомления. Значение поля _extra может быть добавлено с помощью Custom JSON в шаблоне push-уведомления.

Получение уведомлений в любом пакете приложения (опционально)

Для того чтобы получать уведомления в любом пакете приложения, выполните следующие действия:

Шаг 1. Создайте класс AltcraftPushReceiver, расширяющий PushReceiver. В этом классе будет переопределена функция pushHandler():

import android.content.Context
import androidx.annotation.Keep
import com.altcraft.sdk.push.PushReceiver

@Keep
class AltcraftPushReceiver : PushReceiver() {
    override suspend fun pushHandler(context: Context, message: Map<String, String>) {
        // стандартная обработка push-сообщений и отображение уведомлений
        super.pushHandler(context, message)
    }
}

Обратите внимание

Класс должен называться AltcraftPushReceiver. Если вы назовете его иначе, SDK не сможет его найти для передачи уведомления.

Шаг 2. В зависимости от ваших бизнес-целей, настройте логику работы класса AltcraftPushReceiver:

Если вы хотите, чтобы обработку и показ уведомлений выполнял SDK, то:
- используйте super.pushHandler(context, message).
Если вы хотите самостоятельно обрабатывать уведомления, то:
- не вызывайте функцию super.pushHandler();
- вручную регистрируйте события открытия с помощью функции AltcraftSDK.push.pushEvents.openEvent(), иначе событие не будет зарегистрировано платформой Altcraft.

События доставки deliveryEvent регистрируются автоматически. Создание классов AltcraftPushReceiver на регистрацию этого события не влияет.

Обратите внимание

Если вы создали несколько классов AltcraftPushReceiver, то вызов super.pushHandler() в каждом из этих классов будет показывать сообщение пользователю. Чтобы избежать дублирования уведомлений, вызывайте super.pushHandler() только в одном классе.

Шаг 3. Добавьте имена пакетов, которые содержат классы AltcraftPushReceiver, в параметр конфигурации pushReceiverModules. После этого SDK автоматически определит наличие классов AltcraftPushReceiver в указанных пакетах с помощью механизма рефлексии.

Если код приложения будет обфусцироваться, то класс должен быть помечен аннотацией @Keep или добавлен в правила R8/ProGuard, иначе SDK не сможет его обнаружить.

Пример добавления пакета в параметр pushReceiverModules:

pushReceiverModules = listOf(
   context.packageName, // пакет приложения
   "com.altcraft.altcraftmobile.test" 
)

События push: доставка и открытие

AltcraftSDK
└── val push: Push
    └── val pushEvents: EventAPI
        // Сообщить о доставке push-уведомления
        ├── suspend fun deliveryEvent(
        │       context: Context,
        │       message: Map<String, String>? = null,
        │       messageUID: String? = null
        │   ): Unit
        // Сообщить об открытии push-уведомления
        └── suspend fun openEvent(
                context: Context,
                message: Map<String, String>? = null,
                messageUID: String? = null
            ): Unit

Функции регистрации событий push-уведомлений:

suspend fun deliveryEvent() — сообщает платформе о доставке push-уведомления на устройство. При стандартной обработке SDK (super.pushHandler()) регистрируется автоматически;
suspend fun openEvent() — сообщает платформе об открытии push-уведомления пользователем. Если обработку уведомления вы выполняете самостоятельно, событие открытия необходимо регистрировать вручную.

Параметры:

context — Android Context;
message — payload push-уведомления; из него SDK извлекает идентификатор сообщения;
messageUID — явный идентификатор сообщения. Имеет приоритет над UID из message.

Пример использования:

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.push.pushEvents.openEvent(context, message)
}

Цели (target)

Модуль target регистрирует цели (mobile events) — события с сервером Altcraft: установки, покупки, подписки и другие, к которым на платформе привязаны пиксели, сегменты и сценарии.

AltcraftSDK
└── val target: Target
    // Отправить цель (mobile event) на сервер
    └── 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

Кейс: Передача информации о рекламной кампании

Информация о рекламной кампании приложения, которая привела к установке, может быть передана в платформу как значение параметров profileFields/customFields функции subscribe, а также параметров utm или payload функции sendTarget(). Получив UTM-метку в приложении как строку, необходимо вызвать функцию sendTarget():

Передача через payload

AltcraftSDK.target.sendTarget(
    this,
    sid = "your sid",
    eventName = "app_install", 
    payload = mapOf("utm" to "your utm tag")
)

Запись о достижении цели пикселя с UTM-метками

Передача в поля UTM

AltcraftSDK.target.sendTarget(
    this,
    sid = "your sid",
    eventName = "app_install",
    utm = UTM(
        campaign = "your campaign utm",
        content =  "your content utm",
        keyword = "your keyword utm",
        medium = "your medium utm",
        source = "your source utm",
        temp = "your temp utm"
    )
)

Передача в пользовательское поле профиля

// передача utm-метки в поле профиля
// поля профиля должны быть предварительно добавлены в платформе
AltcraftSDK.push.subscription.subscribe(
    context = this,
    profileFields = mapOf("utm" to "your utm tag")
)

Пользовательское поле utm в карточке профиля

Переданные любым из этих способов данные можно использовать для создания сегмента в платформе.

Для регистрации цели используйте функцию sendTarget(). Она имеет следующие параметры:

context: Context

Обязательный: Да

Описание: Android Context.

sid: String

Обязательный: Да

Описание: Строковый идентификатор пикселя, к которому привязываются цели.

eventName: String

Обязательный: Да
Описание: Имя цели (mobile event).

sendMessageId: String?

Обязательный: Нет
Описание: SMID-идентификатор отправленного сообщения (если цель связана с конкретной рассылкой).

payload: Map<String, Any?>?

Обязательный: Нет
Описание: Данные цели — карта со строковыми ключами, для которых допускаются только скалярные типы данных:

String
Boolean
Int
Long
Float
Double
null

matching: Map<String, Any?>?

Обязательный: Нет
Описание: Карта, в которую можно передавать значения с типами и идентификаторами матчинга.

matchingType: String?

Обязательный: Нет
Описание: Тип матчинга.

profileFields: Map<String, Any?>?

Обязательный: Нет
Описание: Поля профиля — карта со строковыми ключами и значениями (JSON-совместимые типы):

Скалярные значения:
- String
- Boolean
- Int
- Long
- Float
- Double
- null
Объекты: Map<String, *>
Списки: List<*>
Массивы карт: Array<Map<String, *>>

Обратите внимание

Параметр используется только при работе с JWT-авторизацией.

utm: UTM?

Обязательный: Нет
Описание: UTM-метки. Добавляются с помощью data class UTM, где каждый вид UTM — отдельный параметр.

data class UTM (
    val campaign: String? = null,
    val content: String? = null,
    val keyword: String? = null,
    val medium: String? = null,
    val source: String? = null,
    val temp: String? = null
)

subscription: Subscription?

Обязательный: Нет
Описание: Параметр добавления подписки для выбранного канала.

Значения параметра — реализации (подтипы) sealed-интерфейса Subscription:

EmailSubscription — email-подписка
SmsSubscription — SMS-подписка
PushSubscription — push-подписка
CcDataSubscription — подписка в Telegram, Whatsapp, Viber, Notify.

Обратите внимание

Используется только при работе с JWT-авторизацией.

Реализации интерфейса `Subscription`

Общая модель: Subscription

Назначение — базовый (sealed) интерфейс для всех видов подписок.
Серилизация полиморфная, поле-дискриминатор — channel.

Общие поля (для всех реализаций):

Поле	Тип	Обязательный	Описание
`resource_id`	`Int`	Да	Идентификатор ресурса/источника подписки
`status`	`String?`	Нет	Статус подписки (например, активна/приостановлена)
`priority`	`Int?`	Нет	Приоритет доставки для данной подписки
`custom_fields`	`Map<String, Any?>?`*	Нет	Пользовательские поля (ключ-значение) для расширенной сегментации
`cats`	`List<String>?`	Нет	Категории подписки
`channel`	`String`	Да	Тип канала; фиксируется реализацией.

Варианты подписки:

EmailSubscription (channel = "email")

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`email`	`String`	Да	Адрес электронной почты получателя

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String`	Нет	Статус подписки
`priority`	`Int`	Нет	Приоритет подписки
`customFields`	`Map<String, Any?>`	Нет	Стандартные и пользовательские поля подписки
`cats`	`List<String>`	Нет	Категории подписки

SmsSubscription (channel = "sms")

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`phone`	`String`	Да	Номер телефона в международном формате

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String`	Нет	Статус подписки
`priority`	`Int`	Нет	Приоритет подписки
`customFields`	`Map<String, Any?>`	Нет	Стандартные и пользовательские поля подписки
`cats`	`List<String>`	Нет	Категории подписки

PushSubscription (channel = "push")

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`provider`	`String`	Да	Провайдер (например, `"android-firebase"`)
`subscriptionId`	`String`	Да	Уникальный идентификатор подписки у провайдера

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String`	Нет	Статус подписки
`priority`	`Int`	Нет	Приоритет подписки
`customFields`	`Map<String, Any?>`	Нет	Стандартные и пользовательские поля подписки
`cats`	`List<String>`	Нет	Категории подписки

CcDataSubscription (channel ∈ {"telegram_bot","whatsapp","viber","notify"})

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`channel`	`String`	Да	Один из: `"telegram_bot"`, `"whatsapp"`, `"viber"`, `"notify"`
`ccData`	`JsonObject`	Да	Канал-специфичные данные (например, chat ID, номер, токены)

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String`	Нет	Статус подписки
`priority`	`Int`	Нет	Приоритет подписки
`customFields`	`Map<String, Any?>`	Нет	Стандартные и пользовательские поля подписки
`cats`	`List<String>`	Нет	Категории подписки

Profile: обновление полей профиля

Важно

Обновление полей профиля с помощью функции updateProfileFields() работает только при использовании JWT-авторизации API-запросов SDK.

AltcraftSDK
└── val profile: Profile
    // Обновляет поля профиля Altcraft
    └── fun updateProfileFields(
        context: Context,
        profileFields: Map<String, Any?>? = null,
        skipTriggers: Boolean? = null
    ): Unit

Для обновления полей профиля используйте функцию updateProfileFields(). Она имеет следующие параметры:

context: Context

Обязательный: Да
Описание: Android Context.

profileFields: Map<String, Any?>?

Обязательный: Нет
Описание: Поля профиля — карта, содержащая значения для полей, которые необходимо изменить (JSON-совместимые типы):

Скалярные значения:
- String
- Boolean
- Int
- Long
- Float
- Double
- null
Объекты: Map<String, *>
Списки: List<*>
Массивы карт: Array<Map<String, *>>

Обратите внимание

Для того чтобы обновление прошло успешно, поля должны быть предварительно добавлены в профиль подписчика.

skipTriggers:Boolean?

Пример использования:

AltcraftSDK.profile.updateProfileFields(
    context = this,
    profileFields = mapOf("_fname" to "Andrey")
)

In-App уведомления

AltcraftSDK
└── val inApp: InApp
    // Настроить анимацию 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
    ├── fun getPlacements(context: Context): Unit
    //
    // Вывод In-App кампаний с типом содержимого "json"
    ├── val jsonContent: JsonContentAPI
    │   ├── fun subscribe(newSubscriber: (String) -> Unit): Unit
    │   └── fun unsubscribe(): Unit
    //
    // Подписка на In-App уведомления (status = SUBSCRIBED)
    ├── fun subscription.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 subscription.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 subscription.getSubscriptionStatus(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

Функции для работы с In-App уведомлениями:

fun animation() — настройка анимации показа In-App уведомления;
fun setScreen() — установка маркера текущего экрана, используется при фильтрации In-App уведомлений. При смене экрана SDK автоматически генерирует триггер open_page (тип default);
fun trigger() — триггер In-App уведомления по имени (тип custom);
fun getPlacements() — запрос доступных размещений In-App с сервера;
val jsonContent — вывод In-App кампаний с типом содержимого json в приложение для собственной отрисовки;
fun subscription.subscribe() — подписка на In-App уведомления;
fun subscription.unSubscribe() — отписка от In-App уведомлений;
suspend fun subscription.getSubscriptionStatus() — получение статуса подписки на In-App уведомления.

Важно

Отслеживание жизненного цикла Activity выполняется SDK автоматически при регистрации модуля in-app — отдельные функции для этой цели в новом SDK нет. SDK отслеживает события жизненного цикла Activity и автоматически генерирует триггер open_app (тип default) при первом запуске Activity.

fun animation(block: Animator.() -> Unit): Unit

Функция позволяет настроить собственную анимацию показа In-App уведомления. Принимает extension-функцию над Animator, в которой можно задать параметры анимации:

prepare(block: View.() -> Unit) — настраивает контейнер In-App уведомления;
animate(block: ViewPropertyAnimator.() -> Unit) — задаёт анимацию показа.

Пример использования:

AltcraftSDK.inApp.animation {
    // настройка анимации
}

fun setScreen(context: Context, screen: String): Unit

Функция устанавливает маркер текущего экрана. Значение маркера используется платформой Altcraft при фильтрации In-App уведомлений — позволяет показывать уведомления только на определённых экранах приложения.

Вызывайте эту функцию при переходе на новый экран, чтобы SDK всегда знал, на каком экране находится пользователь.

Пример использования:

AltcraftSDK.inApp.setScreen(context, "home_screen")

fun trigger(context: Context, name: String): Unit

Функция позволяет вручную запустить показ In-App уведомления по его имени. Используется для триггеров по имени, когда необходимо показать уведомление в ответ на действие пользователя или событие в приложении.

Пример использования:

AltcraftSDK.inApp.trigger(context, "my_custom_trigger")

fun getPlacements(context: Context): Unit

Функция выполняет запрос доступных In-App размещений с сервера Altcraft. Результат запроса можно получить через события SDK.

Если в конфигурации SDK установлен параметр inAppAutoRequest = true, запрос размещений выполняется автоматически при инициализации и далее с интервалом placementsRequestInterval. Перед автоматическим запросом SDK проверяет время последнего успешного запроса: если заданный интервал ещё не прошёл, автоматический запрос не выполняется. Ручной вызов getPlacements() интервалом не ограничивается. Без этого параметра запросы выполняются только по явному вызову getPlacements() или при срабатывании триггеров.

Пример использования:

AltcraftSDK.inApp.getPlacements(context)

val jsonContent: JsonContentAPI

Выводит In-App кампании с типом содержимого json в приложение для собственной отрисовки. В приложении может быть только один активный подписчик — новый вызов subscribe() заменяет существующего.

fun subscribe(newSubscriber: (String) -> Unit) — подписка на вывод In-App JSON;
fun unsubscribe() — отписка от вывода In-App JSON.

Пример использования:

// Подписаться на вывод In-App JSON
AltcraftSDK.inApp.jsonContent.subscribe { json ->
    // отрисовать In-App уведомление самостоятельно
}

// Отписаться
AltcraftSDK.inApp.jsonContent.unsubscribe()

fun subscription.subscribe(context: Context, ...): Unit

Функция выполняет подписку на In-App уведомления. После успешного вызова профиль пользователя будет подписан на получение In-App уведомлений от платформы Altcraft.

Параметры функции аналогичны параметрам push.subscription.subscribe():

context — Android Context;
sync — флаг синхронности выполнения запроса;
profileFields — поля профиля;
customFields — поля подписки;
cats — категории подписки;
replace — при активации заменяет существующую подписку;
skipTriggers — при активации профиль будет игнорироваться в триггерах рассылок и сценариев.

Параметры настраиваются точно так же, как и в push.subscription.subscribe().

Пример использования:

AltcraftSDK.inApp.subscription.subscribe(context)

fun subscription.unSubscribe(context: Context, ...): Unit

Функция отменяет подписку на In-App уведомления. После успешного вызова профиль пользователя будет отписан от получения In-App уведомлений.

Параметры функции аналогичны параметрам push.subscription.unsubscribe().

Пример использования:

AltcraftSDK.inApp.subscription.unSubscribe(context)

suspend fun subscription.getSubscriptionStatus(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

Функция получения текущего статуса подписки на In-App уведомления. Возвращает объект ResponseWithHttpCode, содержащий response?.profile?.subscription — текущую подписку профиля на In-App уведомления. При ошибке выполнения запроса возвращается null. Отсутствие подписки определяется по значению response?.profile?.subscription == null.

Пример использования:

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.inApp.subscription.getSubscriptionStatus(context)?.let { responseWithHttp ->
        val httpCode = responseWithHttp.httpCode
        val response = responseWithHttp.response
        val profile = response?.profile
        val subscription = profile?.subscription
    }
}

Типы отображения In-App уведомлений

SDK поддерживает следующие типы отображения In-App уведомлений:

Тип	Описание
`fullscreen`	Полноэкранное In-App уведомление
`floating_bar`	Плавающая панель (поведение аналогично полноэкранному)
`slideup`	Выезжающая панель сверху или снизу экрана. SDK ожидает от JavaScript данные о размере и позиции, затем применяет нативный контейнер. Если JavaScript не отвечает в течение 1 секунды, уведомление показывается как полноэкранное
`custom`	Пользовательское отображение (поведение аналогично полноэкранному)
`modal`	Модальное окно (поведение аналогично полноэкранному)

Ограничения показа In-App уведомлений

In-App уведомления не показываются в ландшафтной ориентации экрана;
При повороте экрана открытое In-App уведомление закрывается;
При завершении Activity открытое In-App уведомление закрывается;
Кнопка «Назад» закрывает In-App уведомление;
Неанонимные In-App кампании требуют статуса подписки subscribed на In-App уведомления.

Core: авторизация​

Очистка данных SDK​

Сброс запрета на retry-операции при инициализации SDK​

Core: события SDK​

Подписка на события​

Отписка от событий​

Список всех событий SDK​

Push: работа со статусами подписки​

Изменение статуса подписки​

Запрос статуса подписки​

Push: управление push-токенами​

Пример регистрации провайдеров​

Push: передача push-уведомлений в SDK​

Прием уведомления​

Обработка уведомления​

Передача произвольных данных в Intent extras при открытии push-уведомления​

Получение уведомлений в любом пакете приложения (опционально)​

События push: доставка и открытие​

Цели (target)​

Реализации интерфейса Subscription​

Profile: обновление полей профиля​

In-App уведомления​

Типы отображения In-App уведомлений​

Ограничения показа In-App уведомлений​

Core: авторизация

Очистка данных SDK

Сброс запрета на retry-операции при инициализации SDK

Core: события SDK

Подписка на события

Отписка от событий

Список всех событий SDK

Push: работа со статусами подписки

Изменение статуса подписки

Запрос статуса подписки

Push: управление push-токенами

Пример регистрации провайдеров

Push: передача push-уведомлений в SDK

Прием уведомления

Обработка уведомления

Передача произвольных данных в Intent extras при открытии push-уведомления

Получение уведомлений в любом пакете приложения (опционально)

События push: доставка и открытие

Цели (target)

Реализации интерфейса `Subscription`

Profile: обновление полей профиля

In-App уведомления

Типы отображения In-App уведомлений

Ограничения показа In-App уведомлений