Функционал SDK

tip

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

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

---

// Object Events functions

AltcraftSDK
// Singleton, the entry point to the SDK
└── static let shared: AltcraftSDK
    // SDK event stream (one active subscriber)
    └── eventSDKFunctions: SDKEvents
        // Subscribe to SDK events (replaces the existing subscriber)
        ├── subscribe(
        │       callback: @escaping (Event) -> Void
        │   ): Void
        // Unsubscribe from events (the callback remains assigned, delivery stops)
        └── unsubscribe(): Void

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

---

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

public func subscribe(callback: @escaping (Event) -> Void): Void

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

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

AltcraftSDK.shared.eventSDKFunctions.subscribe { event in
  // event
}

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

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

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

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

События SDK

open class Event: Hashable {
    public let id = UUID()
    public let function: String
    public let message: String?
    public let eventCode: Int?
    public let value: [String: Any?]?
    public let date: Date
}

open class ErrorEvent: Event {
    public override init(
        function: String,
        message: String? = nil,
        eventCode: Int? = nil,
        value: [String: Any?]? = nil,
        date: Date = Date()
    ) {
        super.init(
            function: function,
            message: message,
            eventCode: eventCode,
            value: value,
            date: date
        )
    }
}

public class RetryEvent: ErrorEvent {
    public override init(
        function: String,
        message: String? = nil,
        eventCode: Int? = 0,
        value: [String: Any?]? = nil,
        date: Date = Date()
    ) {
        super.init(
            function: function,
            message: message,
            eventCode: eventCode,
            value: value,
            date: date
        )
    }
}

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

├─ function: processResponse
├─ eventCode: 230
├─ message: "successful request: push/subscribe"
├─ value
│  ├─ http code: 200
│  └─ response
│     ├─ error: 0
│     ├─ errorText: ""
│     └─ profile
│        ├─ id: // profile ID
│        ├─ status: subscribed
│        ├─ isTest: false
│        └─ subscription
│           ├─ subscriptionId: // subscription push token
│           ├─ hashId: // ID hash
│           ├─ provider: "ios-apns"
│           ├─ status: subscribed
│           ├─ fields
│           │  ├─ _ad_id: // google service ad id 
│           │  ├─ _ad_track: false
│           │  ├─ _app_id: "AltcraftMobile"
│           │  ├─ _app_iid: "1.0.0"
│           │  ├─ _app_ver: {"raw":"1.0.0","ver":[1,0]}
│           │  ├─ _device_model: "iPhone14,7"
│           │  ├─ _device_name: "iPhone"
│           │  ├─ _device_type: "mob"
│           │  ├─ _os: "Android"
│           │  ├─ _os_language: "ru"
│           │  ├─ _os_tz: "+0300"
│           │  └─ _os_ver: {"raw":"18.6.2","ver":"[\"18.0\", \"6.0\", \"2.0\"]"}
│           └─ cats
│              └─ [ { name: "cats_1", title: "cats_1", steady: false, active: false } ]
└─ date: Tue Aug 12 15:49:20 GMT+03:00 2025

---

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

public func unsubscribe(): Void

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

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

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

---

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

---

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

AltcraftSDK
//   Singleton, the entry point to the SDK
└── static let shared: AltcraftSDK
    // Subscription managment
    └── pushSubscriptionFunctions: PublicPushSubscriptionFunctions
        // Last profile subscription status
        ├── getStatusOfLatestSubscription(
        │       completion: @escaping (ResponseWithHttp?) -> Void
        │   ): Void
        // Subscription status corresponding to the current token/provider
        ├── getStatusForCurrentSubscription(
        │       completion: @escaping (ResponseWithHttp?) -> Void
        │   ): Void
        // Status of the latest subscription for the provider (if nil — the current one is used)
        └── getStatusOfLatestSubscriptionForProvider(
                provider: String? = nil,
                completion: @escaping (ResponseWithHttp?) -> Void
            ): Void

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

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

---

public func getStatusOfLatestSubscription(completion: @escaping (ResponseWithHttp?) -> Void): Void

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

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

// Last profile subscription status
AltcraftSDK.shared.pushSubscriptionFunctions.getStatusOfLatestSubscription(completion: @escaping (ResponseWithHttp?) -> Void)

---

public func getStatusForCurrentSubscription(completion: @escaping (ResponseWithHttp?) -> Void): Void

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

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

// Subscription status corresponding to the current token/provider
AltcraftSDK.shared.pushSubscriptionFunctions.getStatusForCurrentSubscription(completion: @escaping (ResponseWithHttp?) -> Void)

---

public func getStatusOfLatestSubscriptionForProvider(provider: String? = nil, completion: @escaping (ResponseWithHttp?) -> Void): Void

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

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

// Status of the latest subscription for the provider (if nil — the current one is used)
AltcraftSDK.shared.pushSubscriptionFunctions.getStatusOfLatestSubscriptionForProvider(provider: String? = nil, completion: @escaping (ResponseWithHttp?) -> Void)

---

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

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

AltcraftSDK.shared.pushSubscriptionFunctions.getStatusForCurrentSubscription{ responseWithHttp in
    // HTTP code
    let httpCode = responseWithHttp?.httpCode
            
    // Response
    let response = responseWithHttp?.response
    let error = response?.error
    let errorText = response?.errorText
            
    // Profile
    let profile = response?.profile
    let profileId = profile?.id
    let profileStatus = profile?.status
    let profileIsTest = profile?.isTest
            
    // Subscription
    let subscription = profile?.subscription
    let subscriptionId = subscription?.subscriptionId
    let hashId = subscription?.hashId
    let provider = subscription?.provider
    let subscriptionStatus = subscription?.status
            
    // Fields (dictionary [String: JSONValue])
    let fields = subscription?.fields
            
    // Cats (array of CategoryData)
    let cats = subscription?.cats
            
    // CategoryData (every element of cats array)
    let firstCat = cats?.first
    let catName = firstCat?.name
    let catTitle = firstCat?.title
    let catSteady = firstCat?.steady
    let catActive = firstCat?.active
}

В случае успешно выполненного запроса будет создано событие с кодом 234. В случае ошибки — событие с кодом 434.

---

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

AltcraftSDK
//   Singleton, the entry point to the SDK
└── static let shared: AltcraftSDK
    // Push subscription managment
    └── pushSubscriptionFunctions: PublicPushSubscriptionFunctions
        // Subscribe (status = SUBSCRIBED)
        ├── pushSubscribe(
        │       sync: Bool = true,
        │       profileFields: [String: Any?]? = nil,
        │       customFields: [String: Any?]? = nil,
        │       cats: [CategoryData]? = nil,
        │       replace: Bool? = nil,
        │       skipTriggers: Bool? = nil
        │   ): Void
        // Unsubscribe (status = UNSUBSCRIBED)
        ├── pushUnSubscribe(
        │       sync: Bool = true,
        │       profileFields: [String: Any?]? = nil,
        │       customFields: [String: Any?]? = nil,
        │       cats: [CategoryData]? = nil,
        │       replace: Bool? = nil,
        │       skipTriggers: Bool? = nil
        │   ): Void
        // Suspend (status = SUSPENDED)
        └── pushSuspend(
                sync: Bool = true,
                profileFields: [String: Any?]? = nil,
                customFields: [String: Any?]? = nil,
                cats: [CategoryData]? = nil,
                replace: Bool? = nil,
                skipTriggers: Bool? = nil
            ): Void

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

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

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

---

sync: Bool

По умолчанию: 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 = nil

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

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? = nil

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

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

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

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

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

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

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

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

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

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

    AltcraftSDK.shared.eventSDKFunctions.subscribe { event in
        if event.eventCode == 230 {
            if let responseWithHttp = event.value?["response_with_http_code"] as? ResponseWithHttp {
            // HTTP code
            let httpCode = responseWithHttp.httpCode
            
            // Response
            let response = responseWithHttp.response
            let error = response?.error
            let errorText = response?.errorText
            
            // Profile
            let profile = response?.profile
            let profileId = profile?.id
            let profileStatus = profile?.status
            let profileIsTest = profile?.isTest
            
            // Subscription
            let subscription = profile?.subscription
            let subscriptionId = subscription?.subscriptionId
            let hashId = subscription?.hashId
            let provider = subscription?.provider
            let subscriptionStatus = subscription?.status
            
            // Fields (dictionary [String: JSONValue])
            let fields = subscription?.fields
            
            // Cats (array of CategoryData)
            let cats = subscription?.cats
            
            // CategoryData (every element of cats array)
            let firstCat = cats?.first
            let catName = firstCat?.name
            let catTitle = firstCat?.title
            let catSteady = firstCat?.steady
            let catActive = firstCat?.active
        }
    }
}

Поля fields, содержащиеся в subscription могут содержать ваши пользовательские поля подписки. Они имеют тип [String: JSONValue]?. public enum JSONValue содержит вспомогательные функции позволяющие упростить получение значений fields:

    public var stringValue: String? {
        if case let .string(value) = self { return value }
        return nil
    }

    /// Returns the numeric value if case is `.number`, otherwise `nil`.
    public var numberValue: Double? {
        if case let .number(value) = self { return value }
        return nil
    }

    /// Returns the bool value if case is `.bool`, otherwise `nil`.
    public var boolValue: Bool? {
        if case let .bool(value) = self { return value }
        return nil
    }

    /// Returns the object dictionary if case is `.object`, otherwise `nil`.
    public var objectValue: [String: JSONValue]? {
        if case let .object(value) = self { return value }
        return nil
    }

    /// Returns the array if case is `.array`, otherwise `nil`.
    public var arrayValue: [JSONValue]? {
        if case let .array(value) = self { return value }
        return nil
    }

Пример получения значения поля field "_device_name":

AltcraftSDK.shared.eventSDKFunctions.subscribe { event ->
    if event.eventCode == 230 {
        if let responseWithHttp = event.value?["response_with_http_code"] as? ResponseWithHttp {
            let response = responseWithHttp.response
            let profile = response?.profile
            let subscription = profile?.subscription
            
            // extract fields?["_device_name"] as a string value
            if let deviceName = subscription?.fields?["_device_name"]?.stringValue {
                    print(deviceName)
            }
        }     
    }
}

---

profileFields:[String: Any?]?

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

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

• String
• Bool
• Числа
• nil
• Объекты [String: Any]
• Массивы

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

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

---

customFields:[String: Any?]?

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

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

• String
• Bool
• Int
• Float
• Double
• nil

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

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:[CategoryData]?

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

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

public struct CategoryData: Codable {
    public var name: String?
    public var title: String?
    public var steady: Bool?
    public var active: Bool?
}

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

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

let cats: [CategoryData] = [CategoryData(name: "football", title: nil, steady: nil, active: true)]

Пример ответа:

[ { name: "developer_news", title: "dev_news", steady: false, active: false } ]

Категории используемые в запросе должны быть предварительно созданы и добавлены к ресурсу в платформе 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:Bool?

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

---

skipTriggers:Bool?

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

---

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

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

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

AltcraftSDK.shared.pushSubscriptionFunctions.pushSubscribe()

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

AltcraftSDK.shared.pushSubscriptionFunctions.pushSubscribe(
    sync: true,
    profileFields: ["_fname":"Andrey", "_lname":"Pogodin"],
    customFields:  ["developer":true],
    cats: [CategoryData(name: "developer_news", active: true)],
    replace: false,
    skipTriggers:  false
)

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

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

---

Функция unSuspendPushSubscription()

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

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

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

AltcraftSDK.shared.pushSubscriptionFunctions.unSuspendPushSubscription(completion: @escaping (ResponseWithHttp?) -> Void)

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

LogIn-переход:

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

LogOut-переход:

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

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

func logIn() {
    JWTManager.shared.setRegJWT()
    // JWT is set for an authorized user
    AltcraftSDK.shared.pushSubscriptionFunctions.unSuspendPushSubscription { result in
        if result?.httpCode == 200, result?.response?.profile?.subscription == nil {
            AltcraftSDK.shared.pushSubscriptionFunctions.pushSubscribe(
                // specify the required parameters
            )
        }
    }
}

func logOut() {
    JWTManager.shared.setAnonJWT()
    // JWT is set for an anonymous user
    AltcraftSDK.shared.pushSubscriptionFunctions.unSuspendPushSubscription { result in
        if result?.httpCode == 200, result?.response?.profile?.subscription == nil {
            AltcraftSDK.shared.pushSubscriptionFunctions.pushSubscribe(
                // specify the required parameters
            )
        }
    }
}

---

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

---

AltcraftSDK
//   Singleton, the entry point to the SDK
└── static let shared: AltcraftSDK
    // Managing push tokens and providers (FCM / HMS / APNs)
    └── pushTokenFunctions: PublicPushTokenFunctions
        // Manually save the token (String for FCM/HMS, Data for APNs)
        ├── setPushToken(
        │       provider: String,
        │       pushToken: Any?
        │   ): Void
        // Asynchronously retrieve the current push token (completion is optional)
        ├── getPushToken(
        │       completion: ((TokenData?) -> Void)? = nil
        │   ): Void
        // Set the Firebase Cloud Messaging provider (nil — remove)
        ├── setFCMTokenProvider(
        │       _ provider: FCMInterface?
        │   ): Void
        // Set the Huawei Mobile Services provider (nil — remove)
        ├── setHMSTokenProvider(
        │       _ provider: HMSInterface?
        │   ): Void
        // Set the Apple Push Notification service provider (nil — remove)
        ├── setAPNSTokenProvider(
        │       _ provider: APNSInterface?
        │   ): Void
        // Apply a new provider priority list and initiate token update
        ├── changePushProviderPriorityList(
        │       _ list: [String]
        │   ): Void
        // Delete the push token of the specified provider and call completion
        ├── deleteDeviceToken(
        │       provider: String,
        │       completion: @escaping () -> Void
        │   ): Void
        // Force token update 
        └── forcedTokenUpdate(
                completion: (() -> Void)? = nil
            ): Void

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

• func setPushToken() — ручная установка push-токена устройства и провайдера в UserDefaults;
• func getPushToken() — получение текущего push-токена;
• func setAPNSTokenProvider() — установка и снятие push-токена APNs;
• func setFCMTokenProvider() — установка и снятие push-токена FCM;
• func setHMSTokenProvider() — установка и снятие push-токена HSM;
• func changePushProviderPriorityList() — функция, позволяющая выполнить динамическую смену провайдера с обновлением push-токена подписки;
• func deleteDeviceToken() — удаление push-токена указанного провайдера;
• func forcedTokenUpdate() — удаление текущего push-токена с последующим обновлением.

---

public func setPushToken(provider: String, pushToken: Any?): Void

Функция предназначена для ручной установки push-токена устройства и провайдера в UserDefaults. Используется как упрощенный вариант передачи push-токена в SDK без реализации протоколов провайдеров.

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

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

// Manually save the token (String for FCM/HMS, Data for APNs)
AltcraftSDK.shared.pushTokenFunction.setPushToken(provider: String, pushToken: Any?)

---

public func getPushToken(completion: ((TokenData?) -> Void)? = nil): Void

Функция передает в completion объект TokenData(provider: String, token: String), содержащий текущий push-токен устройства и его провайдера. Если push-токен недоступен, в completion будет передано nil.

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

// Asynchronously retrieve the current push token (completion is optional)
AltcraftSDK.shared.pushTokenFunction.getPushToken(completion: ((TokenData?) -> Void)? = nil)

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

AltcraftSDK.shared.pushTokenFunction.getPushToken{ data in
    let provider = data?.provider
    let token = data?.token
}

---

public func setFCMTokenProvider(_ provider: FCMInterface?): Void

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

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

// Set the Firebase Cloud Messaging provider (nil — remove)
AltcraftSDK.shared.pushTokenFunction.setFCMTokenProvider(_ provider: FCMInterface?)

Важно

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

---

public func setHMSTokenProvider(_ provider: HMSInterface?): Void

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

// Set the Huawei Mobile Services provider (nil — remove)
AltcraftSDK.shared.pushTokenFunction.setHMSTokenProvider(_ provider: HMSInterface?)

Важно

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

---

public func setAPNSTokenProvider(_ provider: APNSInterface?): Void

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

// Set the Apple Push Notification service provider (nil — remove)
AltcraftSDK.shared.pushTokenFunction.setHMSTokenProvider(_ provider: APNSInterface?)

Важно

Вызывайте setAPNSTokenProvider() в AppDelegate.application(_:didFinishLaunchingWithOptions:) до вызова AltcraftSDK.initialization(). Это гарантирует регистрацию на старте процесса приложения, независимо от состояния жизненного цикла других компонентов и того, запущено приложение в foreground или background.

---

public func changePushProviderPriorityList(_ list: [String]): Void

Функция, позволяющая выполнить динамическую смену push-провайдера с обновлением токена подписки. Для этого необходимо передать новый массив с другим порядком провайдеров. Например: [Constants.ProviderName.firebase, Constants.ProviderName.apns, Constants.ProviderName.huawei].

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

// Apply a new provider priority list and initiate token update
AltcraftSDK.shared.pushTokenFunction.changePushProviderPriorityList(_ list: [String])

---

public func deleteDeviceToken(provider: String, completion: @escaping () -> Void): Void

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

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

// Delete the push token of the specified provider (invalidated locally and on the server)
AltcraftSDK.shared.pushTokenFunction.deleteDeviceToken(provider: String, completion: @escaping () -> Void)

---

public func forcedTokenUpdate(completion: (() -> Void)? = nil): Void

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

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

// Force token update (determine provider → delete (except APNs) → request new → update)
AltcraftSDK.shared.pushTokenFunction.forcedTokenUpdate(completion: (() -> Void)? = nil)

---

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

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

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

class AppDelegate: UIResponder, UIApplicationDelegate, MessagingDelegate, UNUserNotificationCenterDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let appGroup = "your appGroup id"
        
        AltcraftSDK.shared.setAppGroup(groupName: appGroup)
        AltcraftSDK.shared.backgroundTasks.registerBackgroundTask()
        AltcraftSDK.shared.setJWTProvider(provider: JWTProvider())
       
        //apns provider
        AltcraftSDK.shared.pushTokenFunction.setAPNSTokenProvider(APNSProvider())
        
        //fcm provider
        AltcraftSDK.shared.pushTokenFunction.setFCMTokenProvider(FCMProvider())
        
        //hms provider
        AltcraftSDK.shared.pushTokenFunction.setHMSTokenProvider(HMSProvider())
        
        AltcraftSDK.shared.notificationManager.registerForPushNotifications(for: application)
        
        let config = AltcraftConfiguration.Builder().setApiUrl("your api url").build()
        AltcraftSDK.shared.initialization(configuration: config)
        
        //other functions
        
        return true
    }
}   
    

---

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

---

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

AltcraftPushReceiver — публичный класс SDK для обработки входящих push-уведомлений. Он проверяет, относится ли уведомление к Altcraft, обрабатывает содержимое (включая rich-контент) и формирует итоговое уведомление для отображения пользователю.

// Used in the Notification Service Extension (NSE) — processing rich pushes (categories/buttons/media) with no dependencies on UIApplication
AltcraftPushReceiver       
// Verify that the push is from Altcraft (by the marker in userInfo)
├─ public func isAltcraftPush(_ request: UNNotificationRequest) -> Bool
// Process the incoming request: create categories/buttons, attach media, record delivery, and return the content to the NSE
├─ public func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void): Void
// Return the "best attempt" content on NSE timeout
└─ public func serviceExtensionTimeWillExpire(): Void

Функции класса AltcraftPushReceiver:

• func isAltcraftPush() — функция проверки источника уведомления;
• func didReceive() — функция, принимающая UNNotificationRequest из Notification Service Extension для его дальнейшей обработки на стороне SDK;
• func serviceExtensionTimeWillExpire() — функция, вызывающаяся по истечении времени работы Notification Service Extension (~30 секунд).

---

public func isAltcraftPush(_ request: UNNotificationRequest) -> Bool

Функция SDK, проверяющая, является ли источником уведомления Altcraft по маркеру в userInfo.

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

// Verify that the push is from Altcraft (by the marker in userInfo)
AltcraftPushReceiver().isAltcraftPush(_ request: UNNotificationRequest) -> Bool

---

public func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void): Void

Функция SDK, принимающая UNNotificationRequest из Notification Service Extension для его обработки на стороне SDK и дальнейшего показа уведомления.

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

// Process the incoming request: create categories/buttons, attach media, record delivery, and return the content to the NSE
AltcraftPushReceiver().didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void)

---

public func serviceExtensionTimeWillExpire()

Функция, которая вызывается системой по истечении времени работы Notification Service Extension (~30 секунд).

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

// Return the "best attempt" content on NSE timeout
AltcraftPushReceiver().serviceExtensionTimeWillExpire()

---

Вспомогательные функции

---

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

public func actionField(key: String) -> ActionFieldBuilder

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

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

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

// "_fname" — changing field
// .set("Andrey") — a command that will set the value "Andrey" for this field
AltcraftSDK.shared.pushSubscriptionFunctions.pushSubscribe(
    profileFields: AltcraftSDK.shared.pushSubscriptionFunctions.actionField(key: "_fname").set(value: "Andrey")
)

---

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

public func clear(completion: (() -> Void)? = nil): Void

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

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

// Full cleanup of SDK data (cache/DB/settings), then call completion
AltcraftSDK.shared. clear(completion: (() -> Void)? = nil)

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

---

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

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

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

// Object PublicPushEventFunctions functions

AltcraftSDK
//   Singleton, the entry point to the SDK
└── public static let shared: AltcraftSDK  
    // Ручная отправка push-событий (delivery / open)
    └── public let pushEventFunctions: PublicPushEventFunctions
        // Record delivery of an Altcraft push (triggers a delivery event)
        ├── public func deliveryEvent(from request: UNNotificationRequest): Void
        // Record opening of an Altcraft push (triggers an open event)
        └── public func openEvent(from request: UNNotificationRequest): Void

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

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

---

public func deliveryEvent(from request: UNNotificationRequest): Void

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

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

// Record delivery of an Altcraft push (triggers a delivery event)
AltcraftSDK.shared.pushEventFunctions.deliveryEvent(from: UNNotificationRequest)

---

public func openEvent(from request: UNNotificationRequest): Void

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

// Record opening of an Altcraft push (triggers an open event)
AltcraftSDK.shared.pushEventFunctions.openEvent(from: UNNotificationRequest)

---