دليل التكامل المتقدم لـ iOS SDK

يقدم هذا القسم معلومات حول التكامل المتقدم لـ Pushwoosh iOS SDK.

أوضاع الخلفية

تنبيه

بشكل افتراضي، لا يسمح نظام iOS للتطبيقات بمعالجة الإشعارات الفورية (push notifications) عندما تكون في الخلفية. وهذا يشمل الإشعارات الفورية الصامتة (silent push notifications)، والتي تكون مفيدة لتحديث بيانات التطبيق دون تفاعل المستخدم.

لتمكين هذه الوظيفة، يجب عليك إضافة أوضاع الخلفية (Background Modes) إلى مشروعك.

خطوات تمكين أوضاع الخلفية

1. افتح مشروعك في Xcode وحدده في Project Navigator.
2. اختر هدف تطبيقك من اللوحة اليسرى.
3. انتقل إلى علامة التبويب Signing & Capabilities.
4. انقر على زر + Capability في الزاوية العلوية اليسرى.
5. ابحث عن Background Modes وحددها من القائمة.
6. في قسم Background Modes، قم بتمكين Remote notifications عن طريق تحديد المربع.

بمجرد الانتهاء، سيتمكن تطبيقك من التعامل مع الإشعارات الفورية، بما في ذلك الإشعارات الصامتة، أثناء تشغيله في الخلفية.

أوضاع الواجهة الأمامية

بشكل افتراضي، يعرض Pushwoosh iOS SDK لافتة الإشعار عندما يكون التطبيق قيد التشغيل في الواجهة الأمامية.

يمكنك التحكم في هذا السلوك عن طريق تعيين العلامة المنطقية (boolean flag) التالية في الكود الخاص بك (على سبيل المثال، في AppDelegate الخاص بك):

Swift

// Set false to disable foreground notifications, true to enable it
Pushwoosh.sharedInstance().showPushnotificationAlert = true

مثال (Swift)

Objective-C

// Set 0 to disable foreground notifications, 1 to enable it
[[Pushwoosh sharedInstance] setShowPushnotificationAlert:0];

مثال (Objective-C)

مستوى التسجيل (Log level)

يدعم Pushwoosh iOS SDK مستويات التسجيل التالية:

• NONE - لا توجد سجلات من SDK.
• ERROR - يعرض رسائل الخطأ فقط في وحدة التحكم.
• WARNING - يعرض التحذيرات بالإضافة إلى الأخطاء.
• INFO - يتضمن رسائل إعلامية (الإعداد الافتراضي).
• DEBUG - يتضمن معلومات تصحيح أخطاء مفصلة.

بشكل افتراضي، يتم تعيين مستوى التسجيل على INFO، مما يضمن أن SDK يوفر معلومات ذات صلة دون ازدحام وحدة تحكم المطور.

لتعديل مستوى التسجيل، قم بتحديث مفتاح Pushwoosh_LOG_LEVEL في ملف Info.plist الخاص بتطبيقك:

<key>Pushwoosh_LOG_LEVEL</key>
<string>YOUR_LOG_LEVEL</string>

بدلاً من ذلك، يمكنك تغيير مستوى السجل باستخدام مقتطف الكود أدناه:

Pushwoosh.Debug.setLogLevel(.PW_LL_DEBUG)

استبدل YOUR_LOG_LEVEL بالمستوى المطلوب (على سبيل المثال، DEBUG أو ERROR).

UNNotificationCenterDelegate مخصص

إذا كنت ترغب في استخدام UNNotificationCenterDelegate الخاص بك (على سبيل المثال، للإشعارات المحلية)، يجب عليك إبلاغ Pushwoosh SDK بذلك للحصول على السلوك الصحيح. يمكنك القيام بذلك باستخدام خاصية notificationCenterDelegateProxy لمثيل Pushwoosh:

Swift

Pushwoosh.sharedInstance().notificationCenterDelegateProxy?.add(my_delegate)

مثال (Swift)

Objective-C

[Pushwoosh.sharedInstance.notificationCenterDelegateProxy addNotificationCenterDelegate:my_delegate];

مثال (Objective-C)

بعد ذلك، قم بتنفيذ دوال UNNotificationCenterDelegate في المفوّض (delegate) الخاص بك:

Swift

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
    if (!PWMessage.isPushwooshMessage(notification.request.content.userInfo)) {
        // Handle your notification
        completionHandler(UNNotificationPresentationOptions.alert)
    }
}

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    if (!PWMessage.isPushwooshMessage(response.notification.request.content.userInfo)) {
        // Handle your notification
        completionHandler()
    }
}

مثال (Swift)

Objective-C

- (void)userNotificationCenter:(UNNotificationCenter *)center
        willPresentNotification:(UNNotification *)notification
        withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
    if (![PWMessage isPushwooshMessage:notification.request.content.userInfo]) {
        // Handle your message
        completionHandler(UNNotificationPresentationOptionAlert);
    }
}

- (void)userNotificationCenter:(UNNotificationCenter *)center
        didReceiveNotificationResponse:(UNNotificationResponse *)response
        withCompletionHandler:(void (^)(void))completionHandler {
    if (![PWMessage.isPushwooshMessage:response.notification.request.content.userInfo]) {
        // Handle your message
        completionHandler();
    }
}

مثال (Objective-C)

التهيئة الكسولة لـ Pushwoosh

تمنع علامة Pushwoosh_LAZY_INITIALIZATION التهيئة التلقائية لـ Pushwoosh SDK عند بدء تشغيل التطبيق. وهذا يسمح بمزيد من التحكم في وقت بدء خدمات Pushwoosh SDK.

عند تمكين هذه العلامة، لا يبدأ Pushwoosh SDK خدماته حتى يتم استدعاء دوال Pushwoosh iOS SDK بشكل صريح.

أضف الإدخال التالي إلى Info.plist:

<key>Pushwoosh_LAZY_INITIALIZATION</key>
<true/>

حالات الاستخدام

1. تهيئة SDK المتحكم بها – تسمح علامة Pushwoosh_LAZY_INITIALIZATION بتأخير بدء تشغيل Pushwoosh SDK، مما يمنح مزيدًا من التحكم في وقت تنشيط خدمات الإشعارات.

2. تفعيل الإشعارات المؤجل – في بعض التطبيقات، يجب تهيئة الإشعارات الفورية فقط في ظل ظروف محددة. يضمن تمكين هذه العلامة أن Pushwoosh SDK يبدأ فقط عند طلبه بشكل صريح.

3. تكوين الإشعارات الخاص بالمستخدم – قد تتطلب بعض التطبيقات تخصيص إعدادات الإشعارات الفورية بناءً على تفضيلات المستخدم أو إعدادات الحساب. مع التهيئة الكسولة، يبدأ Pushwoosh SDK فقط بعد تحديد التكوين المناسب.

القائمة الكاملة لخصائص Info.plist

الخاصية	الوصف	القيم الممكنة
Pushwoosh_APPID	يضبط معرّف تطبيق Pushwoosh لنسخة الإنتاج.	XXXXX-XXXXX النوع: String
Pushwoosh_APPID_Dev	يضبط معرّف تطبيق Pushwoosh لنسخة التطوير.	XXXXX-XXXXX النوع: String
Pushwoosh_SHOW_ALERT	يعرض تنبيه الإشعار في الواجهة الأمامية.	YES (افتراضي) / NO النوع: Boolean
Pushwoosh_ALERT_TYPE	يضبط نمط تنبيه الإشعار.	BANNER (افتراضي) / ALERT / NONE النوع: String
Pushwoosh_BASEURL	يتجاوز عنوان URL الأساسي لخادم Pushwoosh.	https://cp.pushwoosh.com/json/1.3/ (افتراضي) النوع: String
Pushwoosh_AUTO_ACCEPT_DEEP_LINK_FOR_SILENT_PUSH	إذا كانت القيمة YES، فسيتم معالجة الروابط العميقة (Deep Links) المستلمة في الإشعارات الصامتة تلقائيًا.	YES (افتراضي) / NO النوع: Boolean
Pushwoosh_ALLOW_SERVER_COMMUNICATION	يسمح لـ SDK بإرسال طلبات الشبكة إلى خوادم Pushwoosh.	YES (افتراضي) / NO النوع: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_DATA	يسمح لـ SDK بجمع وإرسال بيانات الجهاز (إصدار نظام التشغيل، والإعدادات المحلية، والطراز) إلى الخادم.	YES (افتراضي) / NO النوع: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_OS_VERSION	يسمح لـ SDK بجمع وإرسال إصدار نظام تشغيل الجهاز إلى الخادم.	YES (افتراضي) / NO النوع: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_LOCALE	يسمح لـ SDK بجمع وإرسال الإعدادات المحلية للجهاز إلى الخادم.	YES (افتراضي) / NO النوع: Boolean
Pushwoosh_ALLOW_COLLECTING_DEVICE_MODEL	يسمح لـ SDK بجمع وإرسال طراز الجهاز إلى الخادم.	YES (افتراضي) / NO النوع: Boolean
Pushwoosh_LOG_LEVEL	مستوى تسجيل Pushwoosh SDK. لمزيد من التفاصيل، راجع التحكم في مستوى التسجيل.	NONE / ERROR / WARNING / INFO (افتراضي) / DEBUG / VERBOSE النوع: String
Pushwoosh_PURCHASE_TRACKING_ENABLED	يسمح لـ SDK بتتبع عمليات الشراء داخل التطبيق. مطلوب لـ Customer Journey Builder.	YES / NO (افتراضي) النوع: Boolean