Guide d'intégration de base du SDK iOS

Cette section contient des informations sur la manière d’intégrer le SDK Pushwoosh dans votre application iOS.

Prérequis

Pour intégrer le SDK Pushwoosh pour iOS dans votre application, vous aurez besoin des éléments suivants :

Prérequis

• Un compte Pushwoosh
• Un projet Pushwoosh configuré dans votre compte.
• Une plateforme iOS configurée pour envoyer des notifications push. Nous vous recommandons d’utiliser la configuration d’authentification basée sur un token comme approche la plus simple.
• Lors de la configuration, réglez la passerelle (Gateway) sur Sandbox pour envoyer des pushes à un simulateur.
• Votre Pushwoosh Application Code et votre jeton d’API de l’appareil Pushwoosh (Pushwoosh Device API Token) depuis le panneau de contrôle Pushwoosh pour votre application.

Étapes d’intégration

1. Installation

Vous pouvez intégrer le SDK Pushwoosh dans votre application en utilisant soit le Swift Package Manager, soit CocoaPods.

Swift Package Manager

Dans la section Package Dependencies, ajoutez le paquet suivant :

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

Pour utiliser le SDK Pushwoosh pour iOS, assurez-vous d’ajouter les quatre frameworks suivants à la cible de votre application lors de l’intégration via Swift Package Manager :

• PushwooshFramework
• PushwooshCore
• PushwooshBridge
• PushwooshLiveActivities

CocoaPods

Ouvrez votre Podfile et ajoutez la dépendance :

# 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 'PushwooshXCFramework'

end

Ensuite, dans le terminal, exécutez la commande suivante pour installer les dépendances :

pod install

2. Capacités

Pour activer les notifications Push dans votre projet, vous devez ajouter certaines capacités.

Dans la section Signing & Capabilities, ajoutez les capacités suivantes :

• Push Notifications
• Background Modes. Après avoir ajouté cette capacité, cochez la case Remote notifications.

Si vous prévoyez d’utiliser les notifications urgentes (Time Sensitive Notifications) (iOS 15+), ajoutez également la capacité Time Sensitive Notifications.

3. Code d’initialisation

AppDelegate

Ajoutez le code suivant à votre classe AppDelegate :

SwiftUI

import SwiftUI
import PushwooshFramework

@main
struct MyApp: App {
    // Register AppDelegate as UIApplicationDelegate
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

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

class AppDelegate: NSObject, UIApplicationDelegate, PWMessagingDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialization code
        // Set custom delegate for push handling
        Pushwoosh.sharedInstance().delegate = self

        // Register for push notifications
        Pushwoosh.sharedInstance().registerForPushNotifications()

        return true
    }

    // Handle token received from APNS
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Pushwoosh.sharedInstance().handlePushRegistration(deviceToken)
    }

    // Handle token receiving error
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        Pushwoosh.sharedInstance().handlePushRegistrationFailure(error)
    }

    //for silent push notifications
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        Pushwoosh.sharedInstance().handlePushReceived(userInfo)
        completionHandler(.noData)
    }

    // Fired when a push is received
    func pushwoosh(_ pushwoosh: Pushwoosh, onMessageReceived message: PWMessage) {
        print("onMessageReceived: ", message.payload!.description)
    }

    // Fired when a user taps the notification
    func pushwoosh(_ pushwoosh: Pushwoosh, onMessageOpened message: PWMessage) {
        print("onMessageOpened: ", message.payload!.description)
    }
}

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

Swift

import PushwooshFramework

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, PWMessagingDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        //initialization code
        //set custom delegate for push handling, in our case AppDelegate
        Pushwoosh.sharedInstance().delegate = self;

        //register for push notifications
        Pushwoosh.sharedInstance().registerForPushNotifications()

        return true
    }

    //handle token received from APNS
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Pushwoosh.sharedInstance().handlePushRegistration(deviceToken)
    }

    //handle token receiving error
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        Pushwoosh.sharedInstance().handlePushRegistrationFailure(error);
    }

    //for silent push notifications
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        Pushwoosh.sharedInstance().handlePushReceived(userInfo)
        completionHandler(.noData)
    }

    //this event is fired when the push gets received
    func pushwoosh(_ pushwoosh: Pushwoosh, onMessageReceived message: PWMessage) {
        print("onMessageReceived: ", message.payload!.description)
    }

    // Fired when a user taps the notification
    func pushwoosh(_ pushwoosh: Pushwoosh, onMessageOpened message: PWMessage) {
        print("onMessageOpened: ", message.payload!.description)
    }
}

Objective-C

#import <PushwooshFramework/PushwooshFramework.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  //-----------PUSHWOOSH PART-----------

  // set custom delegate for push handling, in our case AppDelegate
  [Pushwoosh sharedInstance].delegate = self;

  //register for push notifications!
  [[Pushwoosh sharedInstance] registerForPushNotifications];

  return YES;
}

//handle token received from APNS
- (void)application:(UIApplication *)application
  didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  [[Pushwoosh sharedInstance] handlePushRegistration:deviceToken];
}

//handle token receiving error
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  [[Pushwoosh sharedInstance] handlePushRegistrationFailure:error];
}

//for silent push notifications
- (void)application:(UIApplication *)application
  didReceiveRemoteNotification:(NSDictionary *)userInfo
      fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [[Pushwoosh sharedInstance] handlePushReceived:userInfo];
    completionHandler(UIBackgroundFetchResultNoData);
}

//this event is fired when the push gets received
- (void)pushwoosh:(Pushwoosh *)pushwoosh onMessageReceived:(PWMessage *)message {
    NSLog(@"onMessageReceived: %@", message.payload);
}

//this event is fired when user taps the notification
- (void)pushwoosh:(Pushwoosh *)pushwoosh onMessageOpened:(PWMessage *)message {
    NSLog(@"onMessageOpened: %@", message.payload);
}

@end

Info.plist

Dans votre Info.plist :

• définissez la clé Pushwoosh_APPID sur le code d’application Pushwoosh.
• définissez la clé Pushwoosh_API_TOKEN sur le jeton d’API de l’appareil Pushwoosh

4. Suivi de la livraison des messages

Pushwoosh prend en charge le suivi des événements de livraison pour les notifications push via l’extension de service de notification (Notification Service Extension)

Ajouter une extension de service de notification

1. Dans Xcode, sélectionnez File > New > Target…
2. Choisissez Notification Service Extension et appuyez sur Next.
3. Entrez le nom de la cible et appuyez sur Finish.
4. Lorsque l’activation vous est demandée, appuyez sur Cancel.

Dépendances pour l’extension de service de notification (CocoaPods uniquement)

Remarque : Si vous utilisez Swift Package Manager pour gérer les dépendances, vous pouvez sauter cette étape, car les dépendances sont ajoutées automatiquement.

Ouvrez votre Podfile et ajoutez la dépendance pour la cible :

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 'PushwooshXCFramework'

end

target 'MyAppNotificationExtension' do
  use_frameworks!

  pod 'PushwooshXCFramework'

end

Exécutez la commande suivante dans le terminal pour mettre à jour les dépendances :

pod update

Ajouter le SDK Pushwoosh à l’extension de service de notification

Ce code vous permet d’intercepter et de traiter les notifications au sein de votre extension de notification.

Swift

import UserNotifications
import PushwooshFramework

class NotificationService: UNNotificationServiceExtension {

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

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

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

        if let bestAttemptContent = bestAttemptContent {
            // Modify the notification content here...
            contentHandler(bestAttemptContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }

}

Objective-C

#import "PWNotificationExtensionManager.h"

@interface NotificationService : UNNotificationServiceExtension

@end

@implementation NotificationService

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

@end

Info.plist

Dans le fichier Info.plist de votre extension de service de notification, ajoutez :

• Pushwoosh_APPID - Votre code d’application.

5. Exécuter le projet

1. Compilez et exécutez le projet.
2. Allez dans le panneau de contrôle Pushwoosh et envoyez une notification push.
3. Vous devriez voir la notification dans l’application.

Intégration iOS étendue de Pushwoosh

À ce stade, vous avez déjà intégré le SDK et pouvez envoyer et recevoir des notifications push. Explorons maintenant les fonctionnalités de base

Notifications push

Dans le SDK Pushwoosh, il existe deux rappels (callbacks) conçus pour gérer les notifications push :

• onMessageReceived : Cette méthode est invoquée lorsqu’une notification push est reçue.
• onMessageOpened : Cette méthode est appelée lorsque l’utilisateur interagit avec (ouvre) la notification

Ces rappels permettent aux développeurs de gérer la réception et l’interaction de l’utilisateur avec les notifications push au sein de leurs applications

Swift

import PushwooshFramework

class AppDelegate: NSObject, UIApplicationDelegate, PWMessagingDelegate {

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

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

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

Objective-C

#import <PushwooshFramework/PushwooshFramework.h>

@interface AppDelegate () <PWMessagingDelegate>

@end

@implementation AppDelegate

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

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

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

Configuration de l’utilisateur

En vous concentrant sur le comportement et les préférences de chaque utilisateur, vous pouvez fournir un contenu personnalisé, ce qui augmente la satisfaction et la fidélité des utilisateurs

Swift

import PushwooshFramework

class Registration {

    func afterUserLogin(user: User) {
        let pushwoosh = Pushwoosh.sharedInstance()
        // set user ID
        if let userId = user.userId {
            pushwoosh.setUserId(userId)
        }

        // set user email
        if let userEmail = user.email {
            pushwoosh.setEmail(userEmail)
        }

        // set user SMS number
        if let userSmsNumber = user.SmsNumber {
            pushwoosh.registerSmsNumber(userSmsNumber)
        }

        // set user WhatsApp number
        if let userWhatsAppNumber = user.WhatsAppNumber {
            pushwoosh.registerSmsNumber(userWhatsAppNumber)
        }

        // setting additional user information as tags for Pushwoosh
        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 <PushwooshFramework/PushwooshFramework.h>

@implementation Registration

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

    // set user ID
    if (user.userId) {
        [pushwoosh setUserId:user.userId];
    }

    // set user email
    if (user.email) {
        [pushwoosh setEmail:user.email];
    }

    // setting additional user information as tags for Pushwoosh
    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

Tags

Les tags sont des paires clé-valeur attribuées aux utilisateurs ou aux appareils, permettant une segmentation basée sur des attributs tels que les préférences ou le comportement, ce qui rend possible la messagerie ciblée.

Swift

import PushwooshFramework

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

        // set list of favorite categories
        pushwoosh.setTags(["favorite_categories" : user.getFavoriteCategories()])

        // set payment information
        pushwoosh.setTags([
            "is_subscribed": user.isSubscribed(),
            "payment_status": user.getPaymentStatus(),
            "billing_address": user.getBillingAddress()
        ])
    }
}

Objective-C

#import <PushwooshFramework/PushwooshFramework.h>

@implementation UpdateUser

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

    // set list of favorite categories
    [pushwoosh setTags:@{@"favorite_categories" : user.getFavoriteCategories}];

    // set payment information
    NSDictionary *tags = @{
        @"is_subscribed": @(user.isSubscribed),
        @"payment_status": user.getPaymentStatus,
        @"billing_address": user.getBillingAddress
    };
    [pushwoosh setTags:tags];
}

@end

Événements

Les événements sont des actions ou des occurrences spécifiques de l’utilisateur au sein de l’application qui peuvent être suivies pour analyser le comportement et déclencher des messages ou des actions correspondants

Swift

import PushwooshFramework

class Registration {

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

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

        // Track purchase event
        PWInAppManager.shared().postEvent("purchase", withAttributes: [
            "product_id": product.getId(),
            "product_name": product.getName(),
            "price": product.getPrice(),
            "quantity": product.getQuantity()
        ])

        // Set user tags
        let lastPurchaseDate = Date().timeIntervalSince1970
        let lifetimeSpend = getCurrentLifetimeSpend() + product.getPrice()

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

Objective-C

#import <PushwooshFramework/PushwooshFramework.h>
#import <PushwooshFramework/PWInAppManager.h>

@implementation Registration

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

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

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

    // Track purchase event
    [[PWInAppManager sharedManager] postEvent:@"purchase" withAttributes:@{
        @"product_id": [product getId],
        @"product_name": [product getName],
        @"price": @([product getPrice]),
        @"quantity": @([product getQuantity])
    }];

    // Set user tags
    NSTimeInterval lastPurchaseDate = [[NSDate date] timeIntervalSince1970];
    double lifetimeSpend = /* fetch current lifetime spend */ + [product getPrice];

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

    [pushwoosh setTags:tags];
}

@end

Rich Media

Le Rich Media fait référence au contenu interactif et multimédia, tel que des images, des vidéos ou du HTML, utilisé dans les notifications et les messages in-app pour améliorer l’engagement de l’utilisateur

Swift

import PushwooshFramework

class ViewController: UIViewController, PWRichMediaPresentingDelegate {

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

        PWRichMediaManager.shared().delegate = self
        richMediaConfiguration.configureModalWindow(with: .PWModalWindowPositionBottom,
                                                                 present: .PWAnimationPresentFromBottom,
                                                                 dismiss: .PWAnimationDismissDown)
    }

    func richMediaManager(_ richMediaManager: PWRichMediaManager!, shouldPresent richMedia: PWRichMedia!) -> Bool {
        print("Rich media will be presented with: \(richMedia.pushPayload!)")
        return true
    }

    func richMediaManager(_ richMediaManager: PWRichMediaManager!, didPresent richMedia: PWRichMedia!) {
        print("Rich media has been presented with: \(richMedia.pushPayload!)")
    }

    func richMediaManager(_ richMediaManager: PWRichMediaManager!, didClose richMedia: PWRichMedia!) {
        print("Rich media has been closed with: \(richMedia.pushPayload!)")
    }

    func richMediaManager(_ richMediaManager: PWRichMediaManager!, presentingDidFailFor richMedia: PWRichMedia!, withError error: (any Error)!) {
        print("Failed to present rich media with: \(richMedia.pushPayload!). Error: \(error.localizedDescription)")
    }
}

Objective-C

#import "ViewController.h"
#import <PushwooshFramework/PushwooshFramework.h>
#import <PushwooshFramework/PWRichMediaManager.h>
#import <PushwooshFramework/PWModalWindowConfiguration.h>

@interface ViewController () <PWRichMediaPresentingDelegate>

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    [[PWRichMediaManager sharedManager] setDelegate:self];
    [[PWModalWindowConfiguration shared] configureModalWindowWith:PWModalWindowPositionBottom
                                                 presentAnimation:PWAnimationPresentFromBottom
                                                 dismissAnimation:PWAnimationDismissDown];
}

- (BOOL)richMediaManager:(PWRichMediaManager *)richMediaManager shouldPresentRichMedia:(PWRichMedia *)richMedia {
    NSLog(@"Rich media will be presented with: %@", richMedia.pushPayload);
    return YES;
}

- (void)richMediaManager:(PWRichMediaManager *)richMediaManager didPresentRichMedia:(PWRichMedia *)richMedia {
    NSLog(@"Rich media has been presented with: %@", richMedia.pushPayload);
}

- (void)richMediaManager:(PWRichMediaManager *)richMediaManager didCloseRichMedia:(PWRichMedia *)richMedia {
    NSLog(@"Rich media has been closed with:: %@", richMedia.pushPayload);
}

- (void)richMediaManager:(PWRichMediaManager *)richMediaManager presentingDidFailForRichMedia:(PWRichMedia *)richMedia withError:(NSError *)error {
    NSLog(@"Failed to present rich media with: %@. Error: %@", richMedia.pushPayload, error.localizedDescription);
}

@end

Dépannage

Échec de la compilation du module ‘PushwooshFramework’

Lors de la compilation de votre projet, vous pouvez rencontrer une erreur similaire à :

Failed to build module 'PushwooshFramework'; this SDK is not supported by the compiler
(the SDK is built with 'Apple Swift version 5.10 (swiftlang-5.10.0.13 clang-1500.3.9.4)',
while this compiler is 'Apple Swift version 6.1.2 effective-5.10 (swiftlang-6.1.2.1.2 clang-1700.0.13.5)')

Cause : Cette erreur n’est pas liée à une incompatibilité de version du compilateur Swift. À partir de la version 6.8.0 du SDK Pushwoosh pour iOS, le SDK est modularisé en plusieurs composants qui interagissent les uns avec les autres. L’erreur se produit lorsque tous les frameworks requis ne sont pas ajoutés à votre projet.

Solution : Assurez-vous que les quatre frameworks requis sont ajoutés à la cible de votre application lors de l’intégration via Swift Package Manager :

• PushwooshFramework
• PushwooshCore
• PushwooshBridge
• PushwooshLiveActivities

Pour vérifier cela dans Xcode :

1. Sélectionnez votre projet dans le navigateur de projet (Project Navigator)
2. Sélectionnez la cible de votre application
3. Allez dans General > Frameworks, Libraries, and Embedded Content
4. Confirmez que les quatre frameworks sont listés

---

Si vous rencontrez des problèmes pendant le processus d’intégration, veuillez vous référer à la section support et communauté.