Функционал SDK

подсказка

Предварительно вам необходимо настроить SDK для работы с вашим приложением. Подробная инструкция находится здесь

SDK разделён на модули: core (авторизация, события), push, target (цели), profile и in-app. Каждый модуль подключается отдельной зависимостью и доступен через своё свойство объекта AltcraftSDK.shared — AltcraftSDK.shared.push, AltcraftSDK.shared.target, AltcraftSDK.shared.profile, AltcraftSDK.shared.inApp.

Core: авторизация

AltcraftSDK
└─ static let shared: AltcraftSDK
   // Доступ к аутентификации пользователя
   └─ let authFunctions: AuthAPI
      // Аутентифицировать текущего пользователя SDK
      ├─ func authenticate(): Void
      // Выйти из профиля (возврат к анонимной сессии)
      └─ func logOut(): Void

Функции авторизации:

func authenticate() — аутентифицирует текущего пользователя: отправляет на сервер запрос с текущими данными аутентификации (JWT-токен или rToken) и привязывает устройство к профилю пользователя. После успешной аутентификации пользователь получает доступ к персонализированным In-App уведомлениям.
func logOut() — завершает текущую сессию аутентификации и переводит устройство в анонимный режим. В анонимном режиме недоступны персонализированные In-App уведомления и управление подпиской.

Установка JWT-провайдера выполняется функцией AltcraftSDK.shared.setJWTProvider(provider:) (см. настройку SDK). Для работы без JWT используйте rToken из конфигурации.

Важно

Вызывайте authenticate() только тогда, когда пользователь действительно выполняет вход в приложение и известен для клиента (например, после успешной авторизации через форму логина, OAuth или другой механизм аутентификации вашего приложения). С logOut() — аналогично: только при реальном выходе пользователя.

Пример использования:

AltcraftSDK.shared.authFunctions.authenticate()

Очистка данных SDK

AltcraftSDK
// Полная очистка данных SDK (кэш, БД, настройки), затем вызов completion
└── func clear(
        completion: (() -> Void)? = nil
    ): Void

Функция выполняет полную очистку данных SDK: кэша, базы данных и локальных настроек. Необязательный параметр completion вызывается после завершения очистки.

Core: события SDK

// API событий SDK

AltcraftSDK
└── let eventSDKFunctions: SDKEvents
    // Подписка на события SDK (заменяет существующего подписчика)
    ├── func subscribe(
    │       callback: @escaping (Event) -> Void
    │   ): Void
    // Отписка от событий
    └── func unsubscribe(): Void

В приложении может быть только один активный подписчик на события SDK.

Типы событий SDK:

Event — общее событие (информация, успешные запросы);
ErrorEvent — событие об ошибке;
RetryEvent — событие об ошибке при выполнении запроса, для которого предусмотрен автоматический повтор на стороне SDK.

Каждое событие содержит поля:

function — имя функции, вызвавшей событие;
event — тип события SDK (SDKEvent, список см. в таблице ниже);
message — сообщение события;
value — дополнительные данные ([String: Any]?), добавляемые к некоторым событиям;
date — время события.

Подписка на события

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

Функция подписывает приложение на события SDK. При возникновении события SDK она вызывает переданный callback и передаёт в него экземпляр Event (или его наследника). Колбэк всегда вызывается на главном потоке.

Пример использования:

AltcraftSDK.shared.eventSDKFunctions.subscribe { event in
    // Обработка события
}

Классы событий SDK

open class Event: NSObject {
    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
}

// Ошибка без автоматического повтора
open class ErrorEvent: Event {}

// Ошибка запроса, для которого предусмотрен автоматический повтор
public final class RetryEvent: ErrorEvent {}

Отписка от событий

func unsubscribe(): Void

Отменяет доставку событий SDK. Подписчик остаётся назначенным, но события больше не передаются.

Пример использования:

AltcraftSDK.shared.eventSDKFunctions.unsubscribe()

Список всех событий SDK

Список событий по модулям

События SDK доступны как значения перечислений: CoreEvents (core), PushModuleEvents, TargetModuleEvents, ProfileModuleEvents, InAppModuleEvents. Каждый элемент — значение перечисления со строковым сообщением (message).

Core:

Значение	Сообщение
`configSet`	SDK configuration is installed.
`sdkCleared`	SDK data has been cleared
`initAwait`	waiting for SDK initialization to complete
`userLogOut`	User logged out. Anonymous session started
`backgroundTaskRegister`	SDK background task is registered
`backgroundTaskCompleted`	SDK background task completed
`configIsNotSet`	the configuration is not set
`appGroupIsNotSet`	App Group name was not set.
`notAuthenticatedError`	user is not authenticated
`invalidUrlValue`	invalid apiUrl value - empty or null.
`invalidRTokenValue`	invalid resource token value - resource token is empty.
`fieldsIsObjects`	invalid values: not all values are primitives
`permissionDenied`	notification permission denied.
`jwtIsNil`	JWT token is nil
`authenticateSuccessful`	successful request: profile/authenticate
`authenticateFailed`	failed request: profile/authenticate

Перечисление CoreEvents содержит и внутренние события (ошибки CoreData, парсинга JWT, недоступности окружения и т.п.), которые не входят в таблицу выше и не являются частью публичного API. Внутренние события также есть в PushModuleEvents и InAppModuleEvents — в таблицах ниже перечислены только события публичного API.

Push:

Значение	Сообщение
`pushProviderSet`	push provider set:
`pushReceive`	received Altcraft push notification.
`pushIsPosted`	push is posted.
`pushTokenUpdateAwait`	waiting for push token update to complete
`pushSubscribeRequestSuccessful`	successful request: push/subscribe
`pushSubscribeRequestFailed`	failed request: push/subscribe
`pushSuspendRequestSuccessful`	successful request: push/suspend
`pushSuspendRequestFailed`	failed request: push/suspend
`pushUnsubscribeRequestSuccessful`	successful request: push/unsubscribe
`pushUnsubscribeRequestFailed`	failed request: push/unsubscribe
`tokenUpdateRequestSuccessful`	successful request: push/update
`tokenUpdateRequestFailed`	failed request: push/update
`pushStatusRequestSuccessful`	successful request: push/status
`pushStatusRequestFailed`	failed request: push/status
`unsuspendRequestSuccessful`	successful request: push/unsuspend
`unsuspendRequestFailed`	failed request: push/unsuspend
`pushEventRequestSuccessful`	successful request: event/push
`pushEventRequestFailed`	failed request: event/push
`invalidPushProviders`	invalid provider. Available - ios-apns, ios-firebase, ios-huawei.
`invalidPushProvider`	invalid provider.
`errorHandleUserInfo`	invalid userInfo format
`uidIsNil`	uid in the push data is null, it is impossible to send a push event to the server.
`errorMediaDownload`	could not download image data from URL.
`errorMediaKeyMissing`	'media' key is missing or URL string is invalid.
`errorButtonsKeyMissing`	'buttons' key is missing or is invalid.
`invalidButtonIdentifier`	invalid button identifier. See event value
`outOfRangeForIdentifier`	out of range for identifier. See event value
`unknownButtonIdentifier`	unknown button identifier. See event value
`subscribeRequestDataIsNil`	subscribe request data is nil
`updateRequestDataIsNil`	update request data is nil
`pushEventRequestDataIsNil`	push event request data is nil
`unsuspendRequestDataIsNil`	unsuspend request data is nil
`pushStatusRequestDataIsNil`	push status request data is nil
`invalidSubRequestData`	invalid push subscribe request data
`invalidPushEventRequestData`	invalid push event request data
`pushConfigurationSaveFailed`	failed to save the push configuration to the local database
`pushConfigurationClearFailed`	failed to clear the push configuration from the local database
`apnsIsNotUpdated`	forcing a push token update is not possible: the operation is not supported for APNs.
`pushTokenIsNil`	current push token is nil

Target:

Значение	Сообщение
`mobileRequestDataIsNil`	mobile event request data is nil
`mobileEventRequestSuccessful`	successful request: event/post
`mobileEventRequestFailed`	failed request: event/post

Profile:

Значение	Сообщение
`profileUpdateRequestDataIsNil`	profile update request data is nil
`profileUpdateRequestSuccessful`	successful request: profile/update
`profileUpdateRequestFailed`	failed request: profile/update

In-App:

Значение	Сообщение
`errorInAppImageLoad`	failed to load in-app image
`invalidStaticField`	invalid in-app static field
`smidIsNil`	smid in the in-app data is null, it is impossible to send a in-app event to the server.
`inAppStatusRequestDataIsNil`	in-app status request data is nil
`inAppEventRequestDataIsNil`	in-app event request data is nil
`subscribeRequestDataIsNil`	in-app subscribe request data is nil
`invalidSubRequestData`	invalid in-app subscribe request data
`inAppSubscribeRequestSuccessful`	successful request: inapp/subscribe
`inAppSubscribeRequestFailed`	failed request: inapp/subscribe
`inAppUnsubscribeRequestSuccessful`	successful request: inapp/unsubscribe
`inAppUnsubscribeRequestFailed`	failed request: inapp/unsubscribe
`inAppStatusRequestSuccessful`	successful request: inapp/status
`inAppStatusRequestFailed`	failed request: inapp/status
`inAppEventRequestSuccessful`	successful request: inapp/event
`inAppEventRequestFailed`	failed request: inapp/event
`inAppPlacementsRequestSuccessful`	successful request: inapp/placements
`inAppPlacementsRequestFailed`	failed request: inapp/placements
`inAppStaticErrorLoad`	error loading in-app notification static resources
`inAppContentErrorLoad`	error loading in-app notification content
`maxPlacementsInvalid`	Invalid in-app configuration: maxPlacements must be >= 1
`requestIntervalInvalid`	Invalid in-app configuration: placementsRequestInterval must be > 0
`placementsLimitExceeded`	in-app placements limit exceeded

Push: работа со статусами подписки

Изменение статуса подписки

AltcraftSDK
└─ static let shared: AltcraftSDK
   └─ var push: Push
      └─ var subscription: SubscriptionAPI
         // Подписка (статус = SUBSCRIBED)
         ├─ func subscribe(
         │     sync: Bool = true,
         │     profileFields: [String: Any?]? = nil,
         │     customFields: [String: Any?]? = nil,
         │     cats: [CategoryData]? = nil,
         │     replace: Bool? = nil,
         │     skipTriggers: Bool? = nil
         │   ): Void
         // Приостановка (статус = SUSPENDED)
         ├─ func suspend(
         │     sync: Bool = true,
         │     profileFields: [String: Any?]? = nil,
         │     customFields: [String: Any?]? = nil,
         │     cats: [CategoryData]? = nil,
         │     replace: Bool? = nil,
         │     skipTriggers: Bool? = nil
         │   ): Void
         // Отписка (статус = UNSUBSCRIBED)
         ├─ func unsubscribe(
         │     sync: Bool = true,
         │     profileFields: [String: Any?]? = nil,
         │     customFields: [String: Any?]? = nil,
         │     cats: [CategoryData]? = nil,
         │     replace: Bool? = nil,
         │     skipTriggers: Bool? = nil
         │   ): Void
         // Переключение подписок между профилями (LogIn/LogOut)
         ├─ func unSuspend(
         │     completion: @escaping @Sendable (
         │       ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?
         │     ) -> Void
         │   ): Void
         // Построение функциональных операций над полями профиля
         └─ func actionField(key: String) -> ActionFieldBuilder

Функции изменения статуса подписки:

func subscribe() — выполняет подписку на push-уведомления;
func suspend() — приостанавливает подписку на push-уведомления (уведомления не приходят, но при этом не создаётся событие отписки в профиле пользователя);
func unsubscribe() — отменяет подписку на push-уведомления;
func unSuspend() — используется для создания LogIn-, LogOut-переходов;
func actionField() — создаёт ActionFieldBuilder для построения функциональных операций (set, unset, incr, add, delete, upsert) над полями профиля внутри profileFields.

Функции изменения статуса имеют одинаковую сигнатуру, содержащую следующие параметры:

sync: Bool

По умолчанию: true
Обязательный: Нет
Описание: Флаг, устанавливающий синхронность выполнения запроса.

Успешное выполнение запроса:

В случае успешного выполнения запроса данной группы функций будет создано событие pushSubscribeRequestSuccessful, pushSuspendRequestSuccessful или pushUnsubscribeRequestSuccessful, содержащее в event.value данные ответа:

Если sync == true

event.value
  ├─ error: 0
  ├─ error_text: ""
  ├─ http_code: 200
  └─ 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: "mob"
        │  ├─ _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 } ]

При синхронном запросе в значении события event.value доступны:

error – внутренний код ошибки сервера (0, если ошибок нет);
error_text – текст ошибки (пустая строка, если ошибок нет);
http_code – транспортный код ответа;
profile – данные профиля, если запрос успешный:
- информация о профиле (ProfileData)
- подписка (SubscriptionData)
- категории подписки (CategoryData)
- если запрос завершился с ошибкой, то вернётся только profile = nil

Структуры данных

public struct ProfileData: Codable {
    public let id: String?
    public let status: String?
    public let acid: 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?
}

Если sync == false

event.value
  ├─ error: Int?
  ├─ error_text: String?
  ├─ http_code: Int
  └─ profile: ProfileData? = nil

При асинхронном запросе profile в значении события event.value всегда равен nil.

Выполнение запроса с ошибкой:

Если запрос данной группы функций завершился ошибкой, будет создано событие с типом ошибки:

pushSubscribeRequestFailed — подписка на уведомления;
pushSuspendRequestFailed — приостановка подписки;
pushUnsubscribeRequestFailed — отписка.

Содержимое события:

только http_code, если сервер Altcraft был недоступен;
error и error_text, если сервер вернул ошибку.

Получение значений событий

AltcraftSDK.shared.eventSDKFunctions.subscribe { event in
    let sdkEvent = event.event

    if sdkEvent == PushModuleEvents.pushSubscribeRequestSuccessful ||
       sdkEvent == PushModuleEvents.pushSubscribeRequestFailed
    {
        let value = event.value
        let error = value?["error"] as? Int
        let errorText = value?["error_text"] as? String
        let httpCode = value?["http_code"] as? Int
        let profile = value?["profile"] as? ProfileData
        let subscription = profile?.subscription
    }
}

profileFields:[String: Any?]?

По умолчанию: nil
Обязательный: Нет
Описание: Словарь, содержащий поля профиля.

Параметр может принимать как системные поля (например, _fname — имя или _lname — фамилия), так и опциональные (заранее создаются вручную в интерфейсе платформы). Допустимые структуры (JSON-совместимые):

Скалярные значения:
- String
- Bool
- Int
- Int64 / UInt64 (или эквиваленты NSNumber)
- Float
- Double
- nil
Объекты: [String: Any?]
Списки: [Any?]
Массивы карт: [[String: Any?]]

Если передано невалидное опциональное поле, запрос завершится с ошибкой:

http_code: 400
error: 400
error_text: Platform profile processing error: with field "название_поля": Incorrect field

Для функциональных операций над полями профиля используйте actionField():

AltcraftSDK.shared.push.subscription.subscribe(
    profileFields: AltcraftSDK.shared.push.subscription.actionField("orders_count").incr(1)
)

customFields:[String: Any?]?

По умолчанию: nil
Обязательный: Нет
Описание: Словарь, содержащий поля подписки.

Параметр может принимать как системные поля (например, _device_model — модель устройства или _os — операционная система), так и опциональные (заранее создаются вручную в интерфейсе платформы). Допустимые типы значений (JSON-совместимые, только скаляры):

String
Bool
Int
Float
Double
nil

Если передано невалидное опциональное поле, запрос завершится с ошибкой:

http_code: 400
error: 400
error_text: Platform profile processing error: field "название_поля" is not valid: failed convert custom field

Вложенные объекты, массивы и коллекции не допускаются.

Обратите внимание

Большая часть системных полей подписки автоматически собирается SDK и добавляется к push-запросам. К таким системным полям относятся: "_os", "_os_tz", "_os_language", "_device_type", "_device_model", "_device_name", "_os_ver", "_ad_track", "_ad_id".

cats:[CategoryData]?

По умолчанию: nil
Обязательный: Нет
Описание: Категории подписок.

Структура категории:

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

При отправке push-запроса с указанием категорий используйте только поля name (название категории) и active (статус активности категории), другие поля не используются в обработке запроса. Поля title и steady заполняются при получении информации о подписке.

Пример запроса:

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

Категории, используемые в запросе, должны быть предварительно созданы и добавлены к ресурсу в платформе Altcraft. Если в запросе будет использована категория, которая не добавлена в ресурс, — запрос вернётся с ошибкой:

http_code: 400
error: 400
error_text: Platform profile processing error: field "subscriptions.cats" is not valid: category not found in resource

replace:Bool?

По умолчанию: nil
Обязательный: Нет
Описание: При активации флага все подписки других профилей с тем же push-токеном в текущей базе данных переводятся в статус unsubscribed после успешного запроса.

skipTriggers:Bool?

По умолчанию: nil
Обязательный: Нет
Описание: При активации флага профиль, содержащий данную подписку, будет игнорироваться в триггерах рассылок и сценариев.

Примеры реализации запроса

Пример выполнения запроса подписки на push-уведомления

Минимальная рабочая настройка:

AltcraftSDK.shared.push.subscription.subscribe()

Передача всех доступных параметров:

AltcraftSDK.shared.push.subscription.subscribe(
    sync: true,
    profileFields: ["_fname": "Andrey", "_lname": "Pogodin"],
    customFields:  ["developer": true],
    cats: [CategoryData(name: "developer_news", active: true)],
    replace: false,
    skipTriggers: false
)

Обратите внимание

Для subscribe, suspend и unsubscribe предусмотрен автоматический повтор запроса со стороны SDK, если http-код ответа находится в диапазоне 500..599. Запрос не повторяется, если код ответа в этот диапазон не входит.

Функция unSuspend()

Функция unSuspend() предназначена для создания LogIn-, LogOut-переходов. Она работает следующим образом:

проводит поиск подписок с тем же push-токеном, что и текущий, не относящихся к профилю, на который указывает текущий JWT-токен;
меняет статус найденных подписок с subscribed на suspended;
меняет статус в подписках профиля, на который указывает текущий JWT, с suspended на subscribed (если профиль, на который указывает JWT, существует и в нём содержатся подписки);
возвращает ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?, в котором response.profile — текущий профиль, на который указывает JWT (если профиля не существует, вернётся nil).

Пример использования:

AltcraftSDK.shared.push.subscription.unSuspend { response in
    // обработка ответа
}

Рекомендуемая реализация LogIn-, LogOut-переходов

LogIn-переход:

Анонимный пользователь входит в приложение. Данному пользователю присвоен JWT_1, указывающий на базу данных #1Anonymous;
Выполнена подписка на push-уведомления, профиль создан в базе данных #1Anonymous;
Пользователь регистрируется, ему присваивается JWT_2, указывающий на базу данных #2Registered;
Вызывается функция unSuspend() — подписка анонимного пользователя в базе данных #1Anonymous приостанавливается;
Выполняется поиск профиля в базе данных #2Registered для восстановления подписки;
Так как подписки с таким push-токеном в базе данных #2Registered не существует, функция unSuspend() вернёт профиль без подписки;
После этого можно выполнить запрос на подписку subscribe(), который создаст новый профиль в базе #2Registered.

LogOut-переход:

Пользователь выполнил выход из профиля на стороне приложения (LogOut);
Пользователю присваивается JWT_1, указывающий на базу данных #1Anonymous;
Вызывается функция unSuspend(), которая приостановит подписку в базе данных #2Registered и сменит статус подписки в базе #1Anonymous на subscribed;
Запрос вернёт непустой профиль — подписка уже существует, новая не требуется.

Пример реализации:

func logIn() {
    JWTManager.shared.setRegJWT()
    // JWT is set for an authorized user
    AltcraftSDK.shared.push.subscription.unSuspend { result in
        if result?.httpCode == 200, result?.response?.profile?.subscription == nil {
            AltcraftSDK.shared.push.subscription.subscribe(
                // Укажите необходимые параметры
            )
        }
    }
}

func logOut() {
    JWTManager.shared.setAnonJWT()
    // JWT is set for an anonymous user
    AltcraftSDK.shared.push.subscription.unSuspend { result in
        if result?.httpCode == 200, result?.response?.profile?.subscription == nil {
            AltcraftSDK.shared.push.subscription.subscribe(
                // Укажите необходимые параметры
            )
        }
    }
}

Запрос статуса подписки

AltcraftSDK
└── static let shared: AltcraftSDK
    └── var push: Push
        └── var subscription: SubscriptionAPI
            // Статус последней подписки профиля
            ├── func latest(
            │       completion: @escaping @Sendable (
            │           ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?
            │       ) -> Void
            │   ): Void
            // Статус подписки по текущему push-токену/провайдеру
            ├── func current(
            │       completion: @escaping @Sendable (
            │           ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?
            │       ) -> Void
            │   ): Void
            // Статус последней подписки по указанному провайдеру (если nil — используется текущий)
            └── func latestForProvider(
                    provider: String? = nil,
                    completion: @escaping @Sendable (
                        ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?
                    ) -> Void
                ): Void

Функции запроса статуса подписки:

func latest() — статус последней подписки профиля;
func current() — статус подписки для текущего push-токена и провайдера;
func latestForProvider() — статус последней подписки по указанному провайдеру. Если провайдер не указан (provider = nil), используется провайдер текущего push-токена.

func latest(completion: @escaping @Sendable (ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?) -> Void): Void

Функция получения статуса последней подписки профиля. В completion передаётся объект ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?, содержащий response?.profile?.subscription — последнюю созданную подписку в профиле. Если такой подписки не существует, будет передан nil.

Пример использования:

AltcraftSDK.shared.push.subscription.latest { response in
    // обработка ответа
}

func current(completion: @escaping @Sendable (ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?) -> Void): Void

Функция получения статуса подписки для текущего push-токена и провайдера. В completion передаётся объект ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?, содержащий response?.profile?.subscription — подписку, найденную по текущему push-токену и провайдеру. Если такой подписки не существует, будет передан nil.

Пример использования:

AltcraftSDK.shared.push.subscription.current { response in
    // обработка ответа
}

func latestForProvider(provider: String? = nil, completion: @escaping @Sendable (ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?) -> Void): Void

Функция получения статуса последней подписки по провайдеру. В completion передаётся объект ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?, содержащий response?.profile?.subscription — последнюю созданную подписку с указанным провайдером push-уведомлений. Если провайдер не указан (provider = nil), используется провайдер текущего push-токена. Если такой подписки не существует, будет передан nil.

Пример использования:

AltcraftSDK.shared.push.subscription.latestForProvider(provider: nil) { response in
    // обработка ответа
}

Ниже представлен пример извлечения данных о профиле, подписке и категориях из ответа функций получения статуса. Данный подход актуален для всех функций получения статуса:

Данные из функций получения статуса

AltcraftSDK.shared.push.subscription.current { response in
    // HTTP code
    let httpCode = response?.httpCode

    // Response
    let resp = response?.response
    let error = resp?.error
    let errorText = resp?.errorText

    // Profile
    let profile = resp?.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
}

В случае успешно выполненного запроса будет создано событие pushStatusRequestSuccessful. В случае ошибки — pushStatusRequestFailed.

Push: управление push-токенами

AltcraftSDK
└── static let shared: AltcraftSDK
    └── var push: Push
        └── var token: TokenAPI
            // Сохранить токен вручную
            ├── func setToken(
            │       provider: String,
            │       pushToken: Any?
            │   ): Void
            // Получить текущие данные токена устройства
            ├── func getToken(
            │       completion: (@Sendable (TokenData?) -> Void)? = nil
            │   ): Void
            // Установить провайдера Apple Push Notification service (nil — удалить)
            ├── func setAPNSTokenProvider(
            │       _ provider: APNSInterface?
            │   ): Void
            // Установить провайдера Firebase Cloud Messaging (nil — удалить)
            ├── func setFCMTokenProvider(
            │       _ provider: FCMInterface?
            │   ): Void
            // Установить провайдера Huawei Mobile Services (nil — удалить)
            ├── func setHMSTokenProvider(
            │       _ provider: HMSInterface?
            │   ): Void
            // Удалить токен push указанного провайдера
            ├── func deleteToken(
            │       provider: String,
            │       completion: (@Sendable () -> Void)? = nil
            │   ): Void
            // Принудительное обновление токена (удалить —> обновить)
            ├── func forcedTokenUpdate(
            │       completion: (@Sendable () -> Void)? = nil
            │   ): Void
            // Изменить список приоритетов провайдеров и инициировать обновление токена
            └── func changeProviderPriority(
                    _ list: [String]
                ): Void

Функции для работы с токеном провайдера в SDK:

func setToken() — ручная установка push-токена устройства и провайдера в локальном хранилище;
func getToken() — получение текущего push-токена;
func setAPNSTokenProvider() — установка и снятие провайдера Apple Push Notification service;
func setFCMTokenProvider() — установка и снятие провайдера Firebase Cloud Messaging;
func setHMSTokenProvider() — установка и снятие провайдера Huawei Mobile Services;
func changeProviderPriority() — динамическая смена порядка провайдеров с обновлением push-токена подписки;
func deleteToken() — удаление push-токена указанного провайдера;
func forcedTokenUpdate() — удаление текущего push-токена с последующим обновлением.

func setToken(provider: String, pushToken: Any?): Void

Функция предназначена для ручной установки push-токена устройства и провайдера. Используется как упрощённый вариант передачи push-токена в SDK без реализации протоколов провайдеров.

Не рекомендуется использовать эту функцию для передачи токена. Рекомендуемый подход передачи push-токена в SDK — реализация FCMInterface, HMSInterface или APNSInterface.

Пример использования:

AltcraftSDK.shared.push.token.setToken(provider: "ios-apns", pushToken: "your token")

func getToken(completion: (@Sendable (TokenData?) -> Void)? = nil): Void

Функция передаёт в completion объект TokenData(provider: String, token: String), содержащий текущий push-токен устройства и его провайдера. Если push-токен недоступен, в completion будет передано nil.

Пример использования:

AltcraftSDK.shared.push.token.getToken { data in
    let provider = data?.provider
    let token = data?.token
}

func setFCMTokenProvider(_ provider: FCMInterface?): Void

Функция устанавливает или снимает провайдера токенов Firebase Cloud Messaging. Чтобы отключить провайдера, передайте nil.

Пример использования:

AltcraftSDK.shared.push.token.setFCMTokenProvider(FCMProvider())

Важно

Вызывайте setFCMTokenProvider() в AppDelegate.application(_:didFinishLaunchingWithOptions:) до вызова AltcraftSDK.shared.initialization(). Это гарантирует регистрацию провайдера на старте процесса приложения, независимо от состояния жизненного цикла других компонентов и того, запущено приложение в foreground или background.

func setHMSTokenProvider(_ provider: HMSInterface?): Void

Функция устанавливает или снимает провайдера токенов Huawei Mobile Services. Чтобы отключить провайдера, передайте nil.

AltcraftSDK.shared.push.token.setHMSTokenProvider(HMSProvider())

Важно

Вызывайте setHMSTokenProvider() в AppDelegate.application(_:didFinishLaunchingWithOptions:) до вызова AltcraftSDK.shared.initialization(). Это гарантирует регистрацию провайдера на старте процесса приложения, независимо от состояния жизненного цикла других компонентов и того, запущено приложение в foreground или background.

func setAPNSTokenProvider(_ provider: APNSInterface?): Void

Функция устанавливает или снимает провайдера токенов Apple Push Notification service. Чтобы отключить провайдера, передайте nil.

AltcraftSDK.shared.push.token.setAPNSTokenProvider(APNSProvider())

Важно

Вызывайте setAPNSTokenProvider() в AppDelegate.application(_:didFinishLaunchingWithOptions:) до вызова AltcraftSDK.shared.initialization(). Это гарантирует регистрацию провайдера на старте процесса приложения, независимо от состояния жизненного цикла других компонентов и того, запущено приложение в foreground или background.

func changeProviderPriority(_ list: [String]): Void

Функция, позволяющая выполнить динамическую смену push-провайдера с обновлением токена подписки. Для этого необходимо передать новый массив с другим порядком провайдеров. Например: [PushConstants.ProviderName.firebase, PushConstants.ProviderName.apns, PushConstants.ProviderName.huawei].

Пример использования:

AltcraftSDK.shared.push.token.changeProviderPriority([
    PushConstants.ProviderName.firebase,
    PushConstants.ProviderName.apns,
    PushConstants.ProviderName.huawei
])

func deleteToken(provider: String, completion: (@Sendable () -> Void)? = nil): Void

Функция удаления push-токена указанного провайдера. Токен инвалидируется и удаляется из локального кеша на устройстве и с сервера push-провайдера. После удаления можно запросить новый токен. Для провайдера APNs удаление не поддерживается — будет зафиксирована ошибка apnsIsNotUpdated.

Пример использования:

AltcraftSDK.shared.push.token.deleteToken(provider: "ios-firebase") {
    // токен удалён
}

func forcedTokenUpdate(completion: (@Sendable () -> Void)? = nil): Void

Функция удаления текущего push-токена с его последующим обновлением. Для APNs операция не поддерживается — будет зафиксирована ошибка apnsIsNotUpdated.

Пример использования:

AltcraftSDK.shared.push.token.forcedTokenUpdate {
    // токен обновлён
}

Пример регистрации провайдеров

Мы не рекомендуем использовать функцию setToken для установки push-токена. Вместо этого настройте функции получения токена для каждого используемого провайдера. Ниже указан пример реализации этого метода:

Рекомендуемый способ регистрации провайдеров в AppDelegate

class AppDelegate: UIResponder, UIApplicationDelegate {
    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.push.token.setAPNSTokenProvider(APNSProvider())

        // FCM provider
        AltcraftSDK.shared.push.token.setFCMTokenProvider(FCMProvider())

        // HMS provider
        AltcraftSDK.shared.push.token.setHMSTokenProvider(HMSProvider())

        AltcraftSDK.shared.push.notificationManager.registerForPushNotifications(for: application)

        let config = AltcraftConfiguration.Builder(
            apiUrl: "your api url"
        ).build()
        AltcraftSDK.shared.initialization(configuration: config)

        return true
    }
}

Push: передача push-уведомлений в SDK

// Используется внутри Notification Service Extension (NSE) — фасад для обработки
// push-уведомлений Altcraft, определения уведомлений Altcraft и регистрации целей
// без зависимости от UIApplication
AltcraftNSE
// Общий (singleton) экземпляр для централизованной логики NSE
├─ static let shared: AltcraftNSE
// Проверка, относится ли уведомление к Altcraft
├─ func isAltcraftPush(
│       _ request: UNNotificationRequest
│   ) -> Bool
// Обработка входящего уведомления Altcraft: передача изменённого содержимого в contentHandler
├─ func handleNotificationRequest(
│       request: UNNotificationRequest,
│       contentHandler: @escaping (UNNotificationContent) -> Void
│   ): Void
// Вызов по истечении времени работы NSE
├─ func serviceExtensionTimeWillExpire(): Void
// Установка App Group и инициализация общего контейнера данных
├─ func setAppGroup(groupName: String?): Void
// Регистрация JWT-провайдера
└─ func setJWTProvider(provider: JWTInterface): Void

Функции класса AltcraftNSE:

func isAltcraftPush() — функция проверки источника уведомления;
func handleNotificationRequest() — функция, принимающая UNNotificationRequest из Notification Service Extension для его дальнейшей обработки на стороне SDK;
func serviceExtensionTimeWillExpire() — функция, вызывающаяся по истечении времени работы Notification Service Extension (~30 секунд).

func isAltcraftPush(_ request: UNNotificationRequest) -> Bool

Функция SDK, проверяющая, является ли источником уведомления Altcraft по маркеру в userInfo.

Пример использования:

let isAltcraft = AltcraftNSE.shared.isAltcraftPush(request)

func handleNotificationRequest(request: UNNotificationRequest, contentHandler: @escaping (UNNotificationContent) -> Void): Void

Функция SDK, принимающая UNNotificationRequest из Notification Service Extension для его обработки на стороне SDK и дальнейшего показа уведомления.

Пример использования:

if AltcraftNSE.shared.isAltcraftPush(request) {
    AltcraftNSE.shared.handleNotificationRequest(request: request) { content in
        contentHandler(content)
    }
}

func serviceExtensionTimeWillExpire()

Функция, которая вызывается системой по истечении времени работы Notification Service Extension (~30 секунд).

Пример использования:

AltcraftNSE.shared.serviceExtensionTimeWillExpire()

func setAppGroup(groupName: String?): Void

Функция для установки идентификатора AppGroup (обязательная установка). В NSE вызывается до обработки уведомлений.

Пример использования:

AltcraftNSE.shared.setAppGroup(groupName: "group.your.app.id")

func setJWTProvider(provider: JWTInterface): Void

Функция для установки JWT-провайдера:

AltcraftNSE.shared.setJWTProvider(provider: jwtProvider)

Получение уведомлений в приложении

По умолчанию обработку входящих push-уведомлений выполняет SDK: NotificationManager назначается делегатом центра уведомлений, показывает уведомления и выполняет стандартную логику обработки клика.

Если приложению нужен доступ к содержимому уведомления в foreground (например, для аналитики или кастомного UI) или к данным уведомления при клике, используйте NotificationManager.

События центра уведомлений (SDK публикует их в NotificationCenter):

.altcraftPushWillPresent — уведомление показывается в foreground, userInfo: ["notification": UNNotification];
.altcraftPushDidReceive — пользователь нажал на уведомление или выполнил action, userInfo: ["response": UNNotificationResponse].

Режимы делегирования обработки приложению:

customPushProcessing — true — обработка и выбор способа показа уведомления в foreground передаётся приложению; false — SDK использует стандартную логику показа;
customClickProcessing — true — обработка клика по уведомлению полностью передаётся приложению; false — SDK использует стандартную логику обработки клика.

Получение foreground-уведомления в приложении (опционально)

Настройка, описанная ниже, требуется только если вам нужен доступ к содержимому уведомления в foreground или вы хотите самостоятельно управлять показом уведомления (показывать/скрывать, менять presentation options).

// Доступ к менеджеру push-уведомлений SDK
let manager = AltcraftSDK.shared.push.notificationManager

// Управление обработкой push-уведомлений в foreground.
// true  — обработка и выбор способа показа передаётся приложению.
// false — SDK использует стандартную логику показа уведомлений.
manager.customPushProcessing = false

// Колбэк для обработки push-уведомлений в foreground.
// Вызывается при получении уведомления, когда приложение активно.
// complete(...) должен быть вызван только при customPushProcessing = true.
manager.onForegroundNotification = { notification, complete in
    // Пользовательская логика обработки уведомления

    // Важно: вызывать complete(...) нужно только если manager.customPushProcessing = true
    if #available(iOS 14.0, *) {
        complete([.banner, .badge, .sound])
    } else {
        complete([.alert, .badge, .sound])
    }

    // или [] чтобы не показывать
}

Если customPushProcessing = false, SDK применяет стандартные параметры показа уведомления, а callback (если задан) вызывается только для дополнительной логики приложения. Если customPushProcessing = true, приложение должно самостоятельно вызвать complete(...), иначе уведомление в foreground может быть не показано.

Получение события клика по уведомлению в приложении (опционально)

Настройка, описанная ниже, требуется только если приложению необходимо получить доступ к данным уведомления при клике, требуется собственная логика обработки переходов или действий, либо нужно полностью перехватить обработку клика на стороне приложения.

let manager = AltcraftSDK.shared.push.notificationManager

// Управление обработкой кликов по уведомлениям.
// true  — обработка клика полностью передаётся приложению.
// false — SDK использует стандартную логику обработки клика.
manager.customClickProcessing = true

// Колбэк обработки клика по уведомлению.
// Вызывается при нажатии на уведомление или выполнении action.
// complete() должен быть вызван обязательно при customClickProcessing = true.
manager.onNotificationClick = { response, complete in
    // Данные уведомления
    let userInfo = response.notification.request.content.userInfo

    // Пользовательская логика обработки клика
    print("push click")

    // Завершение обработки
    complete()
}

Если customClickProcessing = false, SDK самостоятельно обрабатывает клик по уведомлению, отправляет соответствующие события и завершает обработку. Callback onNotificationClick в этом случае (если задан) вызывается только для дополнительной логики приложения.

Если customClickProcessing = true, приложение обязано вызвать complete(). Без вызова complete() система iOS будет считать обработку клика незавершённой, что может привести к некорректному поведению приложения.

События push: доставка и открытие

AltcraftSDK
└── static let shared: AltcraftSDK
    └── var push: Push
        └── var pushEvents: EventAPI
            // Сообщить о доставке push-уведомления
            ├── func deliveryEvent(
            │       from request: UNNotificationRequest
            │   ): Void
            // Сообщить об открытии push-уведомления
            └── func openEvent(
                    from request: UNNotificationRequest
                ): Void

Функции регистрации событий push-уведомлений:

func deliveryEvent() — сообщает платформе о доставке push-уведомления на устройство. При стандартной обработке SDK регистрируется автоматически;
func openEvent() — сообщает платформе об открытии push-уведомления пользователем. Если обработку клика вы выполняете самостоятельно (customClickProcessing = true), событие открытия необходимо регистрировать вручную.

Пример использования:

AltcraftSDK.shared.push.pushEvents.openEvent(from: request)

Цели (target)

Модуль target регистрирует цели (mobile events) — события на платформе Altcraft: установки, покупки, подписки и другие, к которым на платформе привязаны пиксели, сегменты и сценарии.

AltcraftSDK
└── static let shared: AltcraftSDK
    └── var target: Target
        // Отправить цель (target-событие) на сервер
        └── func sendTarget(
                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

Кейс: Передача информации о рекламной кампании

Информация о рекламной кампании приложения, которая привела к установке, может быть передана в платформу как значение параметров profileFields/customFields функции subscribe, а также параметров utm или payload функции sendTarget(). Получив UTM-метку в приложении как строку, необходимо вызвать функцию sendTarget():

Передача через payload

AltcraftSDK.shared.target.sendTarget(
    sid: "your sid",
    eventName: "app_install",
    payload: ["utm": "your utm tag"]
)

Событие достижения цели пикселя с UTM-метками

Передача в поля UTM

AltcraftSDK.shared.target.sendTarget(
    sid: "your sid",
    eventName: "app_install",
    utm: UTM(
        campaign: "your campaign utm",
        content:  "your content utm",
        keyword: "your keyword utm",
        medium: "your medium utm",
        source: "your source utm",
        temp: "your temp utm"
    )
)

Передаваемые UTM-метки с полями кампании и источника

Передача в пользовательское поле профиля

// передача utm-метки в поле профиля
// поля профиля должны быть предварительно добавлены в платформе
AltcraftSDK.shared.push.subscription.subscribe(
    profileFields: ["utm": "your utm tag"]
)

Пользовательские поля профиля со значением UTM

Переданные любым из этих способов данные можно использовать для создания сегмента в платформе.

Обратите внимание, что при настройке на iOS приложение должно использовать AppsFlyer, иначе UTM-метка не будет передана в приложение.

Для регистрации цели используйте функцию sendTarget(). Она имеет следующие параметры:

sid: String

Обязательный: Да
Описание: Строковый идентификатор пикселя, к которому привязываются цели.

altcraftClientID: String

По умолчанию: ""
Обязательный: Нет
Описание: Идентификатор клиента Altcraft.

eventName: String

Обязательный: Да
Описание: Имя цели (mobile event).

sendMessageId: String?

Обязательный: Нет
Описание: SMID-идентификатор отправленного сообщения (если цель связана с конкретной рассылкой).

payload: [String: Any?]?

Обязательный: Нет
Описание: Данные цели — карта со строковыми ключами, для которых допускаются только скалярные типы данных:

String
Bool
Int
Int64 / UInt64 (или эквиваленты NSNumber)
Float
Double
nil

Обратите внимание

Несериализуемые объекты (например, Date без преобразования, кастомные классы) приведут к ошибке кодирования.

matching: [String: Any?]?

Обязательный: Нет
Описание: Карта, в которую можно передавать значения с типами и идентификаторами матчинга.

matchingType: String?

Обязательный: Нет
Описание: Тип матчинга.

profileFields: [String: Any?]?

Обязательный: Нет
Описание: Поля профиля — карта со строковыми ключами и значениями (JSON-совместимые типы):

Скалярные значения:
- String
- Bool
- Int
- Int64 / UInt64 (или эквиваленты NSNumber)
- Float
- Double
- nil
Объекты: [String: Any?]
Списки: [Any?]
Массивы карт: [[String: Any?]]

Обратите внимание

Параметр используется только при работе с JWT-авторизацией.

utm: UTM?

Обязательный: Нет
Описание: UTM-метки. Добавляются с помощью struct UTM, где каждый вид 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?
}

subscription: (any Subscription)?

Обязательный: Нет
Описание: Параметр добавления подписки для выбранного канала.

Значения параметра — реализации протокола Subscription:

EmailSubscription — email-подписка
SmsSubscription — SMS-подписка
PushSubscription — push-подписка
CcDataSubscription — подписка в Telegram, Whatsapp, Viber, Notify.

Обратите внимание

Используется только при работе с JWT-авторизацией.

Реализации протокола `Subscription`

Общая модель: Subscription

Назначение — базовый протокол для всех видов подписок. Сериализация полиморфная, поле-дискриминатор — channel.

Общие поля (для всех реализаций):

Поле	Тип	Обязательный	Описание
`resource_id`	`Int`	Да	Идентификатор ресурса/источника подписки
`status`	`String?`	Нет	Статус подписки (например, активна/приостановлена)
`priority`	`Int?`	Нет	Приоритет доставки для данной подписки
`custom_fields`	`[String: JSONValue]?`	Нет	Пользовательские поля (ключ-значение) для расширенной сегментации
`cats`	`[String]?`	Нет	Категории подписки
`channel`	`String`	Да	Тип канала; фиксируется реализацией.

Варианты подписки:

EmailSubscription (channel = "email")

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`email`	`String`	Да	Адрес электронной почты получателя

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String?`	Нет	Статус подписки
`priority`	`Int?`	Нет	Приоритет подписки
`customFields`	`[String: JSONValue]?`	Нет	Стандартные и пользовательские поля подписки
`cats`	`[String]?`	Нет	Категории подписки

SmsSubscription (channel = "sms")

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`phone`	`String`	Да	Номер телефона в международном формате

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String?`	Нет	Статус подписки
`priority`	`Int?`	Нет	Приоритет подписки
`customFields`	`[String: JSONValue]?`	Нет	Стандартные и пользовательские поля подписки
`cats`	`[String]?`	Нет	Категории подписки

PushSubscription (channel = "push")

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`provider`	`String`	Да	Провайдер (например, `"ios-apns"`)
`subscriptionId`	`String`	Да	Уникальный идентификатор подписки у провайдера

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String?`	Нет	Статус подписки
`priority`	`Int?`	Нет	Приоритет подписки
`customFields`	`[String: JSONValue]?`	Нет	Стандартные и пользовательские поля подписки
`cats`	`[String]?`	Нет	Категории подписки

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

Основные поля

Поле	Тип	Обязательный	Описание
`resourceId`	`Int`	Да	ID ресурса Altcraft
`channel`	`String`	Да	Один из: `"telegram_bot"`, `"whatsapp"`, `"viber"`, `"notify"`
`ccData`	`[String: JSONValue]`	Да	Канал-специфичные данные (например, chat ID, номер, токены)

Дополнительные поля

Поле	Тип	Обязательный	Описание
`status`	`String?`	Нет	Статус подписки
`priority`	`Int?`	Нет	Приоритет подписки
`customFields`	`[String: JSONValue]?`	Нет	Стандартные и пользовательские поля подписки
`cats`	`[String]?`	Нет	Категории подписки

Profile: обновление полей профиля

Важно

Обновление полей профиля с помощью функции updateProfileFields() работает только при использовании JWT-авторизации API-запросов SDK.

AltcraftSDK
└── static let shared: AltcraftSDK
    └── var profile: Profile
        // Обновляет поля профиля Altcraft
        └── var update: UpdateAPI
            └── func updateProfileFields(
                    profileFields: [String: Any?]? = nil,
                    skipTriggers: Bool? = nil
                ): Void

Для обновления полей профиля используйте функцию updateProfileFields(). Она имеет следующие параметры:

profileFields: [String: Any?]?

Обязательный: Нет
Описание: Поля профиля — карта, содержащая значения для полей, которые необходимо изменить (JSON-совместимые типы):

Скалярные значения:
- String
- Bool
- Int
- Int64 / UInt64 (или эквиваленты NSNumber)
- Float
- Double
- nil
Объекты: [String: Any?]
Списки: [Any?]
Массивы карт: [[String: Any?]]

Обратите внимание

Для того чтобы обновление прошло успешно, поля должны быть предварительно добавлены в профиль подписчика.

skipTriggers:Bool?

Пример использования:

AltcraftSDK.shared.profile.update.updateProfileFields(
    profileFields: ["_fname": "Andrey"]
)

In-App уведомления

AltcraftSDK
└── static let shared: AltcraftSDK
    └── var inApp: InApp
        // Подписаться на жизненный цикл приложения для автоматического показа In-App
        ├── func registerLifecycleTracking(): Void
        // Установить маркер текущего экрана (используется при фильтрации In-App уведомлений)
        ├── func setScreen(screen: String): Void
        // Триггер In-App уведомления по имени
        ├── func trigger(name: String): Void
        // Запрос доступных размещений In-App
        ├── func getPlacements(): Void
        // Настроить анимацию In-App уведомления
        ├── func animation(_ block: @escaping @MainActor (InAppAnimator) -> Void): Void
        // Управление подписками на In-App уведомления
        └── var subscription: SubscribeAPI
            // Подписка на In-App уведомления (status = SUBSCRIBED)
            ├── func subscribe(
            │     sync: Bool = true,
            │     profileFields: [String: Any?]? = nil,
            │     customFields: [String: Any?]? = nil,
            │     cats: [CategoryData]? = nil,
            │     replace: Bool? = nil,
            │     skipTriggers: Bool? = nil
            │   ): Void
            // Отписка от In-App уведомлений (status = UNSUBSCRIBED)
            ├── func unSubscribe(
            │     sync: Bool = true,
            │     profileFields: [String: Any?]? = nil,
            │     customFields: [String: Any?]? = nil,
            │     cats: [CategoryData]? = nil,
            │     replace: Bool? = nil,
            │     skipTriggers: Bool? = nil
            │   ): Void
            // Статус подписки на In-App уведомления
            └── func getSubscriptionStatus(
                    completion: @escaping @Sendable (
                        ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?
                    ) -> Void
                ): Void

Функции для работы с In-App уведомлениями:

func registerLifecycleTracking() — регистрация наблюдателей жизненного цикла приложения для автоматического показа In-App уведомлений;
func setScreen() — установка маркера текущего экрана, используется при фильтрации In-App уведомлений. При смене экрана SDK автоматически генерирует триггер openPage (тип default);
func trigger() — триггер In-App уведомления по имени (тип custom);
func getPlacements() — запрос доступных размещений In-App с сервера;
func animation() — настройка анимации показа In-App уведомления;
func subscription.subscribe() — подписка на In-App уведомления;
func subscription.unSubscribe() — отписка от In-App уведомлений;
func subscription.getSubscriptionStatus() — получение статуса подписки на In-App уведомления.

func registerLifecycleTracking()

Функция регистрирует наблюдателей жизненного цикла приложения для автоматического показа In-App уведомлений. После регистрации SDK отслеживает событие UIApplication.didBecomeActiveNotification и генерирует триггер openApp (тип default) один раз при первом переходе приложения в foreground.

Важно

Вызывайте registerLifecycleTracking() как можно раньше на старте приложения — в AppDelegate.application(_:didFinishLaunchingWithOptions:). Это необходимо для того, чтобы наблюдатели жизненного цикла успели зарегистрироваться до первого перехода приложения в foreground. Если вызов будет выполнен с задержкой, In-App уведомления, которые должны были показаться при старте приложения, могут быть пропущены.

Пример использования:

AltcraftSDK.shared.inApp.registerLifecycleTracking()

func setScreen(screen: String)

Функция устанавливает маркер текущего экрана. Значение маркера используется платформой Altcraft при фильтрации In-App уведомлений — позволяет показывать уведомления только на определённых экранах приложения.

При смене экрана SDK автоматически генерирует триггер openPage (тип default). Вызывайте эту функцию при переходе на новый экран, чтобы SDK всегда знал, на каком экране находится пользователь.

Пример использования:

AltcraftSDK.shared.inApp.setScreen(screen: "home_screen")

func trigger(name: String)

Функция позволяет вручную запустить показ In-App уведомления по его имени. Генерирует триггер типа custom с указанным именем. Используется, когда необходимо показать уведомление в ответ на действие пользователя или событие в приложении.

Пример использования:

AltcraftSDK.shared.inApp.trigger(name: "my_custom_trigger")

func getPlacements()

Функция выполняет запрос доступных In-App размещений с сервера Altcraft. Результат запроса можно получить через события SDK.

Если в конфигурации SDK установлен параметр inAppAutoRequest = true, запрос размещений выполняется автоматически при инициализации и далее с интервалом placementsRequestInterval. Перед автоматическим запросом SDK проверяет время последнего успешного запроса: если заданный интервал ещё не прошёл, автоматический запрос не выполняется. Ручной вызов getPlacements() интервалом не ограничивается. Без этого параметра запросы выполняются только по явному вызову getPlacements() или при срабатывании триггеров.

Пример использования:

AltcraftSDK.shared.inApp.getPlacements()

func animation(_ block: @escaping @MainActor (InAppAnimator) -> Void)

Функция позволяет настроить собственную анимацию показа In-App уведомления. Принимает closure с параметром InAppAnimator, предоставляющим доступ к UIView и companyId после загрузки статических ресурсов.

Протокол InAppAnimator:

public protocol InAppAnimator {
    // Идентификатор кампании, связанной с аниматором
    var companyId: Int { get }

    // Применяет изменения к view без анимации
    @MainActor
    func prepare(_ block: (UIView) -> Void)

    // Выполняет UIKit-анимацию для In-App view
    @MainActor
    func animate(
        duration: TimeInterval,
        delay: TimeInterval,
        options: UIView.AnimationOptions,
        animations: @escaping (UIView) -> Void,
        completion: ((Bool) -> Void)?
    )
}

Пример использования:

AltcraftSDK.shared.inApp.animation { animator in
    animator.animate(
        duration: 0.3,
        delay: 0,
        options: .curveEaseInOut,
        animations: { view in
            view.alpha = 1.0
        },
        completion: nil
    )
}

func subscription.subscribe(sync: Bool, ...)

Функция выполняет подписку на In-App уведомления. После успешного вызова профиль пользователя будет подписан на получение In-App уведомлений от платформы Altcraft.

Параметры функции аналогичны параметрам subscribe():

sync — флаг синхронности выполнения запроса;
profileFields — поля профиля;
customFields — поля подписки;
cats — категории подписки;
replace — при активации заменяет существующую подписку;
skipTriggers — при активации профиль будет игнорироваться в триггерах рассылок и сценариев.

Параметры настраиваются точно так же, как и в subscribe().

Пример использования:

AltcraftSDK.shared.inApp.subscription.subscribe()

func subscription.unSubscribe(sync: Bool, ...)

Функция отменяет подписку на In-App уведомления. После успешного вызова профиль пользователя будет отписан от получения In-App уведомлений.

Параметры функции аналогичны параметрам unsubscribe().

Пример использования:

AltcraftSDK.shared.inApp.subscription.unSubscribe()

func subscription.getSubscriptionStatus(completion: @escaping @Sendable (ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?) -> Void)

Функция получения текущего статуса подписки на In-App уведомления. В completion передаётся объект ResponseModel.ResponseWithHttpCode<ResponseModel.ResponseWithProfile>?, содержащий response?.profile?.subscription — текущую подписку профиля на In-App уведомления. При ошибке выполнения запроса будет передано nil. Отсутствие подписки определяется по значению response?.profile?.subscription == nil.

Пример использования:

AltcraftSDK.shared.inApp.subscription.getSubscriptionStatus { response in
    let httpCode = response?.httpCode
    let resp = response?.response
    let profile = resp?.profile
    let subscription = profile?.subscription
}

Типы отображения In-App уведомлений

SDK поддерживает следующие типы отображения In-App уведомлений:

Тип	Описание
`fullscreen`	Полноэкранное In-App уведомление
`floating_bar`	Плавающая панель (поведение аналогично полноэкранному)
`slideup`	Выезжающая панель сверху или снизу экрана. SDK ожидает от JavaScript данные о размере и позиции, затем применяет нативный контейнер. Если JavaScript не отвечает в течение 1 секунды, уведомление показывается как полноэкранное
`custom`	Пользовательское отображение (поведение аналогично полноэкранному)
`modal`	Модальное окно (поведение аналогично полноэкранному)

Ограничения показа In-App уведомлений

In-App уведомления не показываются в ландшафтной ориентации экрана;
При повороте экрана открытое In-App уведомление закрывается;
Показы In-App уведомлений сериализованы — одновременно может быть показано только одно уведомление;
Неанонимные In-App кампании требуют статуса подписки subscribed на In-App уведомления.

Core: авторизация​

Очистка данных SDK​

Core: события SDK​

Подписка на события​

Отписка от событий​

Список всех событий SDK​

Push: работа со статусами подписки​

Изменение статуса подписки​

Запрос статуса подписки​

Push: управление push-токенами​

Пример регистрации провайдеров​

Push: передача push-уведомлений в SDK​

Получение уведомлений в приложении​

Получение foreground-уведомления в приложении (опционально)​

Получение события клика по уведомлению в приложении (опционально)​

События push: доставка и открытие​

Цели (target)​

Реализации протокола Subscription​

Profile: обновление полей профиля​

In-App уведомления​

Типы отображения In-App уведомлений​

Ограничения показа In-App уведомлений​

Core: авторизация

Очистка данных SDK

Core: события SDK

Подписка на события

Отписка от событий

Список всех событий SDK

Push: работа со статусами подписки

Изменение статуса подписки

Запрос статуса подписки

Push: управление push-токенами

Пример регистрации провайдеров

Push: передача push-уведомлений в SDK

Получение уведомлений в приложении

Получение foreground-уведомления в приложении (опционально)

Получение события клика по уведомлению в приложении (опционально)

События push: доставка и открытие

Цели (target)

Реализации протокола `Subscription`

Profile: обновление полей профиля

In-App уведомления

Типы отображения In-App уведомлений

Ограничения показа In-App уведомлений