Public SDK API

class AltcraftSDK

AltcraftSDK
// Singleton entry point to the SDK
├─ public static let shared: AltcraftSDK
// SDK initialization with configuration (completion is called on main)
├─ public func initialization(configuration: AltcraftConfiguration?, completion: ((Bool) -> Void)? = nil): Void
// Sets App Group and initializes Core Data for the shared container
├─ public func setAppGroup(groupName: String): Void
// Registers a JWT provider for token retrieval
├─ public func setJWTProvider(provider: JWTInterface): Void
// Completely clears SDK data (cache / DB / settings), then calls completion
├─ public func clear(completion: (() -> Void)? = nil): Void
| 
// SDK event stream (single active subscriber)
├─ public let eventSDKFunctions: SDKEvents
│  // Subscribe to SDK events (replaces the existing subscriber)
│  ├─ func subscribe(callback: @escaping (Event) -> Void): Void
│  // Unsubscribe from events (callback remains set, delivery stops)
│  ├─ func unsubscribe(): Void
│  // Event model (base type for all events and errors)
│  ├─ Event
│  │   // Base event model
│  │   id: UUID
│  │   function: String
│  │   message: String?
│  │   eventCode: Int?
│  │   value: [String: Any?]?
│  │   date: Date
│  │   // Initializer (normalizes function, filters nil values)
│  │   init(function: String, message: String? = nil, eventCode: Int? = nil, value: [String: Any?]? = nil, date: Date = Date())
│  │   // Equality by unique id
│  │   static func ==(lhs: Event, rhs: Event) -> Bool
│  │   // Hashing by id
│  │   func hash(into hasher: inout Hasher): Void
│  │
│  │   // Non-retryable errors (4xx class)
│  │   ErrorEvent : Event
│  │   init(function: String, message: String? = nil, eventCode: Int? = nil, value: [String: Any?]? = nil, date: Date = Date())
│  │
│  │   // Retryable errors (typically 5xx)
│  │   RetryEvent : ErrorEvent
│  │   init(function: String, message: String? = nil, eventCode: Int? = 0, value: [String: Any?]? = nil, date: Date = Date())
| 
// Push token and provider management (FCM / HMS / APNs)
├─  public let pushTokenFunction: PublicPushTokenFunctions
│  // Set Firebase Cloud Messaging provider (nil to remove)
│  ├─ public func setFCMTokenProvider(_ provider: FCMInterface?): Void
│  // Set Huawei Mobile Services provider (nil to remove)
│  ├─ public func setHMSTokenProvider(_ provider: HMSInterface?): Void
│  // Set Apple Push Notification service provider (nil to remove)
│  ├─ public func setAPNSTokenProvider(_ provider: APNSInterface?): Void
│  // Asynchronously get the current push token (completion optional)
│  ├─ public func getPushToken(completion: ((TokenData?) -> Void)? = nil): Void
│  // Manually save a token (String for FCM/HMS, Data for APNs); provider: "ios-firebase" | "ios-huawei" | "ios-apns"
│  ├─ public func setPushToken(provider: String, pushToken: Any?): Void
│  // Apply a new provider priority list and trigger token update
│  ├─ public func changePushProviderPriorityList(_ list: [String]): Void
│  // Delete a token for the selected provider and call completion
│  ├─ public func deleteDeviceToken(provider: String, completion: @escaping () -> Void): Void
│  // Force token update (resolve provider → delete token (except APNs) → request a new one)
│  └─ public func forcedTokenUpdate(completion: (() -> Void)? = nil): Void
| 
// Push subscription management (status changes, status requests)
├─  public let pushSubscriptionFunctions: PublicPushSubscriptionFunctions
│  // Subscribe (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
│  // Unsubscribe (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
│  // Suspend (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 subscription (single request, no retries / persistence)
│  ├─ public func unSuspendPushSubscription(
│  │     completion: @escaping (ResponseWithHttp?) -> Void
│  │   ): Void
│  // Status of the latest profile subscription
│  ├─ public func getStatusOfLatestSubscription(
│  │     completion: @escaping (ResponseWithHttp?) -> Void
│  │   ): Void
│  // Subscription status for the current token / provider
│  ├─ public func getStatusForCurrentSubscription(
│  │     completion: @escaping (ResponseWithHttp?) -> Void
│  │   ): Void
│  // Latest subscription status for a provider (current one if nil)
│  └─ public func getStatusOfLatestSubscriptionForProvider(
│  │       provider: String? = nil,
│  │       completion: @escaping (ResponseWithHttp?) -> Void
│  │     ): Void
|   // add a functional profile field (set / incr / ...)
|  └─ public func actionField(key: String) -> ActionFieldBuilder
| // Registering Mobile Events
├─ public let mobileEventFunctions: PublicMobileEventFunctions
│  // Registers an Altcraft mobile event
│  └─ 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
|
| // Updating Profile Fields
├─ public let profileFunctions: PublicProfileFunctions
│  // Updates Altcraft profile fields
│  └─ public func updateProfileFields(
│        profileFields: [String: Any?]? = nil,
│        skipTriggers: Bool? = nil
│     ): Void
| 
// Manual push event sending (delivery / open)
├─  public let  pushEventFunctions: PublicPushEventFunctions
│  // Register delivery of an Altcraft push (fires delivery event)
│  ├─ public func deliveryEvent(from request: UNNotificationRequest): Void
│  // Register opening of an Altcraft push (fires open event)
│  └─ public func openEvent(from request: UNNotificationRequest): Void
| 
// Periodic background task registration (BGAppRefreshTask)
├─ public let backgroundTasks: BackgroundTasks
│  // Register a task and schedule periodic execution (~every 3 hours)
│  └─ public func registerBackgroundTask(): Void
| 
// In-app notification management (notification center delegate)
├─  public let notificationManager: NotificationManager
   // NotificationManager singleton (entry point to the notification manager)
   ├─ public static let shared: NotificationManager
   // ObjC-friendly accessor (equivalent to 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
   //
   // App-level delegation modes
   ├─ public var customPushProcessing: Bool
   ├─ public var customClickProcessing: Bool
   //
   // Callbacks for custom handling
   │  // 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 registration (delegate + requestAuthorization + registerForRemoteNotifications)
   ├─ func registerForPushNotifications(for application: UIApplication, completion: ((_ granted: Bool, _ error: Error?) -> Void)? = nil): Void
   //
   // UNUserNotificationCenterDelegate
   │  // Posts altcraftPushWillPresent; if customPushProcessing is enabled,
   │  // delegates the decision to the app,
   │  // otherwise shows banner/alert (+ badge/sound)
   ├─ public func userNotificationCenter(
   │     _ center: UNUserNotificationCenter,
   │     willPresent notification: UNNotification,
   │     withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
   │   ): Void
   │  // Posts altcraftPushDidReceive; if customClickProcessing is enabled,
   │  // delegates handling to the app,
   │  // otherwise parses userInfo, sends an open event and performs the action,
   │  // then calls completionHandler
   └─ public func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
      ): Void

class AltcraftNSE

// Used inside the Notification Service Extension (NSE) — handles processing Altcraft push notifications,
// determining Altcraft notifications, and registering mobile events without relying on UIApplication
AltcraftNSE
// Shared (singleton) instance for centralized NSE logic
├─ public static let shared: AltcraftNSE
// Provides access to the mobile event registration API
├─ public let mobileEventFunctions: PublicMobileEventFunctions
// Registers an Altcraft mobile event
├─ 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
// Updates Altcraft profile fields
├─ public func updateProfileFields(
│     profileFields: [String: Any?]? = nil,
│     skipTriggers: Bool? = nil
│  ): Void
// Checks if the notification is related to Altcraft
├─ public func isAltcraftPush(_ request: UNNotificationRequest) -> Bool
// Processes the incoming Altcraft notification and passes the modified content to the contentHandler
├─ public func handleNotificationRequest(
│     request: UNNotificationRequest,
│     contentHandler: @escaping (UNNotificationContent) -> Void
│  ): Void
// Called by the system when the NSE execution time expires
├─ public func serviceExtensionTimeWillExpire(): Void
// Sets the App Group and initializes the shared data container
├─ public func setAppGroup(groupName: String): Void
// Registers a JWT provider for secure token handling
└─ public func setJWTProvider(provider: JWTInterface): Void

class AltcraftConfiguration

AltcraftConfiguration
// Altcraft SDK configuration class.
// Stores the base API URL and optional parameters (rToken, AppInfo, providerPriorityList, enableLogging).
// Created only via Builder. ObjC-compatible: AltcraftConfiguration / AltcraftConfiguration_Builder.
│ 
├─ @objc(AltcraftConfiguration_Builder) public final class Builder
│  // Builder for creating a configuration with validation.
│  // Allows setting required and optional fields and assembling the configuration object.
│  // Builder constructor
│  ├─ public override init()
│  // Set API URL (required)
│  ├─ @discardableResult public func setApiUrl(_ url: String) -> Builder
│  // Set resource token (optional)
│  ├─ @discardableResult public func setRToken(_ rToken: String?) -> Builder
│  // Set application metadata (Swift AppInfo model) (optional)
│  ├─ @discardableResult public func setAppInfo(_ info: AppInfo?) -> Builder
│  // Set application metadata (ObjC DTO AppInfoObjC) (optional, not available in Swift)
│  ├─ @available(swift, obsoleted: 1) @objc(setAppInfo:) @discardableResult public func setAppInfo(_ dto: AppInfoObjC?) -> Builder
│  // Set push provider priority list (optional)
│  ├─ @discardableResult public func setProviderPriorityList(_ list: [String]?) -> Builder
│  // SDK internal logging control (optional)
│  // true — enable, false — disable, nil — keep default behavior
│  ├─ @discardableResult public func setEnableLogging(_ enabled: Bool?) -> Builder
│  // Build a valid configuration (nil if validation fails)
│  // Validation: apiUrl is not empty; providerPriorityList is valid; appInfo resolves (Swift AppInfo has priority, otherwise AppInfoObjC -> AppInfo)
│  └─ public func build() -> AltcraftConfiguration?
// Access to configuration parameters
├─ public func getApiUrl() -> String
├─ public func getRToken() -> String?
├─ public func getAppInfo() -> AppInfo?
├─ public func getEnableLogging() -> Bool?
└─ public func getProviderPriorityList() -> [String]?

Structures

/// Stores a push token and provider name.
public struct TokenData: Codable {
    public let provider: String
    public let token: String
}

/// Application metadata for Firebase Analytics (if used).
public struct AppInfo: Codable {
    public var appID: String
    public var appIID: String
    public var appVer: String
}

/// API response wrapper with HTTP status code.
public struct ResponseWithHttp {
    public let httpCode: Int?
    public let response: Response?
}

/// Synchronous subscription request response.
public struct Response: Codable {
    public let error: Int?
    public let errorText: String?
    public let profile: ProfileData?
}

/// User profile data.
public struct ProfileData: Codable {
    public let id: String?
    public let status: String?
    public let isTest: Bool?
    public let subscription: SubscriptionData?
}

/// Current profile subscription.
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]?
}

/// Subscription category (name / title / flags).
public struct CategoryData: Codable {
    public var name: String?
    public var title: String?
    public var steady: Bool?
    public var active: Bool?
}

/// Email channel subscription (mobile events).
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 channel subscription (mobile events).
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 channel subscription (mobile events).
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"
}

/// Subscription with 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 parameters for mobile events.
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
// Access to the current JWT
└─ func getToken() -> String?
   // Returns the current JWT or nil

APNSInterface:

APNSInterface
// APNs token retrieval contract
└─ func getToken(completion: @escaping (String?) -> Void)
   // Returns the APNs token via completion or nil

FCMInterface:

FCMInterface
// Contract for FCM token operations (retrieve / revoke)
├─ func getToken(completion: @escaping (String?) -> Void)
│  // Returns the FCM token via completion or nil
└─ func deleteToken(completion: @escaping (Bool) -> Void)
   // Deletes the FCM token; completion(true|false)

HMSInterface:

HMSInterface
// Contract for HMS token operations
├─ func getToken(completion: @escaping (String?) -> Void)
│  // Returns the HMS token via completion or nil
└─ func deleteToken(completion: @escaping (Bool) -> Void)
   // Deletes the HMS token; completion(true|false)

Subscription:

Subscription (protocol)
// Base protocol for all subscription types passed with a mobile event