Функционал SDK

подсказка

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

Работа со статусами подписки

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

AltcraftSDK
└─ val pushSubscriptionFunctions: PublicPushSubscriptionFunctions
   // Подписка (статус = SUBSCRIBED)
   ├─ fun pushSubscribe(
   │     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 pushSuspend(
    │     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 pushUnSubscribe(
          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

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

fun pushSubscribe() — выполняет подписку на push-уведомления;
fun pushUnSubscribe() — отменяет подписку на push-уведомления;
fun pushSuspend() — приостанавливает подписку на push-уведомления (уведомления не приходят, но при этом не создается событие отписки в профиле пользователя);
fun unSuspendPushSubscription() — используется для создания LogIn-, LogOut-переходов.

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

context: Context

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

sync: Boolean

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

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

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

Если sync == true

ResponseWithHttpCode
  ├─ httpCode: 200
  └─ response
     ├─ 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 по ключу "response_with_http_code" доступны:

httpCode – транспортный код ответа;
ResponseWithProfile – data class, содержащий:
- error: Int? — внутренний код ошибки сервера (0, если ошибок нет),
- errorText: String? — текст ошибки (пустая строка, если ошибок нет),
- profile: ProfileData? — данные профиля, если запрос успешный:
  - информация о профиле (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

ResponseWithHttpCode<ResponseWithProfile>
  ├─ httpCode: Int?
  └─ response: ResponseWithProfile?
      ├─ error: Int?
      ├─ errorText: String?
      └─ profile: ProfileData? = null

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

httpCode – транспортный код ответа;
ResponseWithProfile – data class, содержащий:
- error: Int? — внутренний код ошибки сервера (0, если ошибок нет),
- errorText: String? — текст ошибки (пустая строка, если ошибок нет),
- profile: ProfileData? — данные профиля, для асинхронного запроса всегда равен null.

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

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

Операции без автоматического повтора попытки на стороне SDK:

430 – подписка на уведомления;
431 — приостановка подписки;
432 — отписка.

Операции с автоматическим повтором попытки на стороне SDK:

530 – подписка на уведомления;
531 — приостановка подписки;
532 — отписка.

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

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

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

AltcraftSDK.eventSDKFunctions.subscribe { event ->
    val events = setOf(
        SDKEvent.PushSubscribeRequestSuccessful,
        SDKEvent.PushSuspendRequestSuccessful,
        SDKEvent.PushUnsubscribeRequestSuccessful,
        SDKEvent.PushSubscribeRequestFailed,
        SDKEvent.PushSuspendRequestFailed,
        SDKEvent.PushUnsubscribeRequestFailed,
        SDKEvent.PushSubscribeRetryLimit,
        SDKEvent.PushEventRetryLimit,
        SDKEvent.MobileEventRetryLimit
    )

    val sdkEvent = event.event ?: return@subscribe
    if (sdkEvent !in events) return@subscribe

    (event.eventValue?.get("response_with_http_code") as? ResponseWithHttpCode<ResponseWithProfile>)?.let { responseWithHttp ->
        val httpCode = responseWithHttp.httpCode

        val response = responseWithHttp.response
        val error = response?.error
        val errorText = response?.errorText

        val profile = response?.profile
        val profileId = profile?.id
        val profileStatus = profile?.status
        val profileIsTest = profile?.isTest

        val subscription = profile?.subscription
        val subscriptionId = subscription?.subscriptionId
        val hashId = subscription?.hashId
        val provider = subscription?.provider
        val subscriptionStatus = subscription?.status

        val fields = subscription?.fields

        val cats = subscription?.cats
        val firstCat = cats?.firstOrNull()
        val catName = firstCat?.name
        val catTitle = firstCat?.title
        val catSteady = firstCat?.steady
        val catActive = firstCat?.active
    }
}

profileFields:Map<String, Any?>?

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

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

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

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

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

customFields:Map<String, Any?>?

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

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

String
Boolean
Int
Long
Float
Double
null

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

SDK error: 430
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:listOf(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. Если в запросе будет использовано поле, которое не добавлено в ресурс — запрос вернется с ошибкой:

SDK error: 430
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.pushSubscriptionFunctions.pushSubscribe(context)

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

AltcraftSDK.pushSubscriptionFunctions.pushSubscribe(
    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
)

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

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

Функция unSuspendPushSubscription()

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

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

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

LogIn-переход:

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

LogOut-переход:

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

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

private suspend fun unSuspend(context: Context, logIn: Boolean) {

    // Изменение JWT до запроса
    setAuth(context, logIn)

    AltcraftSDK.pushSubscriptionFunctions
        .unSuspendPushSubscription(context)
        ?.let { result ->
            if (result.httpCode == 200 && result.response?.profile?.subscription == null) {
                AltcraftSDK.pushSubscriptionFunctions.pushSubscribe(
                    context = context
                    // Укажите необходимые параметры
                )
            }
        }
}

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

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

AltcraftSDK
└── val pushSubscriptionFunctions: PublicPushSubscriptionFunctions
    // Статус последней подписки профиля
    ├── suspend fun getStatusOfLatestSubscription(
    │       context: Context
    │   ): ResponseWithHttpCode<ResponseWithProfile>?
    // Статус подписки по текущему токену/провайдеру
    ├── suspend fun getStatusForCurrentSubscription(
    │       context: Context
    │   ): ResponseWithHttpCode<ResponseWithProfile>?
    // Статус последней подписки по указанному провайдеру (если null — используется текущий)
    └── suspend fun getStatusOfLatestSubscriptionForProvider(
            context: Context,
            provider: String? = null
        ): ResponseWithHttpCode<ResponseWithProfile>?

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

fun getStatusOfLatestSubscription() — статус последней подписки профиля;
fun getStatusOfLatestSubscriptionForProvider() — статус подписки для текущего токена/провайдера;
fun getStatusForCurrentSubscription() — статус последней подписки по провайдеру. Если указан null, то используется текущий.

suspend fun getStatusOfLatestSubscription(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

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

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

AltcraftSDK.pushSubscriptionFunctions.getStatusOfLatestSubscription(context)

suspend fun getStatusForCurrentSubscription(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

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

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

AltcraftSDK.pushSubscriptionFunctions.getStatusForCurrentSubscription(context)

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

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

AltcraftSDK.pushSubscriptionFunctions.getStatusOfLatestSubscriptionForProvider(context, provider = null)

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

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

CoroutineScope(Dispatchers.IO).launch {
    AltcraftSDK.pushSubscriptionFunctions
        .getStatusForCurrentSubscription(this@App)
        ?.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-токенами провайдеров

AltcraftSDK
└── val pushTokenFunctions: PublicPushTokenFunctions
    |
    // Сохранить токен вручную (onNewToken)
    ├── fun setPushToken(context: Context, provider: String?, token: String?): Unit
    |
    // Получить текущие данные токена устройства
    ├── suspend fun getPushToken(context: Context): TokenData?
    |
    // Установить провайдер Firebase Cloud Messaging (null — удалить)
    ├── fun setFCMTokenProvider(provider: FCMInterface?): Unit
    |
    // Установить провайдер Huawei Mobile Services (null — удалить)
    ├── fun setHMSTokenProvider(provider: HMSInterface?): Unit
    |
    // Установить провайдер RuStore (null — удалить)
    ├── fun setRuStoreTokenProvider(provider: RustoreInterface?): Unit
    |
    // Удалить токен push указанного провайдера
    ├── fun deleteDeviceToken(context: Context, provider: String, complete: () -> Unit): Unit
    |
    // Принудительное обновление токена (удалить —> обновить)
    ├── fun forcedTokenUpdate(context: Context, complete: () -> Unit): Unit
    |
    // Изменить список приоритетов провайдеров и инициировать обновление токена
    └── suspend fun changePushProviderPriorityList(context: Context, priorityList: List<String>): Unit

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

fun setPushToken() — ручная установка push-токена устройства и провайдера в SharedPreferences;
fun getPushToken() — получение текущего push-токена;
fun setFCMTokenProvider() — установка и снятие push-токена FCM;
fun setHMSTokenProvider() — установка и снятие push-токена HMS;
fun setRuStoreTokenProvider() — установка и снятие push-токена RuStore;
fun changePushProviderPriorityList() — функция, позволяющая выполнить динамическую смену провайдера с обновлением push-токена подписки;
fun deleteDeviceToken() — удаление push-токена указанного провайдера;
fun forcedTokenUpdate() — удаление текущего push-токена с последующим обновлением.

fun setPushToken(context: Context, provider: String?, token: String?): Unit

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

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

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

AltcraftSDK.pushTokenFunctions.setPushToken(context, provider, token)

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

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

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

suspend fun getPushToken(context: Context): TokenData?

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

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

AltcraftSDK.pushTokenFunctions.getPushToken(context)

Пример запроса получения данных push-токена:

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

fun setFCMTokenProvider(provider: FCMInterface?): Unit

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

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

AltcraftSDK.pushTokenFunctions.setFCMTokenProvider(FCMProvider())

Важно

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

fun setHMSTokenProvider(provider: HMSInterface?): Unit

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

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

AltcraftSDK.pushTokenFunctions.setHMSTokenProvider(HMSProvider())

Важно

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

fun setRuStoreTokenProvider(provider: RustoreInterface?): Unit

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

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

AltcraftSDK.pushTokenFunctions.setRuStoreTokenProvider(RuStoreProvider())

Важно

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

suspend fun changePushProviderPriorityList(context: Context, priorityList: List<String>): Unit

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

AltcraftSDK.pushTokenFunctions.changePushProviderPriorityList(context, listOf(HMS_PROVIDER, RUSTORE_PROVIDER, FCM_PROVIDER))

fun deleteDeviceToken(context: Context, provider: String, complete: () -> Unit): Unit

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

AltcraftSDK.pushTokenFunctions.deleteDeviceToken(context, provider) {
    // callback после удаления
}

fun forcedTokenUpdate(context: Context, complete: () -> Unit): Unit

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

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

AltcraftSDK.pushTokenFunctions.forcedTokenUpdate(context) {
    // callback после удаления
}

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

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

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

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // установить провайдер RuStore
        RuStorePushClient.init(this, "rustore project id")
        
        // установить провайдер JWT
        AltcraftSDK.setJWTProvider(JWTProvider(applicationContext))
        
        // установить провайдер FCM
        AltcraftSDK.pushTokenFunctions.setFCMTokenProvider(FCMProvider())
        
        // установить провайдер HMS
        AltcraftSDK.pushTokenFunctions.setHMSTokenProvider(HMSProvider())
        
        // установить провайдер RuStore
        AltcraftSDK.pushTokenFunctions.setRuStoreTokenProvider(RuStoreProvider())
        
        // создать AltcraftConfiguration
        val config = AltcraftConfiguration.Builder(
            apiUrl = "your api url",
            R.drawable.ic_altcraft_label
        ).build()
        
        // Инициализация SDK
        AltcraftSDK.initialization(context = this@App, configuration = config)
    }
}

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

PushReceiver — публичный класс, в котором содержится функция, принимающая уведомления.

AltcraftSDK
└── open class PushReceiver
    // Обработка входящего push
    ├── open suspend fun pushHandler(
    │       context: Context, 
    │       message: Map<String, String>
    │   ): Unit
    // Точка входа в SDK для доставки push 
    └── companion object
        └── fun takePush(
                context: Context, 
                message: Map<String, String>
            ): Unit

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

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

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

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

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

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

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

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

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

open suspend fun pushHandler(context: Context, message: Map<String, String>): Unit

Функция запускает стандартный механизм обработки push-уведомления Altcraft в SDK.

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

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

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

import android.content.Context
import androidx.annotation.Keep
import com.altcraft.sdk.AltcraftSDK

@Keep
class AltcraftPushReceiver : AltcraftSDK.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();
- вручную регистрируйте события открытия с помощью функции 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" 
)

Мобильные события

// Функция объекта PublicMobileEventFunctions

AltcraftSDK
└── val mobileEventFunctions: PublicMobileEventFunctions

    // Отправить мобильное событие (mobile event) на сервер
    └── fun mobileEvent(
        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 функции pushSubscribe, а также параметров utm или payload функции mobileEvent(). Получив UTM-метку в приложении как строку, необходимо вызвать функцию mobileEvent():

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

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

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

AltcraftSDK.mobileEventFunctions.mobileEvent(
            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.pushSubscriptionFunctions.pushSubscribe(
     profileFields: ["utm": "your utm tag"]
)

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

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

context: Context

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

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

sid: String

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

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

eventName: String

Обязательный: Да
Описание: Имя мобильного события.

sendMessageId: String?

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

payload: String

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

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>`	Нет	Категории подписки

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

Важно

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

AltcraftSDK
└── val profileFunctions: PublicProfileFunctions
    // Обновляет поля профиля 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?

Получение событий SDK в приложении

// Функции объекта Events

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

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

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

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

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

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

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

Все события, передаваемые SDK, являются экземплярами Event или его наследников:

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

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

function — имя функции, вызывавшей событие;
event — тип события SDK, представленный значением enum SDKEvent (список событий SDK представлен в пункте "События SDK");
eventMessage — сообщение события;
eventValue — произвольные данные [String: Any?]? которые добавляются к некоторым событиям как полезная нагрузка;
date — время события;
internal — флаг, указывающий, является ли событие внутренним.

Классы событий 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)

Пример содержания события успешной подписки на push-уведомления

├─ function: processResponse
├─ event: PushSubscribeRequestSuccessful
├─ eventMessage: "successful request: push/subscribe"
├─ eventValue
│  ├─ http code: 200
│  └─ response
│     ├─ error: 0
│     ├─ errorText: ""
│     └─ profile
│        ├─ id: "your id"
│        ├─ status: "subscribed"
│        ├─ acid: "your acid"
│        ├─ isTest: false
│        └─ subscription
│           ├─ subscriptionId: "your subscriptionId"
│           ├─ hashId: "c52b28d2"
│           ├─ provider: "android-firebase"
│           ├─ status: "subscribed"
│           ├─ fields
│           │  ├─ _device_name: "Pixel 7"
│           │  ├─ _device_model: "Google Pixel 7"
│           │  ├─ _os_tz: "+0300"
│           │  ├─ _os_language: "ru"
│           │  ├─ _os_ver: {"raw":"14","ver":[14]}
│           │  ├─ _ad_track: true
│           │  ├─ _os: "Android"
│           │  └─ _device_type: "mob"
│           └─ cats
│              └─ [ { name: "developer_news", title: "dev_news", steady: false, active: false } ]
└─ date: 2025-09-03 09:01:44 +0000

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

fun unsubscribe(): Unit

При помощи данной функции можно отписаться от событий SDK. Она отменяет передачу событий SDK, при этом callback остаётся назначенным, но доставка событий прекращается.

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

AltcraftSDK.eventSDKFunctions.unsubscribe()

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

Список событий SDKEvent enum

События SDK представлены enum-классом SDKEvent, где каждое значение содержит строковое сообщение (message).

Общие события SDK:

Значение	Сообщение
`ConfigIsSet`	SDK configuration is installed
`PushProviderSet`	push provider set:
`NotAcPush`	received a notification unrelated to the Altcraft Platform
`AcPush`	received Altcraft push notification
`PushIsPosted`	push is posted
`SdkCleared`	SDK data has been cleared
`ReceiverRedefined`	receiver is redefined
`NotAuthenticatedError`	User is not authenticated
`UserLogOut`	User logged out. Anonymous session started.

Внутренние ошибки без повтора:

Значение	Сообщение
`ConfigIsNotSet`	the configuration is not set
`ConfigNotValid`	invalid configuration
`SdkInitWaitingExpired`	SDK initialization timeout has expired
`MobileEventPartsIsNull`	mobile event parts is null
`InvalidPushProvider`	invalid provider. Available - android-firebase, android-huawei, android-rustore.
`PushDataIsNull`	push data is null
`PushUidIsNull`	uid in the push data is null or empty, it is impossible to send a push event to the server.
`ErrorImgLoad`	error uploading the notification image
`NotificationErr`	couldn't create notification
`ChannelNotCreated`	the notification channel has not been created
`SmidIsNull`	send message ID is null
`InvalidStaticField`	invalid in-app static field
`RoomMigrationError`	Room database migration failed. The local SDK database will be recreated.

Отсутствующие payload запросов (без повтора):

Значение	Сообщение
`UnSuspendRequestDataIsNull`	unsuspend request data is null
`SubscriptionStatusRequestDataIsNull`	status request data is null
`InAppSubscriptionStatusRequestDataIsNull`	status request data is null
`AuthorizeRequestDataIsNull`	authorize request data is null

Лимит повторов достигнут:

Значение	Сообщение
`PushSubscribeRetryLimit`	push subscribe retry limit
`PushEventRetryLimit`	push event retry limit
`MobileEventRetryLimit`	mobile event retry limit
`ProfileUpdateRetryLimit`	profile update retry limit
`InAppSubscribeRetryLimit`	in-app subscribe retry limit
`AuthRequestRetryLimit`	auth request retry limit
`InAppEventRetryLimit`	in-app event retry limit

Проблемы состояния SDK или окружения:

Значение	Сообщение
`ConfigIsNull`	config data is null
`PushTokenIsNull`	current push token is null
`UserTagIsNull`	userTag is null. It is impossible to identify the user
`PermissionDenied`	no permission to send notifications
`NoInternetConnect`	no internet connection, retry when connection is restored
`NotUpdated`	failed to update the push token. The subscription request was rejected
`ResponseDataIsNull`	response data is null
`JwtTokenIsNull`	JWT token is null
`MatchingIsNull`	matching mode is null
`JwtTooLarge`	JWT payload exceeds allowed size (16 KB limit): input rejected to prevent DoS
`PayloadIsMissing`	JWT does not contain a payload
`InternalAuthIsNull`	internal auth data is null
`ExternalAuthIsNull`	external auth data is null
`MatchingIdIsNull`	matching claim does not contain a matching ID
`InvalidPayload`	invalid mobile event payload: not all values are primitives
`InvalidCustomFields`	invalid custom fields: not all values are primitives

Отсутствующие payload запросов (с повтором):

Значение	Сообщение
`PushSubscribeRequestDataIsNull`	push subscribe request data is null
`TokenUpdateRequestDataIsNull`	token update request data is null
`PushEventRequestDataIsNull`	push event request data is null
`InAppEventRequestDataIsNull`	in-app event request data is null
`MobEventRequestDataIsNull`	mobile event request data is null
`ProfileUpdateRequestDataIsNull`	profile update request data is null
`InAppSubscribeRequestDataIsNull`	profile update request data is null
`InAppPlacementsRequestDataIsNull`	in-app placements request data is null

Успешные API-запросы:

Значение	Сообщение
`PushUnsubscribeRequestSuccessful`	successful request: push/unsubscribe
`PushSubscribeRequestSuccessful`	successful request: push/subscribe
`PushSuspendRequestSuccessful`	successful request: push/suspend
`InAppUnsubscribeRequestSuccessful`	successful request: inapp/unsubscribe
`InAppSubscribeRequestSuccessful`	successful request: inapp/subscribe
`InAppStatusRequestSuccessful`	successful request: inapp/status
`InAppEventRequestSuccessful`	successful request: inapp/event
`InAppPlacementsRequestSuccessful`	successful request: in_app/placements
`PushStatusRequestSuccessful`	successful request: push/status
`TokenUpdateRequestSuccessful`	successful request: push/update
`PushEventRequestSuccessful`	successful request: event/push
`MobileEventRequestSuccessful`	successful request: event/post
`UnsuspendRequestSuccessful`	successful request: push/unsuspend
`ProfileUpdateRequestSuccessful`	successful request: profile/update
`AuthenticateSuccessful`	successful request: profile/authenticate

Неудачные API-запросы:

Значение	Сообщение
`PushUnsubscribeRequestFailed`	failed request: push/unsubscribe
`PushSubscribeRequestFailed`	failed request: push/subscribe
`PushSuspendRequestFailed`	failed request: push/suspend
`InAppUnsubscribeRequestFailed`	failed request: inapp/unsubscribe
`InAppSubscribeRequestFailed`	failed request: inapp/subscribe
`InAppStatusRequestFailed`	failed request: inapp/status
`InAppEventRequestFailed`	failed request: inapp/event
`InAppPlacementsRequestFailed`	failed request: in_app/placements
`PushStatusRequestFailed`	failed request: push/status
`TokenUpdateRequestFailed`	failed request: push/update
`PushEventRequestFailed`	failed request: event/push
`MobileEventRequestFailed`	failed request: event/post
`ProfileUpdateRequestFailed`	failed request: profile/update
`UnsuspendRequestFailed`	failed request: push/unsuspend
`AuthenticateFailed`	failed request: profile/authenticate
`InAppStaticErrorLoad`	error loading in-app notification static resources
`InAppContentErrorLoad`	error loading in-app notification content

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

AltcraftSDK
└── val inAppFunctions: PublicInAppFunctions
    // Настроить анимацию In-App уведомления
    ├── fun setAnimation(block: Animator.() -> Unit): Unit
    //
    // Установить маркер текущего экрана (используется при фильтрации In-App уведомлений)
    ├── fun setScreen(screen: String): Unit
    //
    // Триггер показа In-App размещения
    ├── fun inAppTrigger(context: Context, name: String): Unit
    //
    // Запрос доступных размещений In-App
    ├── fun getInAppPlacements(context: Context): Unit
    //
    // Подписаться на жизненный цикл Activity для автоматического показа In-App
    ├── fun subscribeOnActivityLifecycle(context: Context): Unit
    //
    // Подписка на In-App уведомления (status = SUBSCRIBED)
    ├── fun inAppSubscribe(
    │     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 inAppUnSubscribe(
    │     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 getInAppSubscriptionStatus(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

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

fun setAnimation() — настройка анимации показа In-App уведомления;
fun setScreen() — установка маркера текущего экрана, используется при фильтрации In-App уведомлений;
fun inAppTrigger() — триггер кастомного In-App уведомления по имени;
fun getInAppPlacements() — запрос доступных размещений In-App с сервера;
fun subscribeOnActivityLifecycle() — подписка на жизненный цикл Activity для автоматического показа In-App уведомлений;
fun inAppSubscribe() — подписка на In-App уведомления;
fun inAppUnSubscribe() — отписка от In-App уведомлений;
suspend fun getInAppSubscriptionStatus() — получение статуса подписки на In-App уведомления.

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

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

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

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

fun setScreen(screen: String): Unit

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

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

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

AltcraftSDK.inAppFunctions.setScreen("home_screen")

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

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

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

AltcraftSDK.inAppFunctions.inAppTrigger(context, "my_custom_trigger")

fun getInAppPlacements(context: Context): Unit

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

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

AltcraftSDK.inAppFunctions.getInAppPlacements(context)

fun subscribeOnActivityLifecycle(context: Context): Unit

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

Важно

Вызывайте subscribeOnActivityLifecycle() как можно раньше на старте приложения — в Application.onCreate(). Это необходимо для того, чтобы callback жизненного цикла Activity успел зарегистрироваться до первого перехода приложения в foreground. Если вызов будет выполнен с задержкой, In-App уведомления, которые должны были показаться при старте приложения, могут быть пропущены.

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

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        // Регистрация как можно раньше
        AltcraftSDK.inAppFunctions.subscribeOnActivityLifecycle(this)

        // Остальная инициализация
    }
}

fun inAppSubscribe(context: Context, ...): Unit

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

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

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

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

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

AltcraftSDK.inAppFunctions.inAppSubscribe(context)

fun inAppUnSubscribe(context: Context, ...): Unit

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

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

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

AltcraftSDK.inAppFunctions.inAppUnSubscribe(context)

suspend fun getInAppSubscriptionStatus(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

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

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

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

Аутентификация

AltcraftSDK
└── val authFunctions: PublicAuthFunctions
    // Аутентификация пользователя
    ├── fun authenticate(context: Context): Unit
    //
    // Выход пользователя
    ├── fun logOut(context: Context): Unit
    //
    // Проверка статуса аутентификации
    └─ suspend fun isAuthenticated(context: Context): Boolean

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

fun authenticate() — аутентификация пользователя на платформе Altcraft;
fun logOut() — выход пользователя, завершение сессии;
suspend fun isAuthenticated() — проверка текущего статуса аутентификации.

fun authenticate(context: Context): Unit

Функция выполняет аутентификацию пользователя на платформе Altcraft. Отправляет запрос на сервер с текущими данными аутентификации (JWT-токен или rToken) и привязывает устройство к профилю пользователя.

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

Важно

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

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

AltcraftSDK.authFunctions.authenticate(context)

fun logOut(context: Context): Unit

Функция выполняет выход пользователя — завершает текущую сессию аутентификации на платформе Altcraft. После вызова устройство переходит в режим анонимной сессии. В данном режиме недоступны персонализированные InApp-уведомления, а также недоступно управление подпиской через inAppSubscribe().

Важно

Вызывайте logOut() только тогда, когда пользователь действительно выполняет выход из приложения и переходит в анонимный режим.

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

AltcraftSDK.authFunctions.logOut(context)

suspend fun isAuthenticated(context: Context): Boolean

Функция проверяет текущий статус аутентификации пользователя. Возвращает true, если пользователь успешно аутентифицирован на платформе Altcraft, и false в противном случае.

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

CoroutineScope(Dispatchers.IO).launch {
    val authenticated = AltcraftSDK.authFunctions.isAuthenticated(context)
    if (authenticated) {
        // пользователь аутентифицирован
    } else {
        // пользователь не аутентифицирован
    }
}

Дополнительные функции SDK

Ручная регистрация push-событий

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

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

// Функции объекта PublicPushEventFunctions

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

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

Функции ручной регистрации событий:

fun deliveryEvent() — регистрация доставки уведомления;
fun openEvent() — регистрация открытия уведомления.

fun deliveryEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit

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

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

AltcraftSDK.pushEventFunctions.deliveryEvent(context, message, messageUID)

fun openEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit

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

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

AltcraftSDK.pushEventFunctions.openEvent(context, message, messageUID)

Передача произвольных данных в 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-уведомления.

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

fun clear(context: Context, onComplete: (() -> Unit)? = null)

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

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

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

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

Функциональное обновление полей профиля

AltcraftSDK
└─ val pushSubscriptionFunctions: PublicPushSubscriptionFunctions
   └─ fun actionField(key: String): ActionFieldBuilder

fun actionField(key: String): ActionFieldBuilder

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

    .set(value)
    .unset(value)
    .incr(value)
    .add(value)
    .delete(value)
    .upsert(value)

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

AltcraftSDK.pushSubscriptionFunctions.pushSubscribe(
    context = context,
    // "_fname" — изменяемое поле
    // .set("Andrey") — команда, которая установит значение "Andrey" для этого поля
    // actionField().set() возвращает Pair<String, Map<String, Any?>>, поэтому оборачиваем в mapOf()
    profileFields = mapOf(
        AltcraftSDK.pushSubscriptionFunctions
            .actionField("_fname").set("Andrey")
    )
)

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

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

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

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

fun unlockInitialOperationsInThisSession(): Unit

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

Запрос разрешения на отправку уведомлений

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

Начиная с Android 13 (API 33, Tiramisu), приложения должны явно запрашивать разрешение POST_NOTIFICATIONS, прежде чем отправлять уведомления. На более ранних версиях Android вызов функции не требуется — разрешение предоставляется автоматически.

fun requestNotificationPermission(context: Context, activity: ComponentActivity)

Функция выполняет проверку текущего статуса разрешения и, при необходимости, показывает пользователю системный диалог запроса разрешения. Если пользователь уже выбрал запрет на показ уведомлений, то повторный вызов функции снова выведет диалог запроса.

Проверка источника push-уведомления

fun isAltcraftPush(message: Map<String, String>): Boolean

Статическая функция в PushReceiver companion object, проверяющая является ли push-уведомление отправленным от платформы Altcraft.

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

if (AltcraftSDK.PushReceiver.isAltcraftPush(message.data)) {
    AltcraftSDK.PushReceiver.takePush(this, message.data)
}

Работа со статусами подписки​

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

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

Управление push-токенами провайдеров​

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

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

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

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

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

Мобильные события​

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

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

Получение событий SDK в приложении​

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

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

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

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

Аутентификация​

Дополнительные функции SDK​

Ручная регистрация push-событий​

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

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

Функциональное обновление полей профиля​

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

Запрос разрешения на отправку уведомлений​

Проверка источника push-уведомления​

Работа со статусами подписки

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

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

Управление push-токенами провайдеров

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

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

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

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

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

Мобильные события

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

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

Получение событий SDK в приложении

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

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

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

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

Аутентификация

Дополнительные функции SDK

Ручная регистрация push-событий

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

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

Функциональное обновление полей профиля

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

Запрос разрешения на отправку уведомлений

Проверка источника push-уведомления