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

import { Badge } from '@astrojs/starlight/components';

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

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

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

لتمكين هذه الوظيفة، يجب عليك إضافة أوضاع الخلفية (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` الخاص بك):

<Tabs syncKey="code-example">
    <TabItem label="Swift">
    ```swift
    // Set false to disable foreground notifications, true to enable it
    Pushwoosh.sharedInstance().showPushnotificationAlert = true
    ```

    <LinkCard
        title="مثال (Swift)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizing/ViewController.swift#L30"
    />

  </TabItem>

  <TabItem label="Objective-C">

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

    <LinkCard
        title="مثال (Objective-C)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizingObjC/customizingObjC/ViewController.m#L35"
    />

  </TabItem>
</Tabs>

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

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

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

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

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

```xml
<key>Pushwoosh_LOG_LEVEL</key>
<string>YOUR_LOG_LEVEL</string>
```

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

```swift
Pushwoosh.Debug.setLogLevel(.PW_LL_DEBUG)
```

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

## `UNNotificationCenterDelegate` مخصص

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

<Tabs syncKey="code-example">
    <TabItem label="Swift">
    ```swift
    Pushwoosh.sharedInstance().notificationCenterDelegateProxy?.add(my_delegate)
    ```

    <LinkCard
        title="مثال (Swift)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizing/Custom%20UNNotificationCenterDelegate/CustomNotificationCDViewConrtoller.swift#L23"
    />

    </TabItem>

    <TabItem label="Objective-C">
    ```objective-c
    [Pushwoosh.sharedInstance.notificationCenterDelegateProxy addNotificationCenterDelegate:my_delegate];
    ```

    <LinkCard
        title="مثال (Objective-C)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizingObjC/customizingObjC/Custom%20UNNotificationCenterDelegate/PWCustomNotificationCDViewConrtoller.m#L28"
    />

    </TabItem>
</Tabs>

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

<Tabs syncKey="code-example">
  <TabItem label="Swift">

  ```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()
      }
  }
  ```

  <LinkCard title="مثال (Swift)" href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizing/Custom%20UNNotificationCenterDelegate/CustomNotificationCDViewConrtoller.swift" />

  </TabItem>

  <TabItem label="Objective-C">

  ```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();
      }
  }
  ```

  <LinkCard title="مثال (Objective-C)" href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizingObjC/customizingObjC/Custom%20UNNotificationCenterDelegate/PWCustomNotificationCDViewConrtoller.m" />

  </TabItem>
</Tabs>

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

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

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

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

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