Перейти к основному содержимому
Документация для версии v73

Функционал SDK

подсказка

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

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

    // Object Events functions

    AltcraftSDK
    └── val eventSDKFunctions: Events
        // Subscribe to SDK events (replaces the existing subscriber)
        ├── fun subscribe(
        │       newSubscriber: (DataClasses.Event) -> Unit
        │   ): Unit
        // Unsubscribe from events
        └── fun unsubscribe(): Unit

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

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

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

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

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

AltcraftSDK.eventSDKFunctions.subscribe { event ->
    // event handling
}

Все события, передаваемые 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: "Mobile"
│           └─ 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 остаётся назначенным, но доставка событий прекращается.

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

    //unsubscribe from getting SDK events
AltcraftSDK.eventSDKFunctions.unsubscribe()

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

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

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.

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

// Last profile subscription status
AltcraftSDK.pushSubscriptionFunctions.getStatusOfLatestSubscription(context)

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

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

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

// Subscription status corresponding to the current token/provider
AltcraftSDK.pushSubscriptionFunctions.getStatusForCurrentSubscription(context)

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

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

// Status of the latest subscription for the provider (if null — the current one is used)
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
        }
}

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

AltcraftSDK
└─ val pushSubscriptionFunctions: PublicPushSubscriptionFunctions
   // Subscribe (status = 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
   // Suspend (status = 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
   // Unsubscribe (status = 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: "c52b28d2"
           ├─ provider: "ios-apns"
           ├─ status: "subscribed"
           ├─ fields
           │  ├─ _os_ver: {"raw":"18.6.2","ver":"[\"18.0\", \"6.0\", \"2.0\"]"}
           │  ├─ _device_type: "Mobile"
           │  ├─ _ad_track: false
           │  ├─ _device_name: "iPhone"
           │  ├─ _os_language: "en"
           │  ├─ _os_tz: "+0300"
           │  ├─ _os: "IOS"
           │  └─ _device_model: "iPhone14,7"
           └─ cats
              └─ [ { name: "developer_news", title: "dev_news", steady: false, active: false } ]

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

  • httpCode – транспортный код ответа;

  • Response – public struct, содержащий:

    • error: Int? — внутренний код ошибки сервера (0, если ошибок нет),

    • errorText: String? — текст ошибки (пустая строка, если ошибок нет),

    • profile: ProfileData? — данные профиля, если запрос успешный:

      • информация о профиле (ProfileData)
      • подписка (SubscriptionData)
      • категории подписки (CategoryData)
      • если запрос завершился с ошибкой, то вернется только profile = null
Структуры данных
public struct Response {
    let error: Int?        // internal error code
    let errorText: String? // error text
    let profile: ProfileData?
}

public struct ProfileData {
    let subscription: SubscriptionData?
    let cats: [CategoryData]?
}

public struct SubscriptionData {
    // Subscription Data
}

public struct CategoryData {
    // Subscription Category Data
}
Если sync == false
ResponseWithHttpCode
  ├─ httpCode: Int?
  └─ response: Response?
      ├─ error: Int?
      ├─ errorText: String?
      └─ profile: ProfileData? = null

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

  • httpCode – транспортный код ответа;

  • Response – public struct, содержащий:

    • error: Int? — внутренний код ошибки сервера (0, если ошибок нет),
    • errorText: String? — текст ошибки (пустая строка, если ошибок нет),
    • profile: ProfileData? — данные профиля, для асинхронного запроса всегда равен null.

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

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

  • 430 – ошибка без автоматического повтора на стороне SDK;
  • 530 – ошибка с автоматическим повтором на стороне SDK.

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

  • только httpCode, если сервер Altcraft был недоступен;
  • error и errorText, если сервер вернул ошибку.
Получение значений событий push
AltcraftSDK.eventSDKFunctions.subscribe { event ->
    if (event.eventCode in listOf(230, 430, 530)) {
        (event.eventValue?.get("response_with_http_code")
                as? DataClasses.ResponseWithHttpCode)?.let { responseWithHttp ->

            // HTTP code
            val httpCode = responseWithHttp.httpCode

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

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

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

            // Fields (Map<String, JsonElement>)
            val fields = subscription?.fields

            // Cats (List<CategoryData>)
            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? = null,
    val title: String? = null,
    val steady: Boolean? = null,
    val active: Boolean? = null
)

При отправке 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 change before request
    setAuth(context, logIn)

    AltcraftSDK.pushSubscriptionFunctions
        .unSuspendPushSubscription(context)
        ?.let { result ->
            if (result.httpCode == 200 && result.response?.profile?.subscription == null) {
                AltcraftSDK.pushSubscriptionFunctions.pushSubscribe(
                    context = context
                    // specify the required parameters
                )
            }
        }
}

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

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

AltcraftSDK
└── val pushTokenFunctions: PublicPushTokenFunctions
    |
    // Manually save the token (onNewToken)
    ├── fun setPushToken(context: Context, provider: String, token: String): Unit
    |
    // Get current device token data
    ├── suspend fun getPushToken(context: Context): DataClasses.TokenData?
    |
    // Set the Firebase Cloud Messaging provider (null — remove)
    ├── fun setFCMTokenProvider(provider: FCMInterface?): Unit
    |
    // Set the Huawei Mobile Services provider (null — remove)
    ├── fun setHMSTokenProvider(provider: HMSInterface?): Unit
    |
    // Set the RuStore provider (null — remove)
    ├── fun setRuStoreTokenProvider(provider: RustoreInterface?): Unit
    |
    // Delete the push token of the specified provider
    ├── suspend fun deleteDeviceToken(context: Context, provider: String, complete: () -> Unit): Unit
    |
    // Force token update (remove → update)
    ├── fun forcedTokenUpdate(context: Context, complete: () -> Unit): Unit
    |
    // Change a provider priority list and initiate token update
    └── 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.

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

// Manually save the token (onNewToken)
AltcraftSDK.pushTokenFunctions.setPushToken(context, provider, token)

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

class FCMService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        super.onNewToken(token)
        
        // Manually pass new 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.

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

// Get the current push token data
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.

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

// Set the Firebase Cloud Messaging provider (null — remove)
AltcraftSDK.pushTokenFunctions.setFCMTokenProvider(FCMProvider())
Важно

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

fun setHMSTokenProvider(provider: HMSInterface?): Unit

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

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

// Set the Huawei Mobile Services provider (null — remove)
AltcraftSDK.pushTokenFunctions.setHMSTokenProvider(HMSProvider())
Важно

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

fun setRuStoreTokenProvider(provider: RustoreInterface?): Unit

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

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

// Set the RuStore provider (null — remove)
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).

// Apply a new provider priority list and initiate token update
AltcraftSDK.pushTokenFunctions.changePushProviderPriorityList(context, listOf(HMS_PROVIDER, RUSTORE_PROVIDER, FCM_PROVIDER))

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

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

// Delete the push token of the specified provider (invalidated locally and on the server)
AltcraftSDK.pushTokenFunctions.deleteDeviceToken(context, provider) {
    // callback after removing
}

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

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

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

// Force token update (delete → update)
AltcraftSDK.pushTokenFunctions.forcedTokenUpdate(context) {
    // callback after removing
}

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

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

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

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

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

AltcraftSDK
└── open class PushReceiver
    // Processing an incoming push message
    ├── open fun pushHandler(
    │       context: Context, 
    │       message: Map<String, String>
    │   ): Unit
    // Entry point for push delivery into the SDK
    └── 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 — message 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>) {
        // standart push message handling and notification display
        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, // application package
   "com.altcraft.altcraftmobile.test" 
)

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

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

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

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

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

AltcraftSDK
└── val pushEventFunction: 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 полезные данные уведомления.

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

// Зафиксировать доставку Altcraft-push (вызывает delivery-ивент)
AltcraftSDK.pushEventFunction.deliveryEvent(context, message, uid)

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

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

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

// Зафиксировать открытие Altcraft-push (вызывает open-ивент)
AltcraftSDK.pushEventFunction.openEvent(context, message, uid)

Очистка данных 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" — changing field
    // .set("Andrey") — a command that will set the value "Andrey" for this field
    profileFields = AltcraftSDK.pushSubscriptionFunctions
        .actionField("_fname").set("Andrey")
)

Сброс запрета на повтор performPushModuleCheck()​

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

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

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

fun reinitializePushModuleInThisSession(): Unit

Функция сбрасывает флаг запрета на повторное выполнение performPushModuleCheck().

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

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

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

fun requestNotificationPermission(context: Context, activity: ComponentActivity)

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

Последнее обновление