Быстрый старт

В статье приведен пример быстрой интеграции Altcraft mSDK с Apple Push Notification System (APNS) и Firebase Cloud Messaging (FCM). После выполнения указанных шагов ваше приложение сможет получать push-уведомления Altcraft.

Для использования Huawei Mobile Services необходимо добавить соответствующие SDK в проект и реализовать их интерфейс, используя тот же подход, что показан для APNS и FCM.

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

• Получен доступ к APNS на сайте;
• Приложение настроено в проекте Firebase, GoogleServiceInfo.plist загружен;
• Все необходимые сущности (ресурс, рассылка, шаблон, база профилей) заранее созданы в платформе Altcraft.

Шаг 1. Подключение Altcraft mSDK к приложению

mSDK разбит на модули. Модуль активизируется добавлением его зависимости в проект — отдельная регистрация не требуется: каждый модуль регистрируется автоматически при инициализации SDK.

Для push-сценария необходимы два модуля:

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

Добавьте пакеты из репозиториев с помощью Swift Package Manager:

• Репозиторий Altcraft SDK — выберите продуктовые модули AltcraftCore и AltcraftPush (при использовании Notification Service Extension добавьте AltcraftNSE);
• Репозиторий Firebase.

Шаг 2. Добавление GoogleServiceInfo в приложение

Добавьте GoogleServiceInfo.plist в папку вашего приложения:

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

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

• General:
  • Проверьте, что библиотека Altcraft добавлена в Frameworks, Libraries, and Embedded Content таргета приложения:

• Проверьте, что библиотека FirebaseMessaging добавлена в Frameworks, Libraries, and Embedded Content таргета приложения:

• Signing & Capabilities:

  • PushNotifications;
  • AppGroups — укажите идентификатор для группы (добавление идентификатора App Group необходимо для обмена информацией с Notification Service Extension);
  • Background Modes — выберите Background fetch, Remote notification, Background processing.

• Info:

  • Добавьте ключи и значения:

Ключ	Тип	Значение
Permitted background task scheduler identifiers	Array	"lib.Altcraft.bgTask.systemControl"
FirebaseAppDelegateProxyEnabled	Boolean	NO

Первый ключ необходим для регистрации bgTask-задачи, которая будет выполнять повтор неудачных запросов к серверу в background-режиме. Второй ключ — для отключения автоматической подмены (method swizzling) методов AppDelegate, которую Firebase Messaging выполняет по умолчанию.

Шаг 4. Реализация JWTInterface

Выполните реализацию протокола SDK, предназначенного для предоставления JWT-токена. Для этого создайте класс, реализующий JWTInterface, и переопределите getToken():

import Altcraft

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

К сведению

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

Шаг 5. Реализация FCMInterface

Выполните реализацию протокола SDK, предназначенного для предоставления и удаления FCM-токена. Для этого создайте класс, реализующий FCMInterface, и переопределите getToken(), deleteToken().

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

Шаг 6. Реализация APNSInterface

Выполните реализацию протокола SDK, предназначенного для предоставления APNS-токена. Для этого создайте класс, реализующий APNSInterface, и переопределите getToken():

import Altcraft

class APNSProvider: APNSInterface {
    /// Извлекает текущий токен APNs из локального хранилища
    func getToken(completion: @escaping (String?) -> Void) {
        let token = getAPNsTokenFromUserDefault()  // передайте токен apns
        completion(token)
    }
}

Шаг 7. Настройка Altcraft SDK и Firebase SDK в AppDelegate

Altcraft SDK:

• выполните передачу идентификатора AppGroups в Altcraft SDK;
• выполните регистрацию backgroundTasks Altcraft SDK;
• установите JWT-, APNS-, FCM-провайдеров;
• выполните регистрацию в центре уведомлений.

FirebaseSDK:

• выполните установку конфигурации;

Пример правильной настройки Altcraft SDK и Firebase SDK в AppDelegate

class AppDelegate: UIResponder, UIApplicationDelegate,  UNUserNotificationCenterDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        //установка конфигурации FirebaseSDK
        FirebaseApp.configure()

        //AltcraftSDK
        ///установка идентификатора AppGroup
        AltcraftSDK.shared.setAppGroup(groupName: "group.your_company.name")
        ///регистрация BGTask
        AltcraftSDK.shared.backgroundTasks.registerBackgroundTask()
        ///установка JWTProvider
        AltcraftSDK.shared.setJWTProvider(provider: JWTProvider())
        ///установка APNSProvider
        AltcraftSDK.shared.push.token.setAPNSTokenProvider(APNSProvider())
        ///установка FCMProvider
        AltcraftSDK.shared.push.token.setFCMTokenProvider(FCMProvider())
        ///регистрация в центре уведомлений
        AltcraftSDK.shared.push.notificationManager.registerForPushNotifications(for: application)

        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken apnsToken: Data
    ) {
        //сохраните apns токен в userDefault
        setAPNsTokenInUserDefault(apnsToken)
    }
}

• выполните установку delegate;
• передайте APNS-токен в Firebase в функции AppDelegate.application(_:didFinishLaunchingWithOptions:). Это гарантирует правильную инициализацию Firebase и доступность FCM-токена в background-режиме, например, во время выполнения BGTask. Так как APNS-токен не доступен в AppDelegate.application(_:didFinishLaunchingWithOptions:), используете сохраненное значение, например, в UserDefaults.

Шаг 8. Создание Notification Service Extension

Создайте расширение приложения 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:
  • AppGroups — укажите идентификатор AppGroup.

Затем настройте SDK в UNNotificationServiceExtension. Для этого замените весь автоматически сгенерированный код NSE на код из примера ниже:

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

import Altcraft
import UserNotifications

class NotificationService: UNNotificationServiceExtension {

    /// - important! Set app groups identifier.
    let appGroupID =  "group.your.id"

    /// - important! Set the provider to JWT if you are using JWT authentication.
    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()
    }
}

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

Если вы не используете JWT-аутентификацию, исключите вызов установки JWT-провайдера AltcraftNSE.shared.setJWTProvider(provider: jwtProvider).

Шаг 9. Инициализация SDK

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

Создайте переменную конфигурации и выполните инициализацию с помощью функции initialization(). Конфигурация push-модуля добавляется вызовом pushConfig() — в данном примере ios-firebase выбран приоритетным провайдером:

let config = AltcraftConfiguration.Builder()
.setApiUrl("your_api_url")
.pushConfig(
    PushConfiguration(
        providerPriority: [Constants.ProviderName.firebase]
    )
)
.build()

AltcraftSDK.shared.initialization(configuration: config)

Вы также можете установить APNS в качестве приоритетного провайдера:

let config = AltcraftConfiguration.Builder()
.setApiUrl("your_api_url")
.pushConfig(
    PushConfiguration(
        providerPriority: [Constants.ProviderName.apns]
    )
)
.build()

AltcraftSDK.shared.initialization(configuration: config)

Если не задавать providerPriority, будет использоваться приоритет по умолчанию — ios-apns -> ios-firebase -> ios-huawei:

let config = AltcraftConfiguration.Builder()
.setApiUrl("your_api_url")
.build()

AltcraftSDK.shared.initialization(configuration: config)

Шаг 10. Выполнение подписки на push-уведомления

Выполните подписку на push-уведомления с помощью функции pushSubscribe(), передав необходимые параметры:

AltcraftSDK.shared.push.subscription.pushSubscribe(
 profileFields: ["_fname": "user_first_name", "_lname": "user_last_name"]
)