Skip to main content
Documentation for version v73

SDK Functionality

Working with subscription statuses​

Requesting subscription status​

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

Subscription status functions:

  • func getStatusOfLatestSubscription() — the last subscription status in the profile;
  • func getStatusOfLatestSubscriptionForProvider() — the subscription status for the current token/provider;
  • func getStatusForCurrentSubscription() — the latest subscription status by provider. If nil is specified, the current one is used.

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

Retrieves the status of the profile’s latest subscription. The completion receives a ResponseWithHttp? containing response?.profile?.subscription — the most recently created subscription in the profile. If no such subscription exists, nil is passed.

Example:

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

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

Retrieves the subscription status for the current token/provider. The completion receives a ResponseWithHttp? containing response?.profile?.subscription — the subscription found by the current push token and provider. If no such subscription exists, nil is passed.

Example:

// 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

Retrieves the latest subscription status by provider. The completion receives a ResponseWithHttp? containing response?.profile?.subscription — the most recently created subscription for the specified push provider. If no provider is specified, the current token’s provider is used. If no such subscription exists, nil is passed.

Example:

// 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)

Below is an example of extracting profile, subscription, and category data from the status response. This approach applies to all status-retrieval functions:

Data from status-retrieval functions
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
}

On a successful request, an event with code 234 is created. On error — an event with code 434.

Changing subscription status​

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

Subscription status change functions:

  • func pushSubscribe() — subscribes to push notifications;
  • func pushUnSubscribe() — unsubscribes from push notifications;
  • func pushSuspend() — suspends the push subscription (no notifications are delivered, but no unsubscribe event is created in the user’s profile);
  • func unSuspendPushSubscription() — used to implement LogIn / LogOut transitions.

All functions in this group have the same signature and parameters:

sync: Bool

Default: true
Required: No
Description: A flag that sets whether the request is executed synchronously.

Successful request execution:

On success, these functions produce an event with code 230, containing an event.value defined by the sync flag:

If 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 } ]

For synchronous requests, the event.value["response_with_http_code"] contains:

  • httpCode – transport-level status code;

  • Response – a public struct containing:

    • error: Int? — internal server error code (0 if no errors),

    • errorText: String? — error text (empty string if no errors),

    • profile: ProfileData? — profile data if the request is successful:

      • profile info (ProfileData)
      • subscription (SubscriptionData)
      • subscription categories (CategoryData)
      • if the request fails, profile = nil
Data structures
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
}
If sync == false
ResponseWithHttpCode
  ├─ httpCode: Int?
  └─ response: Response?
      ├─ error: Int?
      ├─ errorText: String?
      └─ profile: ProfileData? = nil

For asynchronous requests, event.value["response_with_http_code"] contains:

  • httpCode – transport-level status code;

  • Response – a public struct containing:

    • error: Int? — internal server error code (0 if no errors),
    • errorText: String? — error text (empty string if no errors),
    • profile: ProfileData? — profile data, always nil for async requests.

Failed request execution:

If a request in this group fails, an event with one of the following codes is created:

  • 430 – error without automatic retry by the SDK;
  • 530 – error with automatic retry by the SDK.

Event contents:

  • only httpCode if the Altcraft server was unavailable;
  • error and errorText if the server returned an error.
Retrieving push event values
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
        }
    }
}

The fields inside subscription may include your custom subscription fields. They are of type [String: JSONValue]?. The public enum JSONValue provides helpers to simplify field value extraction:

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
}

Example of extracting the 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?]?

Default: nil
Required: No
Description: A dictionary containing profile fields.

The parameter may include system fields (e.g., _fname — first name, _lname — last name) and optional fields (manually created in the platform UI). Allowed JSON-compatible value types:

  • String
  • Bool
  • Numbers
  • nil
  • Objects [String: Any]
  • Arrays

If an invalid optional field is passed, the request fails:

SDK error: 430
http code: 400
error: 400
errorText: Platform profile processing error: with field "field_name": Incorrect field

customFields: [String: Any?]?

Default: nil
Required: No
Description: A dictionary containing subscription fields.

The parameter may include system fields (e.g., _device_model — device model, _os — OS), as well as optional ones (manually created in the platform UI). Allowed types:

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

If an invalid optional field is passed, the request fails:

SDK error: 430
http code: 400
error: 400
errorText: Platform profile processing error: field "field_name" is not valid: failed convert custom field

Nested objects, arrays, and collections are not allowed.

Note

Most system subscription fields are automatically collected by the SDK and added to push requests. These include: "_os", "_os_tz", "_os_language", "_device_type", "_device_model", "_device_name", "_os_ver", "_ad_track", "_ad_id".

cats: [CategoryData]?

Default: nil
Required: No
Description: Subscription categories.

Category structure:

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

When sending a push request with categories, use only name (category name) and active (category active status). Other fields are not used in request processing. The title and steady fields are populated when retrieving subscription info.

Request example:

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

Response example:

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

Categories used in the request must be created beforehand and added to the resource in the Altcraft platform. If a category not present in the resource is used, the request returns an error:

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?

Default: nil
Required: No
Description: When enabled, all subscriptions of other profiles with the same push token in the current database are set to unsubscribed after a successful request.

skipTriggers: Bool?

Default: nil
Required: No
Description: When enabled, the profile containing this subscription will be ignored by campaign and scenario triggers.

Request examples

Example: subscribing to push notifications

Minimal working call:

AltcraftSDK.shared.pushSubscriptionFunctions.pushSubscribe()

Passing all available parameters:

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
)
Note

For pushSubscribe, pushSuspend, and pushUnSubscribe, the SDK automatically retries the request if the HTTP status code is in the 500..599 range. No retry occurs if the code is outside this range.

Function unSuspendPushSubscription()

func unSuspendPushSubscription() is designed for LogIn / LogOut transitions. It works as follows:

  • searches for subscriptions with the same push token as the current one that do not belong to the profile referenced by the current JWT;
  • changes the status of the found subscriptions from subscribed to suspended;
  • changes the status of the subscriptions in the profile referenced by the current JWT from suspended to subscribed (if that profile exists and contains subscriptions);
  • returns a ResponseWithHttpCode? where response.profile is the current profile referenced by the JWT (if the profile does not exist, response.profile is nil).

Example:

AltcraftSDK.shared.pushSubscriptionFunctions.unSuspendPushSubscription(completion: @escaping (ResponseWithHttp?) -> Void)
Recommended LogIn / LogOut flow

LogIn flow:

  • An anonymous user opens the app. The user has JWT_1, pointing to database #1Anonymous;
  • The user subscribes to push; a profile is created in #1Anonymous;
  • The user registers and receives JWT_2, pointing to #2Registered;
  • Call unSuspendPushSubscription() — the anonymous subscription in #1Anonymous is suspended;
  • The SDK searches for a profile in #2Registered to restore the subscription;
  • Since a subscription with this push token does not exist in #2Registered, unSuspendPushSubscription() returns nil;
  • After receiving nil, call pushSubscribe() to create a new profile in #2Registered.

LogOut flow:

  • The user logs out in the app (LogOut);
  • The user receives JTW_1, pointing to #1Anonymous;
  • Call unSuspendPushSubscription(), which suspends the subscription in #2Registered and sets the status in #1Anonymous to subscribed;
  • The request returns #1Anonymous != nil — the subscription already exists, no new one is required.

Example implementation:

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
            )
        }
    }
}

Provider push token management​

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 functions for working with a provider’s token:

  • func setPushToken() — manually sets the device push token and provider in UserDefaults;
  • func getPushToken() — retrieves the current push token;
  • func setAPNSTokenProvider() — sets or removes the APNs push-token provider;
  • func setFCMTokenProvider() — sets or removes the FCM push-token provider;
  • func setHMSTokenProvider() — sets or removes the HMS push-token provider;
  • func changePushProviderPriorityList() — dynamically switches the provider and updates the subscription’s push token;
  • func deleteDeviceToken() — deletes the push token for the specified provider;
  • func forcedTokenUpdate() — deletes the current push token and then refreshes it.

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

Used to manually set the device push token and provider in UserDefaults. This serves as a simplified way to pass a push token into the SDK without implementing provider protocols.

Not recommended for passing the token. The preferred approach is to implement FCMInterface, HMSInterface, or APNSInterface.

Example:

// 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

Passes a TokenData(provider: String, token: String) object to completion, containing the current device push token and its provider. If the push token is unavailable, nil is passed.

Example:

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

Example of requesting push-token data:

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

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

Sets or removes the Firebase Cloud Messaging provider. Pass nil to disable the provider.

Example:

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

Call setFCMTokenProvider() in AppDelegate.application(_:didFinishLaunchingWithOptions:) before AltcraftSDK.initialization(). This guarantees registration at process start, regardless of lifecycle state or whether the app launches in foreground or background.

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

Sets or removes the Huawei Mobile Services provider. Pass nil to disable the provider.

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

Call setHMSTokenProvider() in AppDelegate.application(_:didFinishLaunchingWithOptions:) before AltcraftSDK.initialization(). This guarantees registration at process start, regardless of lifecycle state or whether the app launches in foreground or background.

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

Sets or removes the Apple Push Notification service provider. Pass nil to disable the provider.

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

Call setAPNSTokenProvider() in AppDelegate.application(_:didFinishLaunchingWithOptions:) before AltcraftSDK.initialization(). This guarantees registration at process start, regardless of lifecycle state or whether the app launches in foreground or background.

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

Enables dynamic switching of the push provider with token refresh. Pass a new array with a different provider order, e.g., [Constants.ProviderName.firebase, Constants.ProviderName.apns, Constants.ProviderName.huawei].

Example:

// 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

Deletes the push token for the specified provider. The token is invalidated and removed from the local cache on the device and from the push provider’s server. After deletion, a new token can be requested.

Example:

// 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

Deletes the current push token and then refreshes it.

Example:

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

Example of registering providers​

We do not recommend using setPushToken to set the push token. Instead, configure token retrieval for each provider you use. Example:

Recommended provider registration in 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
    }
}

Passing push notifications to the SDK​

The SDK includes a class and functions for receiving, processing, and displaying push notifications.

AltcraftPushReceiver is the public SDK class for handling incoming push notifications. It checks whether a notification is from Altcraft, processes its content (including rich media), and builds the final notification shown to the user.

// 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 functions:

  • func isAltcraftPush() — verifies the notification source;
  • func didReceive() — accepts a UNNotificationRequest from the Notification Service Extension for further processing by the SDK;
  • func serviceExtensionTimeWillExpire() — called when the Notification Service Extension times out (~30 seconds).

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

Checks whether the notification originates from Altcraft by a marker in userInfo.

Example:

// 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

Accepts a UNNotificationRequest from the Notification Service Extension, processes it in the SDK, and prepares the notification for display.

Example:

// 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()

Called by the system when the Notification Service Extension times out (~30 seconds).

Example:

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

Mobile events​

// PublicMobileEventFunctions object

AltcraftSDK.shared
└── let mobileEventFunctions: PublicMobileEventFunctions

    // Send a mobile event to the server
    └── func mobileEvent(
            sid: 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 
        )

Use mobileEvent() from PublicMobileEventFunctions to register a mobile event. Parameters:

sid: String

Required: Yes
Description: String pixel identifier to which mobile events are linked.

eventName: String

Required: Yes
Description: Mobile event name.

sendMessageId: String?

Required: No
Description: SMID of the sent message (when the event is tied to a specific mailing).

payload: [String: Any?]?

Required: No
Description: Event data — a map with string keys; only scalar value types are allowed:

  • String
  • Bool
  • Int
  • Int64 / UInt64 (or NSNumber equivalents)
  • Float
  • Double
  • nil / NSNull

Note

Non-serializable objects (e.g., Date without conversion, custom classes) will cause encoding errors.

matching: [String: Any?]?

Required: No Description: A map for passing values with matching types/identifiers (e.g., ["email" : "user@example.com"]).

matchingType: String?

Required: No
Description: Matching type.

profileFields: [String: Any?]?

Required: No
Description: Profile fields — a map with string keys and values (JSON-compatible types):

  • Scalar values:

    • String
    • Bool
    • Int
    • Int64 / UInt64 (or NSNumber equivalents)
    • Float
    • Double
    • nil / NSNull

  • Objects: [String: Any?]

  • Lists: [Any?]

  • Array of maps: [[String: Any?]]

Note

profileFields is used only with JWT authorization.

utm: UTM?

Required: No
Description: UTM tags. Added via the UTM struct, where each UTM type is a property:

public struct UTM{
    /// UTM Campaign
    public var campaign: String?
    /// UTM Content
    public var content: String?
    /// UTM Keyword/Term
    public var keyword: String?
    /// UTM Medium
    public var medium: String?
    /// UTM Source
    public var source: String?
    /// UTM Temp
}

subscription: (any Subscription)?

Required: No Description: A subscription to be added to the profile, one of: EmailSubscription, SmsSubscription, PushSubscription, CcDataSubscription.

Note

Used only with JWT authorization.

Subscription interface implementations​

Purpose — a common protocol for all subscription types. Serialization — via Codable, discriminator field — channel.

Common fields (for all implementations):

FieldTypeRequiredDescription
resource_idIntYesIdentifier of the resource/source of the subscription
statusString?NoSubscription status (e.g., active/suspended)
priorityInt?NoDelivery priority for this subscription
custom_fields[String: JSONValue]?NoCustom key–value fields for advanced segmentation
cats[String]?NoSubscription categories
channelStringYesChannel type; fixed by the specific implementation
Note

JSONValue is a serializable enum/type of JSON values in your SDK. All values must be JSON-compatible.



Subscription variants:

1. Email channel subscription

EmailSubscription (channel = "email")

Additional fields:

FieldTypeRequiredDescription
emailStringYesRecipient email address

Details: channel is always "email".

2. SMS channel subscription

SmsSubscription (channel = "sms")

Additional fields:

FieldTypeRequiredDescription
phoneStringYesPhone number in international format

Details: channel is always "sms".

3. Push notifications subscription

PushSubscription (channel = "push")

Additional fields:

FieldTypeRequiredDescription
providerStringYesProvider (e.g., "apns", "android-firebase", etc.)
subscription_idStringYesProvider-side unique subscription identifier

Details: channel is always "push".

4. Subscriptions for channels with arbitrary communication fields

CcDataSubscription (channel ∈ {"telegram_bot","whatsapp","viber","notify"})

Additional fields:

FieldTypeRequiredDescription
channelStringYesOne of: "telegram_bot", "whatsapp", "viber", "notify".
ccData[String: JSONValue]YesChannel-specific data (e.g., chat id, phone number, tokens).

Details: channel is set explicitly and must match a supported value.

Receiving SDK events in the app​

// Events object functions

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

Only one active subscriber to SDK events can exist in the app.

Subscribing to events​

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

Subscribes to and receives SDK events in the app. When an SDK event occurs, it invokes callback and passes an instance of Event (or its subclass).

Example:

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

All events provided by the SDK are instances of Event or its subclasses:

  • Event — general event (information, successful requests);
  • Error — error event;
  • RetryError — error event for a request that the SDK will automatically retry.

Each event contains:

  • function — the name of the function that produced the event;
  • eventCode — internal SDK event code (see “SDK events”);
  • eventMessage — event message;
  • eventValue — arbitrary payload [String: Any?]? added to some events;
  • date — event timestamp.
SDK events
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
        )
    }
}
Example contents of a successful push subscription event
├─ 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: // push token of the subscription
│           ├─ hashId: // hash ID
│           ├─ 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

Unsubscribing from events​

public func unsubscribe(): Void

Unsubscribes from SDK events. It stops event delivery while keeping the callback assigned.

Example:

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

Additional functions​

Functional profile field updates​

public func actionField(key: String) -> ActionFieldBuilder

A helper for the functional profile field update process. Supports:

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

Example:

// "_fname" — field to update
// .set("Andrey") — sets the field to "Andrey"
AltcraftSDK.shared.pushSubscriptionFunctions.pushSubscribe(
    profileFields: AltcraftSDK.shared.pushSubscriptionFunctions.actionField(key: "_fname").set(value: "Andrey")
)

Clearing SDK data​

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

Clears SDK data and cancels all pending background tasks. Removes CoreData records and clears UserDefaults.

Example:

// Full SDK reset (cache/database/settings), then call completion
AltcraftSDK.shared. clear(completion: (() -> Void)? = nil)

The function accepts an optional completion called after cleanup and task cancellation.

Manual event registration​

Note

Use these only if you implement your own notification handling and do not pass them to Altcraft SDK. By default, Altcraft SDK handles notifications automatically; these methods are needed only for custom client-side processing.

// PublicPushEventFunctions

AltcraftSDK
//   Singleton, SDK entry point
└── public static let shared: AltcraftSDK  
    // Manual sending of push events (delivery / open)
    └── public let pushEventFunctions: PublicPushEventFunctions
        // Record Altcraft push delivery (fires a delivery event)
        ├── public func deliveryEvent(from request: UNNotificationRequest): Void
        // Record Altcraft push open (fires an open event)
        └── public func openEvent(from request: UNNotificationRequest): Void

Manual event registration functions:

  • func deliveryEvent() — registers a delivery event;
  • func openEvent() — registers an open event.

public func deliveryEvent(from request: UNNotificationRequest): Void

Registers a delivery event in the Altcraft platform. Pass UNNotificationRequest in the request parameter.

Example:

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

public func openEvent(from request: UNNotificationRequest): Void

Registers an open event in the Altcraft platform. Pass UNNotificationRequest in the request parameter.

// Record Altcraft push open (fires an open event)
AltcraftSDK.shared.pushEventFunctions.openEvent(from: UNNotificationRequest)
Last updated on