دليل التكامل الأساسي لـ iOS SDK 7.0+

يحتوي هذا القسم على معلومات حول كيفية دمج Pushwoosh SDK في تطبيق iOS الخاص بك.

المتطلبات الأساسية

لدمج Pushwoosh iOS SDK في تطبيقك، ستحتاج إلى ما يلي:

المتطلبات

• حساب Pushwoosh
• مشروع Pushwoosh تم إعداده في حسابك.
• منصة iOS مهيأة لإرسال الإشعارات الفورية. نوصي باستخدام تهيئة المصادقة المستندة إلى الرمز المميز كأبسط طريقة.
• أثناء الإعداد، قم بتعيين البوابة (Gateway) إلى Sandbox لإرسال الإشعارات الفورية إلى جهاز محاكاة.
• Pushwoosh Application Code الخاص بك و Pushwoosh Device API Token من لوحة تحكم Pushwoosh لتطبيقك.

خطوات التكامل

1. التثبيت

يمكنك دمج Pushwoosh SDK في تطبيقك باستخدام Swift Package Manager أو CocoaPods.

Swift Package Manager

في قسم Package Dependencies، أضف الحزمة التالية:

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

لاستخدام Pushwoosh iOS SDK، تأكد من إضافة الأطر الأربعة التالية إلى هدف تطبيقك عند التكامل عبر Swift Package Manager:

• PushwooshFramework
• PushwooshCore
• PushwooshBridge
• PushwooshLiveActivities

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

end

بعد ذلك، في الطرفية (terminal)، قم بتشغيل الأمر التالي لتثبيت التبعيات:

pod install

2. الإمكانيات (Capabilities)

لتمكين الإشعارات الفورية في مشروعك، تحتاج إلى إضافة إمكانيات معينة.

في قسم Signing & Capabilities، أضف الإمكانيات التالية:

• Push Notifications
• Background Modes. بعد إضافة هذه الإمكانية، حدد مربع Remote notifications.

إذا كنت تنوي استخدام الإشعارات الحساسة للوقت (Time Sensitive Notifications) (iOS 15+)، أضف أيضًا إمكانية Time Sensitive Notifications.

3. كود التهيئة

AppDelegate

أضف الكود التالي إلى فئة 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.configure.delegate = self

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

        return true
    }

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

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

    //for silent push notifications
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        Pushwoosh.configure.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.configure.delegate = self;

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

        return true
    }

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

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

    //for silent push notifications
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        Pushwoosh.configure.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 configure].delegate = self;

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

  return YES;
}

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

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

//for silent push notifications
- (void)application:(UIApplication *)application
  didReceiveRemoteNotification:(NSDictionary *)userInfo
      fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [[Pushwoosh configure] 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

في ملف Info.plist الخاص بك:

• قم بتعيين مفتاح Pushwoosh_APPID إلى رمز تطبيق Pushwoosh.
• قم بتعيين مفتاح Pushwoosh_API_TOKEN إلى رمز واجهة برمجة تطبيقات جهاز Pushwoosh (Pushwoosh Device API Token)

4. تتبع تسليم الرسائل

يدعم Pushwoosh تتبع أحداث التسليم للإشعارات الفورية عبر ملحق خدمة الإشعارات (Notification Service Extension)

إضافة ملحق خدمة الإشعارات (Notification Service Extension)

1. في Xcode، حدد File > New > Target…
2. اختر Notification Service Extension واضغط على Next.
3. أدخل اسم الهدف واضغط على Finish.
4. عندما يُطلب منك التنشيط، اضغط على Cancel.

التبعيات لملحق خدمة الإشعارات (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 'PushwooshXCFramework'

end

target 'MyAppNotificationExtension' do
  use_frameworks!

  pod 'PushwooshXCFramework'

end

قم بتشغيل الأمر التالي في الطرفية (terminal) لتحديث التبعيات:

pod update

إضافة Pushwoosh SDK إلى ملحق خدمة الإشعارات

يسمح لك هذا الكود باعتراض ومعالجة الإشعارات داخل ملحق الإشعارات الخاص بك.

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

في ملف Info.plist الخاص بملحق خدمة الإشعارات، أضف:

• Pushwoosh_APPID - رمز التطبيق الخاص بك.

5. تشغيل المشروع

1. قم ببناء وتشغيل المشروع.
2. اذهب إلى لوحة تحكم Pushwoosh وأرسل إشعارًا فوريًا.
3. يجب أن ترى الإشعار في التطبيق.

تكامل Pushwoosh iOS الممتد

في هذه المرحلة، لقد قمت بالفعل بدمج SDK ويمكنك إرسال واستقبال الإشعارات الفورية. الآن، دعنا نستكشف الوظائف الأساسية

الإشعارات الفورية

في Pushwoosh SDK، هناك استدعاءان (callbacks) مصممان للتعامل مع الإشعارات الفورية:

• onMessageReceived: يتم استدعاء هذه الطريقة عند استلام إشعار فوري.
• onMessageOpened: يتم استدعاء هذه الطريقة عندما يتفاعل المستخدم مع الإشعار (يفتحه)

تمكن هذه الاستدعاءات المطورين من إدارة استقبال الإشعارات الفورية وتفاعل المستخدم معها داخل تطبيقاتهم

Swift

import PushwooshFramework

class AppDelegate: NSObject, UIApplicationDelegate, PWMessagingDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Pushwoosh.configure.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 configure] 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

تكوين المستخدم

من خلال التركيز على سلوك المستخدم الفردي وتفضيلاته، يمكنك تقديم محتوى مخصص، مما يؤدي إلى زيادة رضا المستخدم وولائه

Swift

import PushwooshFramework

class Registration {

    func afterUserLogin(user: User) {
        let pushwoosh = Pushwoosh.configure
        // 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 configure];

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

العلامات هي أزواج من المفاتيح والقيم يتم تعيينها للمستخدمين أو الأجهزة، مما يسمح بالتقسيم بناءً على سمات مثل التفضيلات أو السلوك، مما يتيح المراسلة المستهدفة.

Swift

import PushwooshFramework

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

        // 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 configure];

    // 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

الأحداث (Events)

الأحداث هي إجراءات مستخدم محددة أو وقائع داخل التطبيق يمكن تتبعها لتحليل السلوك وتشغيل الرسائل أو الإجراءات المقابلة

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.configure

        // 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 configure];

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

تشير الوسائط الغنية إلى المحتوى التفاعلي والوسائط المتعددة، مثل الصور أو مقاطع الفيديو أو HTML، المستخدم في الإشعارات والرسائل داخل التطبيق لتعزيز تفاعل المستخدم

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

استكشاف الأخطاء وإصلاحها

فشل في بناء الوحدة ‘PushwooshFramework’

عند بناء مشروعك، قد تواجه خطأً مشابهًا لـ:

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

السبب: هذا الخطأ لا يتعلق بعدم توافق إصدار مترجم Swift. بدءًا من إصدار Pushwoosh iOS SDK 6.8.0، تم تقسيم SDK إلى عدة مكونات تتفاعل مع بعضها البعض. يحدث الخطأ عندما لا تتم إضافة جميع الأطر المطلوبة إلى مشروعك.

الحل: تأكد من إضافة جميع الأطر الأربعة المطلوبة إلى هدف تطبيقك عند التكامل عبر Swift Package Manager:

• PushwooshFramework
• PushwooshCore
• PushwooshBridge
• PushwooshLiveActivities

للتحقق من ذلك في Xcode:

1. حدد مشروعك في Project Navigator
2. حدد هدف تطبيقك
3. اذهب إلى General > Frameworks, Libraries, and Embedded Content
4. تأكد من إدراج جميع الأطر الأربعة

---

إذا واجهت أي مشاكل أثناء عملية التكامل، يرجى الرجوع إلى قسم الدعم والمجتمع.