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

Публичный 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
| 
// ручная отправка пуш-событий (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
   // Назначить делегата, запросить разрешения и зарегистрироваться на remote notifications; completion вернёт granted/error
   ├─ func registerForPushNotifications(for application: UIApplication, completion: ((_ granted: Bool, _ error: Error?) -> Void)? = nil): Void
   // Показ уведомлений в форграунде (баннер/алерт + бейдж/звук)
   ├─ public func userNotificationCenter(
   │     _ center: UNUserNotificationCenter,
   │     willPresent notification: UNNotification,
   │     withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
   │   ): Void
   // Обработка взаимодействия пользователя (клик/действия), логирование open-ивента
   └─ 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 isAltcraftPush(_ request: UNNotificationRequest) -> Bool
// Обрабатывает входящее уведомление Altcraft и возвращает модифицированное содержимое
├─ public func handleNotificationRequest(
│     request: UNNotificationRequest,
│     contentHandler: @escaping (UNNotificationContent) -> Void
│  ): Void
// Вызывается при истечении времени работы NSE
├─ public func serviceExtensionTimeWillExpire(): Void
// Устанавливает идентификатор App Group и инициализирует Core Data в общем контейнере
├─ public func setAppGroup(groupName: String): Void
// Регистрирует провайдера JWT для безопасного управления токенами в Altcraft SDK
└─ public func setJWTProvider(provider: JWTInterface): Void

class AltcraftConfiguration

AltcraftConfiguration
// Класс конфигурации Altcraft SDK.
// Хранит базовый API URL и опциональные параметры (rToken, AppInfo, providerPriorityList).
// Создаётся только через Builder.
│ 
├─ public class Builder
│  // Builder для формирования конфигурации с валидацией.
│  // Позволяет задать обязательные и опциональные поля и собрать объект конфигурации.
│  // Конструктор билдера
│  ├─ public init(): Builder
│  // Задать API URL (обязательный параметр)
│  ├─ public func setApiUrl(_ url: String) -> Builder
│  // Задать ресурсный токен (опционально)
│  ├─ func setRToken(_ rToken: String?) -> Builder
│  // Задать метаданные приложения AppInfo используемые в Firebase Analytis
│  ├─ public public func setAppInfo(_ info: AppInfo?) -> Builder
│  // Задать приоритет провайдеров пуш-уведомлений (опционально)
│  ├─ public func setProviderPriorityList(_ list: [String]?) -> Builder
│  // Построить валидную конфигурацию (nil, если валидация не пройдена)
│  └─ public func build() -> AltcraftConfiguration?
// Доступ к параметрам конфигурации
├─ public func getApiUrl() -> String
├─ public func getRToken() -> String?
├─ public func getAppInfo() -> AppInfo?
└─ 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)
// Базовый протокол для всех типов подписок передаваемых с мобильным событием