# تمهيد الإشعارات الفورية لنظام iOS

تمهيد الإشعارات الفورية هو مربع حوار اشتراك اختياري ناعم تعرضه **قبل** مطالبة نظام iOS بإذن الإشعارات الفورية. يعرض نظام iOS مطالبة النظام مرة واحدة فقط لكل تثبيت — إذا نقر المستخدم على **عدم السماح**، فسيتم فقدان الإشعارات الفورية حتى يعيد تمكينها في الإعدادات. يتيح لك التمهيد شرح القيمة أولاً والسؤال في اللحظة المناسبة، بحيث تستخدم مطالبة النظام التي تظهر مرة واحدة فقط على المستخدمين الذين وافقوا بالفعل.

متوفر منذ الإصدار 7.1.1. التمهيد هو جزء من `PushwooshFramework`؛ لا يلزم وجود وحدة إضافية.

<figure style={{ textAlign: "center" }}>
  <img
    src="/ios-push-primer-1.webp"
    alt="مربع حوار تمهيد الإشعارات يظهر قبل مطالبة النظام بالإذن"
    style={{ display: "block", margin: "0 auto", maxWidth: "300px", height: "auto" }}
    width="300"
  />
  <figcaption>تمهيد الإشعارات يظهر قبل مطالبة نظام iOS بإذن الإشعارات الفورية</figcaption>
</figure>

## كيف يعمل

يدرك التمهيد الحالة بالكامل. يقرأ حالة تفويض الإشعارات الحالية ويقرر ما يجب فعله، لذا من الآمن استدعاؤه عند كل تشغيل:

- **غير محدد** — يعرض التمهيد؛ عند القبول، فإنه يطلق مطالبة النظام بالإذن.
- **مصرح به أو مؤقت** — يكبت التمهيد بصمت (لا يتم عرض أي شيء).
- **مرفوض** — يعرض التمهيد؛ عند القبول، فإنه يوجه المستخدم إلى إعدادات إشعارات التطبيق (عند تمكين `fallbackToSettings`).

أنت تقرر **متى** تستدعي التمهيد (على سبيل المثال بعد عملية الإعداد أو بعد إجراء رئيسي). لا يفرض SDK أي توقيت خاص به، باستثناء التقييد الاختياري `minInterval` الموضح أدناه.

## الاستخدام الأساسي

قم بتكوين التمهيد باستخدام واجهة بناء سلسة واستدعِ `present`. يتطلب الإعداد الأدنى عنوانًا ورسالة وعناوين للزرين.

<Tabs>
<TabItem label="Swift">
```swift
import PushwooshFramework

Pushwoosh.configure.pushPrimer
    .title("ابق على اطلاع")
    .message("كن أول من يتلقى إشعارات حول الصفقات وتحديثات الطلبات")
    .acceptButton("تمكين الإشعارات")
    .declineButton("ليس الآن")
    .present()
```
</TabItem>
</Tabs>

<Aside type="note">
استدعِ التمهيد بعد ظهور واجهة مستخدم التطبيق على الشاشة (على سبيل المثال بعد لحظة قصيرة من التشغيل، أو في خطوة مدروسة في تدفقك)، حتى يتمكن من الظهور فوق واجهتك.
</Aside>

## الأنماط والمواضع

استخدم `style` للاختيار بين تنبيه النظام وورقة مخصصة، و `position` لوضع الورقة المخصصة. كل موضع له تصميمه الافتراضي الخاص.

| القيمة | الوصف |
|-------|-------------|
| `.alert` | تنبيه نظام `UIAlertController`. يتم تجاهل الموضع. |
| `.sheet` + `.bottom` | ورقة سفلية تنزلق لأعلى، مع مقبض وأزرار بعرض كامل (الافتراضي). |
| `.sheet` + `.top` | لافتة مدمجة تنزل من الأعلى، مثل إشعار. |
| `.sheet` + `.center` | مربع حوار متمركز يتوسع ويتلاشى للظهور. |

<Tabs>
<TabItem label="Swift">
```swift
Pushwoosh.configure.pushPrimer
    .style(.sheet)
    .position(.top)
    .title("ابق على اطلاع")
    .message("كن أول من يتلقى إشعارات حول الصفقات وتحديثات الطلبات")
    .acceptButton("تمكين الإشعارات")
    .declineButton("ليس الآن")
    .present()
```
</TabItem>
</Tabs>

<img src="/ios-push-primer-positions.webp" alt="تمهيد الإشعارات في المواضع السفلية والعلوية والوسطى"/>

## التخصيص

جميع الإعدادات المرئية اختيارية — احذفها لاستخدام القيم الافتراضية الأصلية التي تتكيف مع الوضع الفاتح والداكن.

<Tabs>
<TabItem label="Swift">
```swift
Pushwoosh.configure.pushPrimer
    .style(.sheet)
    .position(.center)
    .title("ابق على اطلاع")
    .message("كن أول من يتلقى إشعارات حول الصفقات وتحديثات الطلبات")
    .acceptButton("تمكين الإشعارات")
    .declineButton("ليس الآن")
    .image(UIImage(named: "PrimerHero"))          // صورة محلية، أو .imageURL("https://…")
    .backgroundColor(.systemBackground)
    .titleColor(.label)
    .messageColor(.secondaryLabel)
    .acceptButtonColor(.systemBlue)
    .acceptButtonTextColor(.white)
    .declineButtonColor(.clear)
    .declineButtonTextColor(.secondaryLabel)
    .cornerRadius(24)
    .buttonCornerRadius(14)
    .buttonBorderColor(.separator)
    .present()
```
</TabItem>
</Tabs>

مرجع التخصيص:

| المُعيِّن (Setter) | الوصف |
|--------|-------------|
| `image` / `imageURL` | `UIImage` محلي أو عنوان URL بعيد. يتم عرضه كدائرة في التخطيطات الوسطى والسفلية، وكأيقونة في اللافتة العلوية. الصورة المحلية لها الأسبقية على عنوان URL. |
| `backgroundColor` | لون خلفية البطاقة الصلب. |
| `backgroundGradient` | مصفوفة من الألوان يتم عرضها كتدرج لوني ناعم متعدد الألوان. يتجاوز `backgroundColor`. |
| `titleColor` / `messageColor` | ألوان نص العنوان والرسالة. |
| `acceptButtonColor` / `acceptButtonTextColor` | ألوان خلفية ونص زر القبول. لون القبول يلون أيضًا الأيقونة الافتراضية. |
| `declineButtonColor` / `declineButtonTextColor` | ألوان خلفية ونص زر الرفض. |
| `cornerRadius` | نصف قطر زاوية البطاقة. |
| `buttonCornerRadius` / `buttonBorderColor` | نصف قطر الزاوية ولون حدود كلا الزرين. |

<Aside type="note">
يعرض التمهيد بالضبط السلاسل النصية التي تمررها. للغات متعددة، مرر سلاسل نصية مترجمة (على سبيل المثال باستخدام `NSLocalizedString`).
</Aside>

## إعدادات السلوك

### الرجوع إلى الإعدادات

بشكل افتراضي، عندما تكون الإشعارات مرفوضة بالفعل، يتم عرض التمهيد ويأخذ زر القبول المستخدم إلى إعدادات إشعارات التطبيق. مرر `false` لكبت التمهيد بالكامل في حالة الرفض بدلاً من ذلك.

```swift
.fallbackToSettings(false)
```

### تكرار العرض

بشكل افتراضي، لا يحتوي التمهيد على أي تقييد مدمج — يظهر كلما استدعيت `present` (ويتم كبته تلقائيًا بمجرد تفويض الإشعارات). استخدم `minInterval` لتحديد عدد مرات ظهور التمهيد. يتم الاحتفاظ بآخر وقت عرض عبر عمليات التشغيل.

```swift
.minInterval(7 * 24 * 60 * 60)   // إظهاره مرة واحدة في الأسبوع على الأكثر
```

## التعامل مع النتيجة

مرر دالة إكمال (completion) إلى `present` للتفاعل مع النتيجة.

<Tabs>
<TabItem label="Swift">
```swift
Pushwoosh.configure.pushPrimer
    .title("ابق على اطلاع")
    .message("كن أول من يتلقى إشعارات حول الصفقات وتحديثات الطلبات")
    .acceptButton("تمكين الإشعارات")
    .declineButton("ليس الآن")
    .present { outcome in
        switch outcome {
        case .accepted:            break   // تم عرضه، قبل المستخدم، تم طلب مطالبة النظام
        case .declined:            break   // تم عرضه، رفض المستخدم
        case .suppressed:          break   // لم يتم عرضه (مصرح به بالفعل، أو تم تقييده)
        case .redirectedToSettings: break  // حالة الرفض، تم إرسال المستخدم إلى الإعدادات
        @unknown default:          break
        }
    }
```
</TabItem>
</Tabs>

تصل نتيجة مطالبة النظام النهائية (حالة المنح/الرفض ورمز الجهاز) من خلال استدعاءات التسجيل العادية — يعيد التمهيد استخدام `registerForPushNotifications` عند القبول ولا يكرر تلك السلسلة.

## المراجع

<CardGrid>
  <LinkCard
    title="مرجع واجهة برمجة تطبيقات iOS SDK"
    description="توثيق فني كامل يغطي جميع الفئات والأساليب والخصائص العامة."
    href="https://pushwoosh.github.io/pushwoosh-ios-sdk/"
  />
  <LinkCard
    title="تخصيص iOS SDK"
    description="طرق أخرى لتكييف Pushwoosh iOS SDK مع تطبيقك."
    href="/developer/pushwoosh-sdk/ios-sdk/customizing-ios-sdk/"
  />
</CardGrid>