Документация для версии v75

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

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

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

data class ProfileData(
    val id: String?,
    val status: String?,
    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, Any?>?,
    val cats: List<CategoryData>?
)

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

Если sync == false

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

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

httpCode – транспортный код ответа;
Response – 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 codes = setOf(
        230, 231, 232,
        430, 431, 432,
        531, 532, 533
    )

    val code = event.eventCode ?: return@subscribe
    if (code !in codes) return@subscribe

    (event.eventValue?.get("response_with_http_code") as? DataClasses.ResponseWithHttpCode)?.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(
    DataClasses.CategoryData(name = "football", active = true),
    DataClasses.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(DataClasses.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);
Пользователю присваивается JTW_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
    │   ): DataClasses.ResponseWithHttpCode?
    // Статус подписки по текущему токену/провайдеру
    ├── suspend fun getStatusForCurrentSubscription(
    │       context: Context
    │   ): DataClasses.ResponseWithHttpCode?
    // Статус последней подписки по указанному провайдеру (если null — используется текущий)
    └── suspend fun getStatusOfLatestSubscriptionForProvider(
            context: Context,
            provider: String? = null
        ): DataClasses.ResponseWithHttpCode?

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

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

suspend fun getStatusOfLatestSubscription(context: Context): DataClasses.ResponseWithHttpCode?

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

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

AltcraftSDK.pushSubscriptionFunctions.getStatusOfLatestSubscription(context)

suspend fun getStatusForCurrentSubscription(context: Context): DataClasses.ResponseWithHttpCode?

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

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

AltcraftSDK.pushSubscriptionFunctions.getStatusForCurrentSubscription(context)

suspend fun getStatusOfLatestSubscriptionForProvider(context: Context, provider: String? = null): DataClasses.ResponseWithHttpCode?

Функция получения статуса последней подписки по провайдеру. Возвращает объект 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): DataClasses.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 указанного провайдера
    ├── suspend 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-токена устройства и провайдера в UserDefaults;
fun getPushToken() — получение текущего push-токена;
fun setFCMTokenProvider() — установка и снятие push-токена FCM;
fun setHMSTokenProvider() — установка и снятие push-токена HSM;
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): DataClasses.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))

suspend 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 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 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 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: DataClasses.Subscription? = null,
        utm: DataClasses.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 = DataClasses.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.shared.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: DataClasses.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: DataClasses.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: (DataClasses.Event) -> Unit
    │   ): Unit
    // Отписка от событий
    └── fun unsubscribe(): Unit

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

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

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

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

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

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

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

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

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

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

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

open class Event(
    val function: String,
    val eventCode: Int? = null,
    val eventMessage: String? = null,
    val eventValue: Map<String, Any?>? = null,
    val date: Date = Date(),
)

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

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

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

├─ function: processResponseprocessResponse
├─ eventCode: 230
├─ eventMessage: "successful request: push/subscribe"
├─ eventValue
│  ├─ http code: 200
│  └─ response
│     ├─ error: 0
│     ├─ errorText: ""
│     └─ profile
│        ├─ id: "your id"
│        ├─ status: "subscribed"
│        ├─ 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

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

Код	Описание
200	SDK configuration is installed
201	push provider set
202	received a notification unrelated to the Altcraft Platform
203	received Altcraft push notification
204	push is posted
205	SDK data has been cleared
206	waiting for SDK initialization to complete
207	waiting for push token update to complete
220	receiver override event
230	subscribe request succeeded
231	push suspend request succeeded
232	push unsubscribed request succeeded
233	push update request succeeded
234	push unsuspend request succeeded
235	profile status request succeeded
236	push event delivered successfully
237	mobile event delivered successfully
401	the configuration is not set
402	userTag is null. It is impossible to identify the user
404	SDK initialization timeout has expired
405	mobile event parts is null
422	unsuspend request data is null
423	profile request data is null
430	subscribe request failed
431	suspend request failed
432	unsubscribed request failed
433	update request failed
434	unsuspend request failed
435	status request failed
436	push event delivery failed
437	mobile event request failed
450	push data is null
451	uid in the push data is null or empty, it is impossible to send a push event to the server
452	error uploading the notification image
453	couldn't create notification
454	foreground info is null
455	the notification channel has not been created
471	invalid provider. Available - android-firebase, android-huawei, android-rustore
472	invalid customFields: not all values are primitives
480	subscribe retry limit reached (request removed from DB)
484	push event retry limit reached (request removed from DB)
485	mobile event retry limit reached (request removed from DB)
501	config data is null
502	current push token is null
503	userTag is null. It is impossible to identify the user
504	no permission to send notifications
505	no internet connection, retry when connection is restored
506	failed to update the push token. The subscription request was rejected
520	push subscribe request data is null
521	token update request data is null
524	push event request data is null
525	mobile event request data is null
529	common data is null
530	subscribe request failed (retryable)
531	token update request failed (retryable)
534	push event delivery failed (retryable)
535	mobile event delivery failed (retryable)
540	JWT token is null
541	matching mode is null
542	JWT payload exceeds allowed size (16 KB limit): input rejected to prevent DoS
543	JWT does not contain a payload
544	auth data is null
545	matching claim does not contain a matching ID
560	response data is null

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Передача произвольных данных в 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" для этого поля
    profileFields = AltcraftSDK.pushSubscriptionFunctions
        .actionField("_fname").set("Andrey")
)

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

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

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

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

fun reinitializeRetryControlInThisSession(): Unit

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

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

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

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

fun requestNotificationPermission(context: Context, activity: ComponentActivity)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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