Публичный API SDK

class AltcraftSDK

AltcraftSDK
// Синглтон точка входа в SDK
├─ public static let shared: AltcraftSDK
// Инициализация SDK конфигурацией (completion вызывается на main)
├─ public func initialization(configuration: AltcraftConfiguration?, completion: ((Bool) -> Void)? = nil): Void
// Установка App Group и инициализация Core Data под shared-контейнер
├─ public func setAppGroup(groupName: String): Void
// Регистрация JWT-провайдера для получения токенов
├─ public func setJWTProvider(provider: JWTInterface): Void
// Полная очистка данных SDK (кэш/БД/настройки), затем вызов completion
├─ public func clear(completion: (() -> Void)? = nil): Void
| 
// Поток SDK-событий (один активный подписчик)
├─ public let eventSDKFunctions: SDKEvents
│  // Подписаться на события SDK (заменяет существующего подписчика)
│  ├─ func subscribe(callback: @escaping (Event) -> Void): Void
│  // Отписаться от событий (колбэк остаётся назначенным, доставка останавливается)
│  ├─ func unsubscribe(): Void
│  // Модель события (базовый тип для всех событий/ошибок)
│  ├─ Event
│  │   // Базовая модель события
│  │   id: UUID
│  │   function: String
│  │   message: String?
│  │   eventCode: Int?
│  │   value: [String: Any?]?
│  │   date: Date
│  │   // Конструктор (нормализация function, фильтрация nil в value)
│  │   init(function: String, message: String? = nil, eventCode: Int? = nil, value: [String: Any?]? = nil, date: Date = Date())
│  │   // Сравнение по уникальному id
│  │   static func ==(lhs: Event, rhs: Event) -> Bool
│  │   // Хеширование по id
│  │   func hash(into hasher: inout Hasher): Void
│  │
│  │   // Ошибки без повторов (4xx-класс)
│  │   ErrorEvent : Event
│  │   init(function: String, message: String? = nil, eventCode: Int? = nil, value: [String: Any?]? = nil, date: Date = Date())
│  │
│  │   // Повторяемые ошибки (обычно 5xx)
│  │   RetryEvent : ErrorEvent
│  │   init(function: String, message: String? = nil, eventCode: Int? = 0, value: [String: Any?]? = nil, date: Date = Date())
| 
// Управление push-токенами и провайдерами (FCM/HMS/APNs)
├─  public let pushTokenFunction: PublicPushTokenFunctions
│  // Установить провайдера Firebase Cloud Messaging (nil — снять)
│  ├─ public func setFCMTokenProvider(_ provider: FCMInterface?): Void
│  // Установить провайдера Huawei Mobile Services (nil — снять)
│  ├─ public func setHMSTokenProvider(_ provider: HMSInterface?): Void
│  // Установить провайдера Apple Push Notification service (nil — снять)
│  ├─ public func setAPNSTokenProvider(_ provider: APNSInterface?): Void
│  // Асинхронно получить текущий push-токен (completion опционален)
│  ├─ public func getPushToken(completion: ((TokenData?) -> Void)? = nil): Void
│  // Сохранить токен вручную (String для FCM/HMS, Data для APNs); provider: "ios-firebase" | "ios-huawei" | "ios-apns"
│  ├─ public func setPushToken(provider: String, pushToken: Any?): Void
│  // Применить новый приоритет провайдеров и инициировать обновление токена
│  ├─ public func changePushProviderPriorityList(_ list: [String]): Void
│  // Удалить токен выбранного провайдера и вызвать completion
│  ├─ public func deleteDeviceToken(provider: String, completion: @escaping () -> Void): Void
│  // Форсировать обновление токена (определить провайдера —> удалить (кроме APNs) —> запросить новый)
│  └─ public func forcedTokenUpdate(completion: (() -> Void)? = nil): Void
| 
// Управление подпиской на push (изменение статуса, запросы статуса)
├─  public let pushSubscriptionFunctions: PublicPushSubscriptionFunctions
│  // Оформить подписку (status = SUBSCRIBED)
│  ├─ public func pushSubscribe(
│  │     sync: Bool = true,
│  │     profileFields: [String: Any?]? = nil,
│  │     customFields: [String: Any?]? = nil,
│  │     cats: [CategoryData]? = nil,
│  │     replace: Bool? = nil,
│  │     skipTriggers: Bool? = nil
│  │   ): Void
│  // Отписаться (status = UNSUBSCRIBED)
│  ├─ public func pushUnSubscribe(
│  │     sync: Bool = true,
│  │     profileFields: [String: Any?]? = nil,
│  │     customFields: [String: Any?]? = nil,
│  │     cats: [CategoryData]? = nil,
│  │     replace: Bool? = nil,
│  │     skipTriggers: Bool? = nil
│  │   ): Void
│  // Приостановить (status = SUSPENDED)
│  ├─ public func pushSuspend(
│  │     sync: Bool = true,
│  │     profileFields: [String: Any?]? = nil,
│  │     customFields: [String: Any?]? = nil,
│  │     cats: [CategoryData]? = nil,
│  │     replace: Bool? = nil,
│  │     skipTriggers: Bool? = nil
│  │   ): Void
│  // UnSuspend подписки (один запрос, без ретраев/персиста)
│  ├─ public func unSuspendPushSubscription(
│  │     completion: @escaping (ResponseWithHttp?) -> Void
│  │   ): Void
│  // Статус последней подписки профиля
│  ├─ public func getStatusOfLatestSubscription(
│  │     completion: @escaping (ResponseWithHttp?) -> Void
│  │   ): Void
│  // Статус подписки, соответствующий текущим токену/провайдеру
│  ├─ public func getStatusForCurrentSubscription(
│  │     completion: @escaping (ResponseWithHttp?) -> Void
│  │   ): Void
│  // Статус последней подписки по провайдеру (если nil — используется текущий)
│  └─ public func getStatusOfLatestSubscriptionForProvider(
│  │       provider: String? = nil,
│  │       completion: @escaping (ResponseWithHttp?) -> Void
│  │     ): Void
|   // добавить функциональное поле профиля(set/incr/...)
|  └─ public func actionField(key: String) -> ActionFieldBuilder
|
| // Регистрация мобильных событий
├─ public let mobileEventFunctions: PublicMobileEventFunctions
│  // Регистрирует мобильное событие Altcraft
│  └─ public func mobileEvent(
│        sid: String,
│        altcraftClientID: String = "",
│        eventName: String,
│        sendMessageId: String? = nil,
│        payload: [String: Any?]? = nil,
│        matching: [String: Any?]? = nil,
│        matchingType: String? = nil,
│        profileFields: [String: Any?]? = nil,
│        subscription: (any Subscription)? = nil,
│        utm: UTM? = nil
│     ): Void
|
| // Обновление полей профиля
├─ public let profileFunctions: PublicProfileFunctions
│  // Обновляет поля профиля Altcraft
│  └─ public func updateProfileFields(
│        profileFields: [String: Any?]? = nil,
│        skipTriggers: Bool? = nil
│     ): Void
| 
// ручная отправка пуш-событий (delivery/open)
├─  public let  pushEventFunctions: PublicPushEventFunctions
│  // Зафиксировать доставку Altcraft-push (вызывает delivery-ивент)
│  ├─ public func deliveryEvent(from request: UNNotificationRequest): Void
│  // Зафиксировать открытие Altcraft-push (вызывает open-ивент)
│  └─ public func openEvent(from request: UNNotificationRequest): Void
| 
// Регистрация периодических фоновых задач (BGAppRefreshTask)
├─ public let backgroundTasks: BackgroundTasks
│  // Зарегистрировать задачу и запланировать периодический запуск (~каждые 3 часа)
│  └─ public func registerBackgroundTask(): Void
| 
// Управление нотификациями в приложении (делегат центра уведомлений)
├─  public let notificationManager: NotificationManager
   // Синглтон NotificationManager (точка доступа к менеджеру уведомлений)
   ├─ public static let shared: NotificationManager
   // ObjC-friendly аксессор (эквивалент shared)
   ├─ public class func sharedInstance() -> NotificationManager
   //
   // NotificationCenter events (SDK posts these)
   ├─ public extension Notification.Name
   │  // Fired when a notification is about to be presented in foreground.
   │  // userInfo: ["notification": UNNotification]
   │  ├─ static let altcraftPushWillPresent: Notification.Name
   │  // Fired when user taps on a delivered notification or performs an action.
   │  // userInfo: ["response": UNNotificationResponse]
   │  └─ static let altcraftPushDidReceive: Notification.Name
   //
   // Режимы делегирования обработки приложению
   ├─ public var customPushProcessing: Bool
   ├─ public var customClickProcessing: Bool
   //
   // Колбэки для кастомной обработки
   │  // Called when a foreground push arrives.
   │  // App must call completion when customPushProcessing = true.
   ├─ public var onForegroundNotification: ((UNNotification, @escaping (UNNotificationPresentationOptions) -> Void) -> Void)?
   │  // Called when the user taps a notification (or performs an action).
   │  // App must call completion when customClickProcessing = true.
   ├─ public var onNotificationClick: ((UNNotificationResponse, @escaping () -> Void) -> Void)?
   //
   // Регистрация на push (delegate + requestAuthorization + registerForRemoteNotifications)
   ├─ func registerForPushNotifications(for application: UIApplication, completion: ((_ granted: Bool, _ error: Error?) -> Void)? = nil): Void
   //
   // UNUserNotificationCenterDelegate
   │  // Постит altcraftPushWillPresent; при customPushProcessing отдаёт решение приложению,
   │  // иначе показывает banner/alert (+ badge/sound)
   ├─ public func userNotificationCenter(
   │     _ center: UNUserNotificationCenter,
   │     willPresent notification: UNNotification,
   │     withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
   │   ): Void
   │  // Постит altcraftPushDidReceive; при customClickProcessing отдаёт обработку приложению,
   │  // иначе парсит userInfo, шлёт open event и выполняет action; затем вызывает completionHandler
   └─ public func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
      ): Void

class AltcraftNSE

// Используется внутри Notification Service Extension (NSE) — отвечает за обработку push-уведомлений Altcraft,
// определение уведомлений Altcraft и регистрацию мобильных событий без зависимости от UIApplication
AltcraftNSE
// Общий (singleton) экземпляр для централизованной логики NSE
├─ public static let shared: AltcraftNSE
// Предоставляет доступ к API регистрации мобильных событий
├─ public let mobileEventFunctions: PublicMobileEventFunctions
// Регистрирует мобильное событие Altcraft
├─ public func mobileEvent(
│     sid: String,
│     altcraftClientID: String = "",
│     eventName: String,
│     sendMessageId: String? = nil,
│     payload: [String: Any?]? = nil,
│     matching: [String: Any?]? = nil,
│     matchingType: String? = nil,
│     profileFields: [String: Any?]? = nil,
│     subscription: (any Subscription)? = nil,
│     utm: UTM? = nil
│  ): Void
// Обновляет поля профиля Altcraft
├─ public func updateProfileFields(
│     profileFields: [String: Any?]? = nil,
│     skipTriggers: Bool? = nil
│  ): Void
// Проверяет, относится ли уведомление к Altcraft
├─ public func isAltcraftPush(_ request: UNNotificationRequest) -> Bool
// Обрабатывает входящее уведомление Altcraft и передаёт изменённое содержимое в contentHandler
├─ public func handleNotificationRequest(
│     request: UNNotificationRequest,
│     contentHandler: @escaping (UNNotificationContent) -> Void
│  ): Void
// Вызывается системой при истечении времени выполнения NSE
├─ public func serviceExtensionTimeWillExpire(): Void
// Устанавливает App Group и инициализирует общий контейнер данных
├─ public func setAppGroup(groupName: String): Void
// Регистрирует JWT-провайдер для безопасной работы с токенами
└─ public func setJWTProvider(provider: JWTInterface): Void

class AltcraftConfiguration

AltcraftConfiguration
// Класс конфигурации Altcraft SDK.
// Хранит базовый API URL и опциональные параметры (rToken, AppInfo, providerPriorityList, enableLogging).
// Создаётся только через Builder. ObjC-совместим: AltcraftConfiguration / AltcraftConfiguration_Builder.
│ 
├─ @objc(AltcraftConfiguration_Builder) public final class Builder
│  // Builder для формирования конфигурации с валидацией.
│  // Позволяет задать обязательные и опциональные поля и собрать объект конфигурации.
│  // Конструктор билдера
│  ├─ public override init()
│  // Задать API URL (обязательный параметр)
│  ├─ @discardableResult public func setApiUrl(_ url: String) -> Builder
│  // Задать ресурсный токен (опционально)
│  ├─ @discardableResult public func setRToken(_ rToken: String?) -> Builder
│  // Задать метаданные приложения (Swift-модель AppInfo) (опционально)
│  ├─ @discardableResult public func setAppInfo(_ info: AppInfo?) -> Builder
│  // Задать метаданные приложения (ObjC DTO AppInfoObjC) (опционально, Swift недоступно)
│  ├─ @available(swift, obsoleted: 1) @objc(setAppInfo:) @discardableResult public func setAppInfo(_ dto: AppInfoObjC?) -> Builder
│  // Задать приоритет провайдеров пуш-уведомлений (опционально)
│  ├─ @discardableResult public func setProviderPriorityList(_ list: [String]?) -> Builder
│  // Управление внутренним логированием SDK (опционально)
│  // true — включить, false — выключить, nil — оставить поведение по умолчанию
│  ├─ @discardableResult public func setEnableLogging(_ enabled: Bool?) -> Builder
│  // Построить валидную конфигурацию (nil, если валидация не пройдена)
│  // Валидация: apiUrl не пустой; providerPriorityList валиден; appInfo резолвится (Swift AppInfo приоритетнее, иначе AppInfoObjC -> AppInfo)
│  └─ public func build() -> AltcraftConfiguration?
// Доступ к параметрам конфигурации
├─ public func getApiUrl() -> String
├─ public func getRToken() -> String?
├─ public func getAppInfo() -> AppInfo?
├─ public func getEnableLogging() -> Bool?
└─ public func getProviderPriorityList() -> [String]?

Structures

/// Хранит push-токен и имя провайдера.
public struct TokenData: Codable {
    public let provider: String
    public let token: String
}

/// Метаданные приложения для Firebase Analytics (если используется).
public struct AppInfo: Codable {
    public var appID: String
    public var appIID: String
    public var appVer: String
}

/// Обёртка ответа API с HTTP-кодом.
public struct ResponseWithHttp {
    public let httpCode: Int?
    public let response: Response?
}

/// Ответ синхронного запроса подписки.
public struct Response: Codable {
    public let error: Int?
    public let errorText: String?
    public let profile: ProfileData?
}

/// Данные профиля пользователя.
public struct ProfileData: Codable {
    public let id: String?
    public let status: String?
    public let isTest: Bool?
    public let subscription: SubscriptionData?
}

/// Текущая подписка профиля.
public struct SubscriptionData: Codable {
    public let subscriptionId: String?
    public let hashId: String?
    public let provider: String?
    public let status: String?
    public let fields: [String: JSONValue]?
    public let cats: [CategoryData]?
}

/// Категория подписки (имя/заголовок/флаги).
public struct CategoryData: Codable {
    public var name: String?
    public var title: String?
    public var steady: Bool?
    public var active: Bool?
}

/// Подписка канала Email (мобильные события).
public struct EmailSubscription: Subscription, Codable {
    public let resourceId: Int
    public let email: String
    public let status: String?
    public let priority: Int?
    public let customFields: [String: JSONValue]?
    public let cats: [String]?
    public let channel: String = "email"
}

/// Подписка канала SMS (мобильные события).
public struct SmsSubscription: Subscription, Codable {
    public let resourceId: Int
    public let phone: String
    public let status: String?
    public let priority: Int?
    public let customFields: [String: JSONValue]?
    public let cats: [String]?
    public let channel: String = "sms"
}

/// Подписка push-канала (мобильные события).
public struct PushSubscription: Subscription, Codable {
    public let resourceId: Int
    public let provider: String
    public let subscriptionId: String
    public let status: String?
    public let priority: Int?
    public let customFields: [String: JSONValue]?
    public let cats: [String]?
    public let channel: String = "push"
}

/// Подписка с cc_data (Telegram, WhatsApp, Viber, Notify).
public struct CcDataSubscription: Subscription, Codable {
    public let resourceId: Int
    public let channel: String
    public let ccData: [String: JSONValue]
    public let status: String?
    public let priority: Int?
    public let customFields: [String: JSONValue]?
    public let cats: [String]?
}

/// UTM-параметры для мобильных событий.
public struct UTM: Codable {
    public let campaign: String?
    public let content: String?
    public let keyword: String?
    public let medium: String?
    public let source: String?
    public let temp: String?
}

Protocols

JWTInterface:

JWTInterface
// Доступ к текущему JWT
└─ func getToken() -> String?
   // Возвращает текущий JWT или nil

APNSInterface:

APNSInterface
// Контракт получения APNs-токена
└─ func getToken(completion: @escaping (String?) -> Void)
   // Возвращает APNs-токен через completion или nil

FCMInterface:

FCMInterface
// Контракт операций с FCM-токеном (получение/отзыв)
├─ func getToken(completion: @escaping (String?) -> Void)
│  // Возвращает FCM-токен через completion или nil
└─ func deleteToken(completion: @escaping (Bool) -> Void)
   // Удаляет FCM-токен; completion(true|false)

HMSInterface:

HMSInterface
// Контракт операций с HMS-токеном
├─ func getToken(completion: @escaping (String?) -> Void)
│  // Возвращает HMS-токен через completion или nil
└─ func deleteToken(completion: @escaping (Bool) -> Void)
   // Удаляет HMS-токен; completion(true|false)

Subscription:

Subscription (protocol)
// Базовый протокол для всех типов подписок передаваемых с мобильным событием