دليل التكامل المتقدم لـ 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)

مستوى السجل

يدعم 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 في المندوب الخاص بك:

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