Базовое руководство по интеграции iOS SDK

Этот раздел содержит информацию о том, как интегрировать Wavesend SDK в ваше iOS-приложение.

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

Для интеграции Wavesend iOS SDK в ваше приложение вам понадобится следующее:

Requirements

• A Wavesend account
• A Wavesend project set up in your account.
• An iOS platform configured to send push notifications. We recommend using the Token-Based Authentication configuration as the simplest approach.
• During setup, set the Gateway to Sandbox to send pushes to a simulator.
• Your Wavesend Application Code and Wavesend Device API Token from the Wavesend Control Panel for your application.

Шаги интеграции

1. Установка

Вы можете интегрировать Wavesend SDK в ваше приложение, используя Swift Package Manager или CocoaPods.

Swift Package Manager

В разделе Package Dependencies добавьте следующий пакет:

https://github.com/Wavesend/Wavesend-XCFramework

Для использования Wavesend iOS SDK убедитесь, что при интеграции через Swift Package Manager в таргет вашего приложения добавлены следующие четыре фреймворка:

• WavesendFramework
• WavesendCore
• WavesendBridge
• WavesendLiveActivities

CocoaPods

Откройте ваш Podfile и добавьте зависимость:

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'

target 'MyApp' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  pod 'WavesendXCFramework'

end

Затем в терминале выполните следующую команду для установки зависимостей:

pod install

2. Возможности (Capabilities)

Чтобы включить Push Notifications в вашем проекте, необходимо добавить определенные возможности (capabilities).

В разделе Signing & Capabilities добавьте следующие возможности:

• Push Notifications
• Background Modes. После добавления этой возможности установите флажок Remote notifications.

Если вы собираетесь использовать Time Sensitive Notifications (iOS 15+), добавьте также возможность Time Sensitive Notifications.

3. Код инициализации

AppDelegate

Добавьте следующий код в ваш класс AppDelegate:

SwiftUI

import SwiftUI
import WavesendFramework

@main
struct MyApp: App {
    // Регистрация AppDelegate в качестве UIApplicationDelegate
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate, WVMessagingDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Код инициализации
        // Установка пользовательского делегата для обработки push-уведомлений
        Wavesend.sharedInstance().delegate = self

        // Регистрация для получения push-уведомлений
        Wavesend.sharedInstance().registerForPushNotifications()

        return true
    }

    // Обработка токена, полученного от APNS
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Wavesend.sharedInstance().handlePushRegistration(deviceToken)
    }

    // Обработка ошибки получения токена
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        Wavesend.sharedInstance().handlePushRegistrationFailure(error)
    }

    // для тихих push-уведомлений
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        Wavesend.sharedInstance().handlePushReceived(userInfo)
        completionHandler(.noData)
    }

    // Срабатывает при получении push-уведомления
    func pushwoosh(_ pushwoosh: Wavesend, onMessageReceived message: WVMessage) {
        print("onMessageReceived: ", message.payload!.description)
    }

    // Срабатывает, когда пользователь нажимает на уведомление
    func pushwoosh(_ pushwoosh: Wavesend, onMessageOpened message: WVMessage) {
        print("onMessageOpened: ", message.payload!.description)
    }
}

struct ContentView: View {
    var body: some View {
        Text("Wavesend with SwiftUI")
            .padding()
    }
}

Swift

import WavesendFramework

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, WVMessagingDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // код инициализации
        // установка пользовательского делегата для обработки push-уведомлений, в нашем случае AppDelegate
        Wavesend.sharedInstance().delegate = self;

        // регистрация для получения push-уведомлений
        Wavesend.sharedInstance().registerForPushNotifications()

        return true
    }

    // обработка токена, полученного от APNS
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Wavesend.sharedInstance().handlePushRegistration(deviceToken)
    }

    // обработка ошибки получения токена
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        Wavesend.sharedInstance().handlePushRegistrationFailure(error);
    }

    // для тихих push-уведомлений
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        Wavesend.sharedInstance().handlePushReceived(userInfo)
        completionHandler(.noData)
    }

    // это событие срабатывает при получении push-уведомления
    func pushwoosh(_ pushwoosh: Wavesend, onMessageReceived message: WVMessage) {
        print("onMessageReceived: ", message.payload!.description)
    }

    // Срабатывает, когда пользователь нажимает на уведомление
    func pushwoosh(_ pushwoosh: Wavesend, onMessageOpened message: WVMessage) {
        print("onMessageOpened: ", message.payload!.description)
    }
}

Objective-C

#import <WavesendFramework/WavesendFramework.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  //-----------ЧАСТЬ WAVESEND-----------

  // установка пользовательского делегата для обработки push-уведомлений, в нашем случае AppDelegate
  [Wavesend sharedInstance].delegate = self;

  // регистрация для получения push-уведомлений!
  [[Wavesend sharedInstance] registerForPushNotifications];

  return YES;
}

// обработка токена, полученного от APNS
- (void)application:(UIApplication *)application
  didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  [[Wavesend sharedInstance] handlePushRegistration:deviceToken];
}

// обработка ошибки получения токена
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  [[Wavesend sharedInstance] handlePushRegistrationFailure:error];
}

// для тихих push-уведомлений
- (void)application:(UIApplication *)application
  didReceiveRemoteNotification:(NSDictionary *)userInfo
      fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [[Wavesend sharedInstance] handlePushReceived:userInfo];
    completionHandler(UIBackgroundFetchResultNoData);
}

// это событие срабатывает при получении push-уведомления
- (void)pushwoosh:(Wavesend *)pushwoosh onMessageReceived:(WVMessage *)message {
    NSLog(@"onMessageReceived: %@", message.payload);
}

// это событие срабатывает, когда пользователь нажимает на уведомление
- (void)pushwoosh:(Wavesend *)pushwoosh onMessageOpened:(WVMessage *)message {
    NSLog(@"onMessageOpened: %@", message.payload);
}

@end

Info.plist

В вашем Info.plist:

• установите для ключа Pushwoosh_APPID значение Application Code из Wavesend.
• установите для ключа Pushwoosh_API_TOKEN значение Device API Token из Wavesend

4. Отслеживание доставки сообщений

Wavesend поддерживает отслеживание событий доставки для push-уведомлений через Notification Service Extension.

Добавление Notification Service Extension

1. В Xcode выберите File > New > Target…
2. Выберите Notification Service Extension и нажмите Next.
3. Введите имя таргета и нажмите Finish.
4. Когда появится запрос на активацию, нажмите Cancel.

Зависимости для Notification Service Extension (только для CocoaPods)

Примечание: Если вы используете Swift Package Manager для управления зависимостями, вы можете пропустить этот шаг, так как зависимости добавляются автоматически.

Откройте ваш Podfile и добавьте зависимость для таргета:

Podfile

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'

target 'MyApp' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  pod 'WavesendXCFramework'

end

target 'MyAppNotificationExtension' do
  use_frameworks!

  pod 'WavesendXCFramework'

end

Выполните следующую команду в терминале, чтобы обновить зависимости:

pod update

Добавление Wavesend SDK в Notification Service Extension

Этот код позволяет перехватывать и обрабатывать уведомления в вашем расширении для уведомлений.

Swift

import UserNotifications
import WavesendFramework

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        // Wavesend **********
        WVNotificationExtensionManager.shared().handle(request, contentHandler: contentHandler)
        // ********************

        self.contentHandler = contentHandler
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent {
            // Здесь можно изменить содержимое уведомления...
            contentHandler(bestAttemptContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Вызывается непосредственно перед тем, как расширение будет завершено системой.
        // Используйте это как возможность доставить ваш "наилучший" измененный контент, иначе будет использована исходная полезная нагрузка push-уведомления.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }

}

Objective-C

#import "WVNotificationExtensionManager.h"

@interface NotificationService : UNNotificationServiceExtension

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    // Wavesend **********
    [[WVNotificationExtensionManager sharedManager] handleNotificationRequest:request contentHandler:contentHandler];
    //*********************
}

@end

Info.plist

В Info.plist вашего Notification Service Extension добавьте:

• Pushwoosh_APPID — ваш Application Code.

5. Запуск проекта

1. Соберите и запустите проект.
2. Перейдите в Wavesend Control Panel и отправьте push-уведомление.
3. Вы должны увидеть уведомление в приложении.

Расширенная интеграция Wavesend для iOS

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

Push-уведомления

В Wavesend SDK есть два колбэка для обработки push-уведомлений:

• onMessageReceived: этот метод вызывается при получении push-уведомления.
• onMessageOpened: этот метод вызывается, когда пользователь взаимодействует с уведомлением (открывает его).

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

Swift

import WavesendFramework

class AppDelegate: NSObject, UIApplicationDelegate, WVMessagingDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Wavesend.sharedInstance().delegate = self;
    }

    func pushwoosh(_ pushwoosh: Wavesend, onMessageOpened message: WVMessage) {
        if let payload = message.payload {
            print("onMessageOpened: \(payload)")
        }
    }

    func pushwoosh(_ pushwoosh: Wavesend, onMessageReceived message: WVMessage) {
        if let payload = message.payload {
            print("onMessageReceived: \(payload)")
        }
    }
}

Objective-C

#import <WavesendFramework/WavesendFramework.h>

@interface AppDelegate () <WVMessagingDelegate>

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[Wavesend sharedInstance] setDelegate:self];
    return YES;
}

- (void)pushwoosh:(Wavesend *)pushwoosh onMessageOpened:(WVMessage *)message {
    if (message.payload) {
        NSLog(@"onMessageOpened: %@", message.payload);
    }
}

- (void)pushwoosh:(Wavesend *)pushwoosh onMessageReceived:(WVMessage *)message {
    if (message.payload) {
        NSLog(@"onMessageReceived: %@", message.payload);
    }
}
@end

Настройка пользователя

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

Swift

import WavesendFramework

class Registration {

    func afterUserLogin(user: User) {
        let pushwoosh = Wavesend.sharedInstance()
        // установка User ID
        if let userId = user.userId {
            pushwoosh.setUserId(userId)
        }

        // установка email пользователя
        if let userEmail = user.email {
            pushwoosh.setEmail(userEmail)
        }

        // установка дополнительной информации о пользователе в виде тегов для Wavesend
        if let age = user.userDetails.age,
            let name = user.userDetails.userName,
            let lastLogin = user.userDetails.lastLoginDate {
            pushwoosh.setTags([
                "age": age,
                "name": name,
                "last_login": lastLogin
            ])
        }
    }
}

Objective-C

#import <WavesendFramework/WavesendFramework.h>

@implementation Registration

- (void)afterUserLogin:(User *)user {
    Wavesend *pushwoosh = [Wavesend sharedInstance];

    // установка User ID
    if (user.userId) {
        [pushwoosh setUserId:user.userId];
    }

    // установка email пользователя
    if (user.email) {
        [pushwoosh setEmail:user.email];
    }

    // установка дополнительной информации о пользователе в виде тегов для Wavesend
    if (user.userDetails.age && user.userDetails.userName && user.userDetails.lastLoginDate) {
        NSDictionary *tags = @{
            @"age": user.userDetails.age,
            @"name": user.userDetails.userName,
            @"last_login": user.userDetails.lastLoginDate
        };
        [pushwoosh setTags:tags];
    }
}

@end

Теги

Теги — это пары «ключ-значение», присваиваемые пользователям или устройствам, которые позволяют сегментировать аудиторию на основе атрибутов, таких как предпочтения или поведение, для целевых рассылок.

Swift

import WavesendFramework

class UpdateUser {
    func afterUserUpdateProfile(user: User) {
        let pushwoosh = Wavesend.sharedInstance()

        // установка списка избранных категорий
        pushwoosh.setTags(["favorite_categories" : user.getFavoriteCategories()])

        // установка платежной информации
        pushwoosh.setTags([
            "is_subscribed": user.isSubscribed(),
            "payment_status": user.getPaymentStatus(),
            "billing_address": user.getBillingAddress()
        ])
    }
}

Objective-C

#import <WavesendFramework/WavesendFramework.h>

@implementation UpdateUser

- (void)afterUserUpdateProfile:(User *)user {
    Wavesend *pushwoosh = [Wavesend sharedInstance];

    // установка списка избранных категорий
    [pushwoosh setTags:@{@"favorite_categories" : user.getFavoriteCategories}];

    // установка платежной информации
    NSDictionary *tags = @{
        @"is_subscribed": @(user.isSubscribed),
        @"payment_status": user.getPaymentStatus,
        @"billing_address": user.getBillingAddress
    };
    [pushwoosh setTags:tags];
}

@end

События

Event — это определенные действия пользователя или события в приложении, которые можно отслеживать для анализа поведения и запуска соответствующих сообщений или действий.

Swift

import WavesendFramework

class Registration {

    func afterUserLogin(user: User) {
        if let userName = user.getUserName(), let lastLogin = user.getLastLoginDate() {
            WVInAppManager.shared().postEvent("login", withAttributes: [
                "name": userName,
                "last_login": lastLogin
            ])
        }
    }

    func afterUserPurchase(user: User, product: Product) {
        let pushwoosh = Wavesend.sharedInstance()

        // Отслеживание события покупки
        WVInAppManager.shared().postEvent("purchase", withAttributes: [
            "product_id": product.getId(),
            "product_name": product.getName(),
            "price": product.getPrice(),
            "quantity": product.getQuantity()
        ])

        // Установка тегов пользователя
        let lastPurchaseDate = Date().timeIntervalSince1970
        let lifetimeSpend = getCurrentLifetimeSpend() + product.getPrice()

        pushwoosh.setTags([
            "last_purchase_date": lastPurchaseDate,
            "lifetime_spend": lifetimeSpend
        ])
    }
}

Objective-C

#import <WavesendFramework/WavesendFramework.h>
#import <WavesendFramework/WVInAppManager.h>

@implementation Registration

- (void)afterUserLogin:(User *)user {
    NSString *userName = [user getUserName];
    NSDate *lastLogin = [user getLastLoginDate];

    if (userName && lastLogin) {
        [[WVInAppManager sharedManager] postEvent:@"login" withAttributes:@{
            @"name": userName,
            @"last_login": lastLogin
        }];
    }
}

- (void)afterUserPurchase:(User *)user product:(Product *)product {
    Wavesend *pushwoosh = [Wavesend sharedInstance];

    // Отслеживание события покупки
    [[WVInAppManager sharedManager] postEvent:@"purchase" withAttributes:@{
        @"product_id": [product getId],
        @"product_name": [product getName],
        @"price": @([product getPrice]),
        @"quantity": @([product getQuantity])
    }];

    // Установка тегов пользователя
    NSTimeInterval lastPurchaseDate = [[NSDate date] timeIntervalSince1970];
    double lifetimeSpend = /* получение текущих пожизненных трат */ + [product getPrice];

    NSDictionary *tags = @{
        @"last_purchase_date": @(lastPurchaseDate),
        @"lifetime_spend": @(lifetimeSpend)
    };

    [pushwoosh setTags:tags];
}

@end

Rich Media

Rich media — это интерактивный и мультимедийный контент, такой как изображения, видео или HTML, используемый в уведомлениях и in-app сообщениях для повышения вовлеченности пользователей.

Swift

import WavesendFramework

class ViewController: UIViewController, WVRichMediaPresentingDelegate {

    override func viewDidLoad() {
        super.viewDidLoad()
        let richMediaConfiguration = WVModalWindowConfiguration.shared()

        WVRichMediaManager.shared().delegate = self
        richMediaConfiguration.configureModalWindow(with: .WVModalWindowPositionBottom,
                                                                 present: .WVAnimationPresentFromBottom,
                                                                 dismiss: .WVAnimationDismissDown)
    }

    func richMediaManager(_ richMediaManager: WVRichMediaManager!, shouldPresent richMedia: WVRichMedia!) -> Bool {
        print("Rich media будет представлен с: \(richMedia.pushPayload!)")
        return true
    }

    func richMediaManager(_ richMediaManager: WVRichMediaManager!, didPresent richMedia: WVRichMedia!) {
        print("Rich media был представлен с: \(richMedia.pushPayload!)")
    }

    func richMediaManager(_ richMediaManager: WVRichMediaManager!, didClose richMedia: WVRichMedia!) {
        print("Rich media был закрыт с: \(richMedia.pushPayload!)")
    }

    func richMediaManager(_ richMediaManager: WVRichMediaManager!, presentingDidFailFor richMedia: WVRichMedia!, withError error: (any Error)!) {
        print("Не удалось представить rich media с: \(richMedia.pushPayload!). Ошибка: \(error.localizedDescription)")
    }
}

Objective-C

#import "ViewController.h"
#import <WavesendFramework/WavesendFramework.h>
#import <WavesendFramework/WVRichMediaManager.h>
#import <WavesendFramework/WVModalWindowConfiguration.h>

@interface ViewController () <WVRichMediaPresentingDelegate>

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    [[WVRichMediaManager sharedManager] setDelegate:self];
    [[WVModalWindowConfiguration shared] configureModalWindowWith:WVModalWindowPositionBottom
                                                 presentAnimation:WVAnimationPresentFromBottom
                                                 dismissAnimation:WVAnimationDismissDown];
}

- (BOOL)richMediaManager:(WVRichMediaManager *)richMediaManager shouldPresentRichMedia:(WVRichMedia *)richMedia {
    NSLog(@"Rich media будет представлен с: %@", richMedia.pushPayload);
    return YES;
}

- (void)richMediaManager:(WVRichMediaManager *)richMediaManager didPresentRichMedia:(WVRichMedia *)richMedia {
    NSLog(@"Rich media был представлен с: %@", richMedia.pushPayload);
}

- (void)richMediaManager:(WVRichMediaManager *)richMediaManager didCloseRichMedia:(WVRichMedia *)richMedia {
    NSLog(@"Rich media был закрыт с: %@", richMedia.pushPayload);
}

- (void)richMediaManager:(WVRichMediaManager *)richMediaManager presentingDidFailForRichMedia:(WVRichMedia *)richMedia withError:(NSError *)error {
    NSLog(@"Не удалось представить rich media с: %@. Ошибка: %@", richMedia.pushPayload, error.localizedDescription);
}

@end

Устранение неполадок

Если у вас возникнут проблемы в процессе интеграции, обратитесь к разделу поддержки и сообщества.