Public SDK API

The SDK is built from modules: the required Core and the optional Push, Target, Profile, In-App. Each module is connected as a separate dependency and is accessed through the corresponding property of the AltcraftSDK.shared object:

AltcraftSDK.shared     // Core: initialization, authentication, events, clearing
AltcraftSDK.shared.authFunctions   // Core: user authentication
AltcraftSDK.shared.push      // Push: subscriptions, tokens, notifications
AltcraftSDK.shared.target    // Target: sending goals
AltcraftSDK.shared.profile   // Profile: profile fields
AltcraftSDK.shared.inApp     // In-App: campaigns and subscriptions

Core (required module)

class AltcraftSDK

AltcraftSDK
// Singleton — the SDK entry point
├─ static let shared: AltcraftSDK
// SDK initialization and configuration setup (completion is called on main)
├─ func initialization(
│     configuration: AltcraftConfiguration?,
│     completion: (@Sendable (Bool) -> Void)? = nil
│   ): Void
// Full cleanup of SDK data (cache, DB, settings), then calls completion
├─ func clear(completion: (() -> Void)? = nil): Void
// Set up App Group and initialize Core Data under the shared container
├─ func setAppGroup(groupName: String?): Void
// Register a JWT provider for obtaining tokens
├─ func setJWTProvider(provider: JWTInterface): Void
// Access to SDK events (single subscriber)
├─ let eventSDKFunctions: SDKEvents
// Access to user authentication
├─ let authFunctions: AuthAPI
// Register periodic background tasks (BGAppRefreshTask)
├─ let backgroundTasks: BackgroundTask
// Access to optional modules
├─ var push: Push
├─ var target: Target
├─ var profile: Profile
└─ var inApp: InApp

class AuthAPI

AuthAPI
// User authentication
├─ func authenticate(): Void
// User logout (restores the anonymous session)
└─ func logOut(): Void

class SDKEvents

SDKEvents
// Subscribe to SDK events (replaces the existing subscriber)
├─ func subscribe(callback: @escaping (Event) -> Void): Void
// Unsubscribe from SDK events
└─ func unsubscribe(): Void

CoreEvents — public events of the Core module

CoreEvents
// General SDK events
├─ configSet                  // SDK configuration is installed
├─ sdkCleared                 // SDK data has been cleared
├─ userLogOut                 // User logged out. Anonymous session started
├─ backgroundTaskRegister     // SDK background task is registered
├─ backgroundTaskCompleted    // SDK background task completed
// State and environment errors
├─ notAuthenticatedError      // user is not authenticated
├─ appGroupIsNotSet           // App Group name was not set
├─ coreDataError              // error in CoreData. Re-initialize the SDK
├─ permissionDenied           // notification permission denied
// Configuration errors
├─ invalidUrlValue            // invalid apiUrl value - empty or null
├─ invalidRTokenValue         // invalid resource token value - resource token is empty
├─ unsupportedSubscriptionType // unsupported subscription type
// Authentication errors
├─ jwtIsNil                   // JWT token is nil
├─ jwtParsingError            // JWT parsing error
// Successful / failed API requests
├─ authenticateSuccessful     // successful request: profile/authenticate
└─ authenticateFailed         // failed request: profile/authenticate

class AltcraftConfiguration

AltcraftConfiguration
// Altcraft SDK configuration class: API URL, resource token, information about
// the app, the logging flag, and the optional modules' configurations.
// Created only via the Builder. ObjC-compatible:
// AltcraftConfiguration / AltcraftConfiguration_Builder.
├─ @objc(AltcraftConfiguration_Builder) public final class Builder
│  // Set the API URL (required parameter)
│  ├─ @discardableResult func setApiUrl(_ url: String) -> Builder
│  // Set the resource token (optional)
│  ├─ @discardableResult func setRToken(_ rToken: String?) -> Builder
│  // Set the app metadata (Swift AppInfo model) (optional)
│  ├─ @discardableResult func setAppInfo(_ info: AppInfo?) -> Builder
│  // Enable/disable logging (optional)
│  ├─ @discardableResult func setEnableLogging(_ enabled: Bool?) -> Builder
│  // Add the configuration of an optional module (a repeated call for the same
│  // module replaces the previous configuration)
│  ├─ @discardableResult func addModuleConfiguration(
│  │     _ configuration: any ModuleConfiguration
│  │   ) -> Builder
│  // Build a valid configuration (nil if validation fails)
│  └─ func build() -> AltcraftConfiguration?
// Access to configuration parameters
├─ func getApiUrl() -> String
├─ func getRToken() -> String?
├─ func getAppInfo() -> AppInfo?
└─ func getEnableLogging() -> Bool?

Push (optional module)

enum Push

Push
// Access to the push token API
├─ var token: TokenAPI
// Access to the push subscription and status API
├─ var subscription: SubscriptionAPI
// Access to push events (delivery, open)
├─ var event: EventAPI
// Access to receiving and handling push notifications
├─ var notificationManager: NotificationManager
// Push module event types
└─ var moduleEvents: PushModuleEvents.Type

class AltcraftNSE — handling push in a Notification Service Extension

// Used inside the Notification Service Extension (NSE) — responsible for handling
// Altcraft push notifications, identifying Altcraft notifications, and registering goals
// without a dependency on UIApplication
AltcraftNSE
// Shared (singleton) instance for centralized NSE logic
├─ static let shared: AltcraftNSE
// Access to the goal registration API
├─ let target: TargetAPI
// Access to the profile fields update API
├─ let profile: UpdateAPI
// Check whether a notification belongs to Altcraft
├─ func isAltcraftPush(_ request: UNNotificationRequest) -> Bool
// Handle an incoming Altcraft notification: pass the modified content to contentHandler
├─ func handleNotificationRequest(
│     request: UNNotificationRequest,
│     contentHandler: @escaping (UNNotificationContent) -> Void
│   ): Void
// Called by the system when the NSE lifetime is about to expire
├─ func serviceExtensionTimeWillExpire(): Void
// Set up App Group and initialize the shared data container
├─ func setAppGroup(groupName: String?): Void
// Register the JWT provider
└─ func setJWTProvider(provider: JWTInterface): Void

class TokenAPI

TokenAPI
// Register an Apple Push Notification service provider (nil — remove)
├─ func setAPNSTokenProvider(_ provider: APNSInterface?): Void
// Register a Firebase Cloud Messaging provider (nil — remove)
├─ func setFCMTokenProvider(_ provider: FCMInterface?): Void
// Register a Huawei Mobile Services provider (nil — remove)
├─ func setHMSTokenProvider(_ provider: HMSInterface?): Void
// Get the current device token (completion is optional)
├─ func getPushToken(completion: ((TokenData?) -> Void)? = nil): Void
// Save a provider token manually
├─ func setPushToken(provider: String, pushToken: Any?): Void
// Change the provider priority and update the token
├─ func changePushPriorityList(_ list: [String]): Void
// Delete the token of the selected provider
├─ func deleteDeviceToken(provider: String, completion: (() -> Void)? = nil): Void
// Forced token update (delete —> update)
└─ func forcedTokenUpdate(completion: (() -> Void)? = nil): Void

class SubscriptionAPI

SubscriptionAPI
// Subscribe to push notifications (status = SUBSCRIBED)
├─ func pushSubscribe(
│     sync: Bool = true,
│     profileFields: [String: Any?]? = nil,
│     customFields: [String: Any?]? = nil,
│     cats: [CategoryData]? = nil,
│     replace: Bool? = nil,
│     skipTriggers: Bool? = nil
│   ): Void
// Suspend the push notification subscription (status = SUSPENDED)
├─ func pushSuspend(
│     sync: Bool = true,
│     profileFields: [String: Any?]? = nil,
│     customFields: [String: Any?]? = nil,
│     cats: [CategoryData]? = nil,
│     replace: Bool? = nil,
│     skipTriggers: Bool? = nil
│   ): Void
// Unsubscribe from push notifications (status = UNSUBSCRIBED)
├─ func pushUnSubscribe(
│     sync: Bool = true,
│     profileFields: [String: Any?]? = nil,
│     customFields: [String: Any?]? = nil,
│     cats: [CategoryData]? = nil,
│     replace: Bool? = nil,
│     skipTriggers: Bool? = nil
│   ): Void
// Change the status of the subscription specified in the JWT from suspended to subscribed; the other
// subscriptions that contain the specified push token will change status from subscribed to suspended
├─ func unSuspendPushSubscription(
│     completion: @escaping (ResponseWithHttpCode<ResponseWithProfile>?) -> Void
│   ): Void
// Status of the profile's latest subscription
├─ func getStatusOfLatestSubscription(
│     completion: @escaping (ResponseWithHttpCode<ResponseWithProfile>?) -> Void
│   ): Void
// Status of the subscription with the current device token
├─ func getStatusForCurrentSubscription(
│     completion: @escaping (ResponseWithHttpCode<ResponseWithProfile>?) -> Void
│   ): Void
// Status of the profile's latest subscription for the specified push notification provider
├─ func getStatusOfLatestSubscriptionForProvider(
│     provider: String? = nil,
│     completion: @escaping (ResponseWithHttpCode<ResponseWithProfile>?) -> Void
│   ): Void
// Add a profile functional field (set/incr/...)
└─ func actionField(key: String) -> ActionFieldBuilder

class EventAPI

EventAPI
// Record the delivery of an Altcraft push (fires the delivery event)
├─ func deliveryEvent(from request: UNNotificationRequest): Void
// Record the opening of an Altcraft push (fires the open event)
└─ func openEvent(from request: UNNotificationRequest): Void

class NotificationManager

// Manager of incoming push notifications: registration, display, click handling
NotificationManager
// Singleton (access point)
├─ static let shared: NotificationManager
// Register for push (delegate + requestAuthorization + registerForRemoteNotifications)
├─ func registerForPushNotifications(
│     for application: UIApplication,
│     completion: ((_ granted: Bool, _ error: Error?) -> Void)? = nil
│   ): Void
// Control push notification handling in the foreground (true — to the app)
├─ var customPushProcessing: Bool
// Control notification click handling (true — to the app)
├─ var customClickProcessing: Bool
// Callback for custom handling of a foreground notification
├─ var onForegroundNotification: (
│     (UNNotification, @escaping (UNNotificationPresentationOptions) -> Void) -> Void
│   )?
// Callback for custom handling of a notification click
├─ var onNotificationClick: (
│     (UNNotificationResponse, @escaping () -> Void) -> Void
│   )?
// NotificationCenter events published by the SDK
├─ Notification.Name.altcraftPushWillPresent   // a notification is shown in the foreground
└─ Notification.Name.altcraftPushDidReceive    // a tap on the notification / an action

class PushConfiguration

// Push module configuration. Added to the Builder via a pushConfig() call.
└─ class PushConfiguration(
     icon: String? = nil,                      // Name of the custom notification icon (optional)
     providerPriority: [String] = [],          // Push notification provider priority (optional)
     pushReceiverModules: [String] = [],       // Package prefixes containing custom receivers (optional)
     pushChannelName: String? = nil,          // Push notification channel name (optional)
     pushChannelDescription: String? = nil    // Push notification channel description (optional)
   )
   // Extension for adding the Push configuration to the main builder
   └─ func AltcraftConfiguration.Builder.pushConfig(_ configuration: PushConfiguration) -> Self

Target (optional module)

enum Target

Target
// Access to the goal registration API
├─ var event: TargetAPI
// Target module event types
└─ var moduleEvents: TargetModuleEvents.Type

class TargetAPI

TargetAPI
// Send a goal (target event) to the server
└─ 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

Profile (optional module)

enum Profile

Profile
// Access to the profile fields update API
├─ var update: UpdateAPI
// Profile module event types
└─ var moduleEvents: ProfileModuleEvents.Type

class UpdateAPI

UpdateAPI
// Update profile fields
└─ func updateProfileFields(
      profileFields: [String: Any?]? = nil,
      skipTriggers: Bool? = nil
    ): Void

In-App (optional module)

enum InApp

InApp
// Subscribe to the app lifecycle for automatic In-App display
├─ func registerLifecycleTracking(): Void
// Set the current screen marker (used when filtering In-App notifications)
├─ func setScreen(screen: String): Void
// Trigger a custom In-App campaign by name
├─ func trigger(name: String): Void
// Request available In-App placements
├─ func getPlacements(): Void
// Configure the In-App notification animation
├─ func setAnimation(
│     _ block: @escaping @MainActor (InAppAnimator) -> Void
│   ): Void
// Manage In-App notification subscriptions
├─ var subscription: SubscribeAPI
// In-App module event types
└─ var moduleEvents: InAppModuleEvents.Type

class SubscribeAPI (In-App)

SubscribeAPI
// Subscribe to In-App notifications (status = SUBSCRIBED)
├─ func inAppSubscribe(
│     sync: Bool = true,
│     profileFields: [String: Any?]? = nil,
│     customFields: [String: Any?]? = nil,
│     cats: [CategoryData]? = nil,
│     replace: Bool? = nil,
│     skipTriggers: Bool? = nil
│   ): Void
// Unsubscribe from In-App notifications (status = UNSUBSCRIBED)
├─ func inAppUnSubscribe(
│     sync: Bool = true,
│     profileFields: [String: Any?]? = nil,
│     customFields: [String: Any?]? = nil,
│     cats: [CategoryData]? = nil,
│     replace: Bool? = nil,
│     skipTriggers: Bool? = nil
│   ): Void
// In-App notification subscription status
└─ func getInAppSubscriptionStatus(
      completion: @escaping (ResponseWithHttpCode<ResponseWithProfile>?) -> Void
    ): Void

class InAppEmitter

// Output of In-App campaigns with "json" content type for an external subscriber
InAppEmitter
// Singleton
├─ static let shared: InAppEmitter
// Subscribe to JSON In-App campaigns (replaces the existing subscriber)
├─ func subscribe(callback: @escaping (String) -> Void): Void
// Unsubscribe from JSON In-App campaigns
└─ func unsubscribe(): Void

protocol InAppAnimator

InAppAnimator
// Identifier of the placement the animator belongs to
├─ var companyId: Int { get }
// Apply the block to the In-App view immediately, without starting an animation
├─ @MainActor func prepare(_ block: (UIView) -> Void): Void
// Configure and start a UIKit animation for the In-App view
└─ @MainActor func animate(
     duration: TimeInterval,
     delay: TimeInterval,
     options: UIView.AnimationOptions,
     animations: @escaping (UIView) -> Void,
     completion: ((Bool) -> Void)?
   ): Void

class InAppConfiguration

// In-App module configuration. Added to the Builder via an inAppConfig() call.
└─ class InAppConfiguration(
     inAppAutoRequest: Bool = true            // Automatic request of In-App placements (optional)
   )
   // Extension for adding the In-App configuration to the main builder
   └─ func AltcraftConfiguration.Builder.inAppConfig(_ configuration: InAppConfiguration) -> Self

Data models

Event Classes

Event
// Base SDK event (universal telemetry)
public let id: UUID
public let function: String
public let event: SDKEvent?
public let message: String?
public let value: [String: Any]?
public let date: Date

ErrorEvent
// SDK error, inherits from Event (errors without automatic retry)

RetryEvent
// Error of a request for which automatic retry is provided
// and execution on the SDK side; inherits from ErrorEvent

Data Classes (Core)

// App metadata for analytics (if used)
public struct AppInfo: Codable {
    public var appID: String
    public var appIID: String
    public var appVer: String
}

// Wrapper of an API response together with the HTTP code
public struct ResponseWithHttpCode<T: ResponseData & Sendable> {
    public let httpCode: Int?
    public let response: T?
}

// Request response containing profile data
public struct ResponseWithProfile: 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 acid: String?
    public let isTest: Bool?
    public let subscription: SubscriptionData?
}

// The profile's current 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?
}

Data Classes (Push)

// Device push provider token
public struct TokenData: Codable {
    public let provider: String
    public let token: String
}

Data Classes (Target)

// UTM parameters container for goal attribution (all fields are optional)
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?
}

// Base protocol of all subscription types added by a goal
public protocol Subscription {}

// Subscription to the Email channel
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"
}

// Subscription to the SMS channel
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"
}

// Subscription to the push channel
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]?
}

// Builder of functional operations (set/unset/incr/add/delete/upsert) over
// a profile field. The result is an entry for the profileFields dictionary.
public struct ActionFieldBuilder {
    public init(key: String)
    public func set(value: Any?) -> [String: Any?]
    public func unset(value: Any?) -> [String: Any?]
    public func incr(value: Any?) -> [String: Any?]
    public func add(value: Any?) -> [String: Any?]
    public func delete(value: Any?) -> [String: Any?]
    public func upsert(value: Any?) -> [String: Any?]
}

Constants

// Push module constants
└─ enum PushConstants
   // Push notification providers
   ├─ enum ProviderName
   │  ├─ static let apns     = "ios-apns"
   │  ├─ static let firebase = "ios-firebase"
   │  └─ static let huawei   = "ios-huawei"
   // push_event event types
   ├─ enum PushEvents
   │  ├─ static let delivery = "delivery"
   │  └─ static let open     = "open"

Interfaces

JWTInterface (Core):

JWTInterface
// Access to the current JWT
└─ func getToken() -> String?
   // Returns the current JWT or nil

APNSInterface (Push):

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

FCMInterface (Push):

FCMInterface
// Contract for FCM token operations (retrieval/revocation)
├─ 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 (Push):

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 (Target):

Subscription (protocol)
// Base protocol for all subscription types passed with a goal.
// Polymorphic serialization; the discriminant field is channel.