Конфигурация SDK

Предварительные условия

• SDK провайдеров push-уведомлений интегрированы в проект приложения (см. инструкции по интеграции push-провайдеров).
• Выполнена загрузка пакета Altcraft с помощью Swift Package Manager.

Подготовка приложения

Настройка таргета

Настройте следующие параметры таргета приложения:

• General

При использовании Swift Package Manager проверьте, что библиотека Altcraft добавлена в Frameworks, Libraries, and Embedded Content таргета приложения.

• Signing & Capabilities

Добавьте следующие Capabilities:

• PushNotifications;
• AppGroups;
• Background Modes (Background fetch, Background processing).

• Info

Добавьте key Permitted background task scheduler identifiers и value "lib.Altcraft.bgTask.systemControl". Это необходимо для регистрации bgTask-задачи, которая будет выполнять повтор неудачных запросов к серверу в background-режиме.

• Опционально:

При использовании Firebase Cloud Messaging добавьте ключ FirebaseAppDelegateProxyEnabled (Boolean) с значением NO. Это отключит автоматическую подмену (method swizzling) методов AppDelegate, которую Firebase Messaging выполняет по умолчанию.

Настройка AppDelegate

Далее необходимо выполнить в AppDelegate.application(_:didFinishLaunchingWithOptions:) следующие действия:

• передать идентификатор AppGroup в SDK
• зарегистрировать BGTask (фоновые задачи SDK)
• (опционально) инициализировать функции UNUserNotificationCenter на стороне SDK

---

Установка идентификатора AppGroup

Добавление идентификатора AppGroup необходимо для обмена информацией с Notification Service Extension и требуется для корректной работы SDK. Выполняется с помощью функции setAppGroup():

AltcraftSDK.shared.setAppGroup(groupName: String)

---

Регистрация BGTask

Регистрация фоновых задач SDK необходима для повторной отправки неуспешных запросов в фоновом режиме. Выпоняется с помощью функции registerBackgroundTask():

AltcraftSDK.shared.backgroundTasks.registerBackgroundTask()

---

Инициализация функций UNUserNotificationCenter (опционально)

SDK содержит класс NotificationManager который выполняет следующие задачи:

• настраивает UNUserNotificationCenter и запрашивает разрешение на уведомление (alert/sound/badge);
• обеспечивает вызов UIApplication.registerForRemoteNotifications() и гарантирует корректную регистрацию в APNs;
• отображает уведомления в foreground;
• обрабатывает клики по уведомлениям и кнопкам — выполняет переход на указанный URL или открывает приложение;
• регистрирует push-событие открытия ("open").

Для использования класса SDK NotificationManager вызовите функцию в AppDelegate.application(_:didFinishLaunchingWithOptions:):

func registerForPushNotifications(for application: UIApplication, completion: ((_ granted: Bool, _ error: Error?) -> Void)? = nil): Void

Данная функция назначает делегата, запрашивает разрешение у пользователя и регистрирует приложение для получения push-уведомлений на стороне SDK.

Пример корректного заполнения AppDelegate.application

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let appGroup = "group.your.id"

        //ID App Group Setup
        AltcraftSDK.shared.setAppGroup(groupName: appGroup)
        
        //Backgroung SDK task registration
        AltcraftSDK.shared.backgroundTasks.registerBackgroundTask()
        
        //SDK UNUserNotificationCenter functions initialization
        AltcraftSDK.shared.notificationManager.registerForPushNotifications(for: application)
        
        //Other functions
        
        return true
    }
    //Other functions AppDelegate
}

Использование этого класса опционально, вы можете заменить его своей реализацией. Для этого:

• назначьте делегата центра уведомлений:
  UNUserNotificationCenter.current().delegate = self;
• запросите разрешения на уведомления и вызовите UIApplication.shared.registerForRemoteNotifications() строго на главном потоке;
• реализуйте метод userNotificationCenter(_:willPresent:withCompletionHandler:) для отображения уведомлений в foreground (banner/alert/sound/badge);
• вызовите AltcraftSDK.shared.pushEventFunctions.openEvent(from:) в userNotificationCenter(_:didReceive:withCompletionHandler:) при обработке нажатия на уведомление (регистрация события "open");
• реализуйте собственную логику обработки кликов по уведомлению (URL/Deep Link/кнопки), не забудьте при этом продумать fallback-сценарий (навигацию по умолчанию при отсутствии валидной ссылки).

---

Настройка JWT-протокола (опционально)

JWTInterface — протокол запроса JWT-токена. Предоставляет актуальный JWT-токен из приложения по запросу SDK. Реализация данного протокола требуется, если используется JWT-аутентификация API-запросов. JWT подтверждает, что пользовательские идентификаторы аутентифицированы приложением.

Реализация JWT-аутентификации обязательна, если используется тип матчинга отличный от push-данных из подписки (например, идентификатор пользователя — email или телефон).

Протокол SDK:

public protocol JWTInterface {
    func getToken() -> String?
}

Реализация на стороне приложения

import Altcraft

class JWTProvider: JWTInterface {
    func getToken() -> String? {
         //ваш код, который возвращает JWT
      }
}

Регистрация провайдера в application(_:didFinishLaunchingWithOptions:)

В AppDelegate укажите:

class AppDelegate: UIResponder, UIApplicationDelegate, MessagingDelegate, UNUserNotificationCenterDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    //Другой код
    
    AltcraftSDK.setJWTProvider(provider: JWTProvider())
  }
  //Другие функции
}

К сведению

getJWT() — синхронная функция. Поток выполнения SDK будет приостановлен до получения JWT. Рекомендуется, чтобы getJWT() возвращал значение немедленно — из кэша (in-memory, SharedPreferences или EncryptedSharedPreferences) — это ускорит выполнение запросов. Желательно подготовить актуальный JWT как можно раньше (на старте приложения) и сохранить его в кэш, чтобы при обращении SDK токен был доступен без задержек. При отсутствии значения допустимо вернуть nil.

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

Данная реализация протоколов запроса и удаления push-токена гарантирует использование актуального токена и обеспечивает возможность динамической смены провайдеров по требованию клиента. Реализуйте протоколы только для тех push-провайдеров, которые используются в вашем проекте.

Регистрируйте провайдеры в application(_:didFinishLaunchingWithOptions:) (AppDelegate). Данная точка регистрации гарантирует раннюю, однократную и детерминированную регистрацию при старте процесса, в том числе в background.

---

Apple Push Notifcation service

APNSInterface — протокол запроса push-токена APNs. В данном протоколе отсутствует функция удаления токена, в отличии от других протоколов push-провайдеров.

Протокол SDK:

public protocol APNSInterface {

    func getToken(completion: @escaping (String?) -> Void)
}

Рекомендуемая реализация на стороне приложения

import Altcraft

class APNSProvider: APNSInterface {
    func getToken(completion: @escaping (String?) -> Void) {
        //ваш код, который возвращает токен APNs
    }
}

Регистрация провайдера в application(_:didFinishLaunchingWithOptions:)

class AppDelegate: UIResponder, UIApplicationDelegate, MessagingDelegate, UNUserNotificationCenterDelegate {
  func application(
  _ application: UIApplication, 
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    //другой код
    
    AltcraftSDK.pushTokenFunction.setAPNSTokenProvider(APNSProvider())
  }
  //другие функции
}

---

Firebase Cloud Messaging

FCMInterface — протокол запроса и удаления push-токена Firebase Cloud Messaging.

Протокол SDK:

public protocol FCMInterface {
    func getToken(completion: @escaping (String?) -> Void)
    
    func deleteToken(completion: @escaping (Bool) -> Void)
}

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

Рекомендуемая реализация на стороне приложения

import FirebaseMessaging
import Altcraft

class FCMProvider: FCMInterface {
    
    /// Извлекает текущий токен FCM
   func getToken(completion: @escaping (String?) -> Void) {
    
        ///Токен APNs (в виде данных), извлеченный из userDefault 
        let apnsToken = getAPNsTokenDataFromUserDefaults() 
        
        ///Установите токен APNs для FCM перед запросом токена FCM
        Messaging.messaging().apnsToken = apnsToken
        
        ///Функция запроса токена FCM
        Messaging.messaging().token { token, error in
            if error != nil {
                completion(nil)
            } else {
                completion(token)
            }
        }
    }

    /// Удаляет текущий токен FCM
    func deleteToken(completion: @escaping (Bool) -> Void) {
        Messaging.messaging().deleteToken { error in
            if error != nil {
                completion(false)
            } else {
                completion(true)
            }
        }
    }
}

Регистрация провайдера в application(_:didFinishLaunchingWithOptions:)

class AppDelegate: UIResponder, UIApplicationDelegate, MessagingDelegate, UNUserNotificationCenterDelegate {
  func application(
  _ application: UIApplication, 
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    //Другой код
    
    AltcraftSDK.pushTokenFunction.setFCMTokenProvider(FCMProvider())
  }
  //Другие функции
}

---

Huawei Mobile Services

HMSInterface — протокол запроса и удаления push-токена Huawei Mobile Services.

Протокол SDK:

public protocol HMSInterface {
    
    func getToken(completion: @escaping (String?) -> Void)

    func deleteToken(completion: @escaping (Bool) -> Void)
}

Рекомендуемая реализация на стороне приложения

class HMSProvider: HMSInterface {
    
    func getToken(completion: @escaping (String?) -> Void) {
    
        //переменная, содержащая токен APNs (в виде строки), который позже 
        //передается в HmsInstanceId.getInstance().getToken(apnsToken)
        guard let apnsToken = getAPNsTokenFromUserDefault() else {
            completion(nil)
            return
        }


        let token = HmsInstanceId.getInstance().getToken(apnsToken)
        completion(token)
    }
    
    
    func deleteToken(completion: @escaping (Bool) -> Void) {
        HmsInstanceId.getInstance().deleteToken()
        completion(true)
    }
}

Регистрация провайдера в application(_:didFinishLaunchingWithOptions:)

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
  func application(
  _ application: UIApplication, 
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    //Другой код
    
    AltcraftSDK.pushTokenFunction.setHMSTokenProvider(HMSProvider())
  }
  //Другие функции
}

Подготовка Notification Service Extension

Добавление расширения NSE необходимо для поддержки Rich Push и гарантированной регистрации событий доставки.

Создайте расширение приложения Notification Service Extension:

• Выполните File — New — Target — Notification Service Extension;
• Выберите название (Product Name) для таргета расширения;
• Активируйте его.

Выполните в Notification Service Extension:

• General:

• Укажите Minimum Deployments — это параметр сборки в Xcode, который определяет минимальную версию операционной системы, на которой будет работать Notification Service Extension;
• Добавьте библиотеку Altcraft в разделе Frameworks, Libraries and Embedded Content.

• Signing & Capabilities:

• Укажите идентификатор AppGroup.

Затем настройте SDK в UNNotificationServiceExtension:

• Импортируйте библиотеку Altcraft;
• В функции didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void):
• Передайте идентификатор appGroup в функцию AltcraftNSE.shared.setAppGroup(groupName: appGroupsName). Данный идентификатор должен соответствовать идентификатору переданному в SDK в таргете приложения;
• Установите провайдер JWT (если используется JWT-аутентификация запросов): AltcraftNSE.shared.setJWTProvider(provider: jwtProvider);
• Выполните проверку источника уведомления с помощью функции AltcraftNSE.shared.isAltcraftPush(request);
• После проверки источника уведомления, передайте UNNotificationRequest и contentHandler в функцию AltcraftNSE.shared.handleNotificationRequest(request: request, contentHandler: contentHandler), если источник уведомления — Altcraft.

Приведенный ниже пример реализации UNNotificationServiceExtension можно использовать как готовый класс. Замените весь автоматически сгенерированный код на эту реализацию, если вам не требуется дополнительная логика. Если вы уже используете UNNotificationServiceExtension, интегрируйте функции Altcraft в свою реализацию.

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

import Altcraft
import UserNotifications

class NotificationService: UNNotificationServiceExtension {
    
    /// - важно! Укажите идентификатор App Group.
    let appGroupID =  "group.your.id"
    
    /// - важно! Установите провайдер JWT, если используется JWT-аутентификация.
    let jwtProvider = JWTProvider()


    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {

        AltcraftNSE.shared.setAppGroup(groupName: appGroupID)
        AltcraftNSE.shared.setJWTProvider(provider: jwtProvider)
        
        if AltcraftNSE.shared.isAltcraftPush(request) {
            AltcraftNSE.shared.handleNotificationRequest(request: request, contentHandler: contentHandler)
        } else {
            contentHandler(request.content)
        }
    }
    override func serviceExtensionTimeWillExpire() {
        AltcraftNSE.shared.serviceExtensionTimeWillExpire()
    }
}

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

Таргет приложения и таргет Notification Service Extension работают в отдельных процессах и не разделяют общие объекты. Поэтому для корректной обработки уведомлений SDK необходимо зарегистрировать JWTProvider и идентификатор App Group также в расширении NSE — например, в методе didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void). Это обеспечивает доступ SDK к токену авторизации при отправке push-события доставки ("delivery_event").

Инициализация SDK

Параметры инициализации

Для передачи параметров конфигурации испоользуется класс AltcraftConfiguration:

public final class AltcraftConfiguration {
    private let apiUrl: String
    private let rToken: String?
    private var appInfo: AppInfo?
    private var providerPriorityList: [String]?
}

Сборка файла конфигурации происходит после вызова функции build() класса AltcraftConfiguration.Builder(): AltcraftConfiguration.Builder().build().

Описание параметров:

apiUrl String

Обязательный: Да
Описание: URL конечной точки Altcraft API

---

rToken String?

По умолчанию: nil
Обязательный: Нет
Описание: Ролевой токен Altcraft (идентифицирует ресурс, БД или аккаунт). Используется, если единственный тип матчинга — push-токен устройства, выданный провайдером.

---

appInfo AppInfo?

По умолчанию: nil
Обязательный: Нет
Описание: Базовые метаданные приложения для Firebase Analytics. Для установки значения этого параметра используйте публичную структуру SDK AppInfo:

public struct AppInfo: Codable {
    /// Firebase app_id
    public var appID: String
    /// Firebase app_instance_id
    public var appIID: String
    /// Firebase app_version
    public var appVer: String
}

---

providerPriorityList [String]?

По умолчанию: nil
Обязательный: Нет
Описание: Список приоритетов провайдеров. Используется для автоматического обновления push-токена подписки, если токен более приоритетного провайдера недоступен. Приоритет определяется индексом в списке: элемент с индексом 0 — самый приоритетный.

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

providerPriorityList = [
    Constants.ProviderName.apns,
    Constants.ProviderName.firebase,
    Constants.ProviderName.huawei
]

При такой настройке:

• SDK сначала запросит токен APNs; если APNs недоступен — FCM; если FCM недоступен — HMS;
• Работает при условии, если в приложении реализованы протоколы соответствующих провайдеров.

Для удобства установки значения параметра SDK содержит публичные константы. Все константы находятся в enum Constants:

public enum Constants {
    public enum ProviderName {
        /// Provider name for Firebase
        public static let firebase = "ios-firebase"
        /// Provider name for APNs
        public static let apns = "ios-apns"
        /// Provider name for HMS
        public static let huawei = "ios-huawei"
    }
}

Если значение не задано, приоритет провайдеров следующий:

apns —> firebase —> huawei

Значение параметра может содержать один элемент — в этом случае будет использоваться только один провайдер, независимо от доступности push-токена.

Параметр можно не указывать, если:

• в проекте используется только один провайдер;
• приоритет по умолчанию соответствует требованиям.

Выполнение инициализации

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

Вызывайте AltcraftSDK.shared.initialization() тогда, когда это необходимо, но только после установки идентификатора AppGroup и провайдеров, реализующих протоколы SDK. Запросы следует выполнять после установки конфигурации.

Для инициализации SDK используется функция public func initialization(configuration: AltcraftConfiguration?, completion: ((Bool) -> Void)? = nil):

AltcraftSDK.shared.initialization(configuration: AltcraftConfiguration?, completion: ((Bool) -> Void)? = nil)

Функция initialization(configuration: AltcraftConfiguration?, completion: ((Bool) -> Void)? = nil) ожидает файл конфигурации AltcraftConfiguration, для которого установлены необходимые значения и выполнена сборка:

 let config = AltcraftConfiguration.Builder()
        .setApiUrl("your apiUrl")
        .setRToken("your rToken")
        .setAppInfo(AppInfo(appID: "your appID", appIID: "your appIID", appVer: "your appVer"))
        .setProviderPriorityList([Constants.ProviderName.firebase])
        .build()

Пример правильного порядка инициализации SDK в AppDelegate.application(_:didFinishLaunchingWithOptions:) (после установки идентификатора AppGroup и регистрации провайдеров)

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Firebase configuration initialization (if used)

        let appGroup = "group.your.id"
        
        AltcraftSDK.shared.setAppGroup(groupName: appGroup)
        AltcraftSDK.shared.backgroundTasks.registerBackgroundTask()
        AltcraftSDK.shared.setJWTProvider(provider: JWTProvider())
        AltcraftSDK.shared.pushTokenFunction.setAPNSTokenProvider(APNSProvider())
        AltcraftSDK.shared.pushTokenFunction.setFCMTokenProvider(FCMProvider())
        AltcraftSDK.shared.pushTokenFunction.setHMSTokenProvider(HMSProvider())
        AltcraftSDK.shared.notificationManager.registerForPushNotifications(for: application)
        
        let config = AltcraftConfiguration.Builder()
            .setApiUrl("your apiUrl")
            .setRToken("your rToken")
            .setAppInfo(AppInfo(appID: "your appID", appIID: "your appIID", appVer: "your appVer"))
            .setProviderPriorityList([Constants.ProviderName.firebase])
            .build()
        
        AltcraftSDK.shared.initialization(configuration: config) { success in
            if success {
               // Actions after successful initialization
            }
        }
        
        // Other functions
        
        return true
    }
    // Other functions AppDelegate
}