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

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.configure.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 configure] 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 بذلك للحصول على سلوك صحيح. يمكنك القيام بذلك باستخدام طريقة `addNotificationCenterDelegate`:

<Tabs syncKey="code-example">
    <TabItem label="Swift">
    ```swift
    Pushwoosh.configure.addNotificationCenterDelegate(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.configure 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` في المفوّض الخاص بك:

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