Swift Academy · درس

التعامل مع حمولات الإشعارات

استجب للإشعارات في المقدمة والخلفية.

التعامل مع حمولات الإشعارات درس مجاني في Swift Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Swift Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Swift Academy 4 دروس في المجموع.

بنية الحمولة

الإشعار البعيد هو قاموس JSON يرسله خادمكم إلى APNs. يحتوي المفتاح المحجوز aps على المحتوى الظاهر للمستخدم — التنبيه والصوت والشارة — بينما تحمل المفاتيح الأخرى على المستوى نفسه بياناتكم المخصصة، مثل معرّف عنصر لفتحه.

// Example payload JSON:
// {
//   "aps": { "alert": { "title": "Hi", "body": "..." },
//            "sound": "default", "badge": 1 },
//   "itemId": "42"
// }

قاموس aps

داخل aps، يمكن أن تكون alert سلسلة نصية أو كائنًا يضم العنوان والنص والعنوان الفرعي. كما توجد هنا sound وbadge وأعلام مثل content-available وmutable-content. أما كل ما يقع خارج aps فهو متروك لكم لتحديده.

// aps keys:
//   alert: { title, subtitle, body }
//   sound: "default" or critical sound object
//   badge: Int
//   content-available: 1  (silent / background)
//   mutable-content: 1    (allow modification)

التسليم في المقدمة

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

import UserNotifications
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification
) async -> UNNotificationPresentationOptions {
    return [.banner, .sound, .badge]
}

الاستجابة للنقر

عندما ينقر المستخدم على إشعار، سواء كان التطبيق في الخلفية أو متوقفًا، تُستدعى didReceive response الخاصة بالمفوض. هنا تقرؤون الحمولة وتنتقلون إلى الشاشة المناسبة.

import UserNotifications
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse
) async {
    let info = response.notification.request
        .content.userInfo
    if let id = info["itemId"] as? String {
        print("open item", id)
    }
}

قراءة userInfo

تظهر الحمولة الكاملة، بما في ذلك مفاتيحكم المخصصة، في content.userInfo، وهي قاموس من النوع [AnyHashable: Any]. تحقّقوا من نوع كل قيمة بعناية؛ ولا تستخدموا فك الإلغاء القسري مطلقًا، لأن الحمولة غير الصحيحة يجب ألا تتسبب في تعطل التطبيق.

import UserNotifications
func route(_ userInfo: [AnyHashable: Any]) {
    guard let screen = userInfo["screen"] as? String
    else { return }
    switch screen {
    case "profile": print("go to profile")
    case "cart":    print("go to cart")
    default:        break
    }
}

الإشعارات الصامتة (في الخلفية)

يؤدي ضبط content-available: 1 وحذف التنبيه إلى إنشاء إشعار push صامت يوقظ التطبيق في الخلفية لجلب البيانات من دون أي واجهة مستخدم. يحد النظام من معدل هذه الإشعارات، كما تتطلب وضع الخلفية Remote notifications.

// Silent payload — no alert, just a wake-up:
// { "aps": { "content-available": 1 }, "sync": true }
let silent = "content-available wakes app quietly"
_ = silent

معالج الجلب في الخلفية

يصل إشعار push الصامت إلى طريقة didReceiveRemoteNotification غير المتزامنة في مفوض التطبيق. تنفذون عملية الجلب ثم تعيدون قيمة من النوع UIBackgroundFetchResult، ليعرف النظام ما إذا وصلت بيانات جديدة ويتمكن من ضبط عمليات الإيقاظ المستقبلية.

import UIKit
func application(
    _ app: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    // fetch fresh data here
    return .newData
}

المحتوى القابل للتعديل وامتدادات الخدمة

باستخدام mutable-content: 1، يمكن لـ Notification Service Extension اعتراض إشعار push قبل عرضه، لفك تشفير النص أو تنزيل مرفق صورة أو إعادة كتابة العنوان. ولا يملك الامتداد سوى مهلة قصيرة لإنهاء عمله.

// Service extension entry point (UNNotificationServiceExtension):
// override didReceive(_:withContentHandler:)
//   modify bestAttemptContent, then call contentHandler
let mutable = "mutable-content enables interception"
_ = mutable

توطين التنبيه

لتوطين النص من جهة الخادم، أرسلوا title-loc-key وloc-key اللذين يشيران إلى مفاتيح في سلاسل Localizable الخاصة بتطبيقكم، بالإضافة إلى loc-args لقيم الاستبدال. يعرض الجهاز النص بلغة المستخدم من دون الحاجة إلى إرسال نص مترجم مسبقًا.

// Localized alert payload:
// "alert": {
//   "loc-key": "NEW_MESSAGE",
//   "loc-args": ["Ada"]
// }
let localized = "loc-key resolves on device"
_ = localized

تحديث الشارة

تحدد قيمة badge الرقم الظاهر على أيقونة التطبيق. ويؤدي إرسال badge: 0 إلى مسحه. يمكنكم أيضًا ضبطه في الشيفرة عبر setBadgeCount بعد أن يقرأ المستخدم المحتوى، للحفاظ على توافق الشارة مع حالة العناصر غير المقروءة.

import UserNotifications
func clearBadge() async {
    try? await UNUserNotificationCenter.current()
        .setBadgeCount(0)
}

معالج متين

اجمعوا هذه الأجزاء: اعرضوا الإشعار في المقدمة، ووجّهوا المستخدم عند النقر، وتحققوا من كل عملية تحويل نوع. يجب ألا يتعطل المعالج بسبب حمولة غير متوقعة، وأن يستخرج دائمًا كل ما يستطيع استخراجه.

import UserNotifications
func handleTap(_ response: UNNotificationResponse) {
    let info = response.notification.request
        .content.userInfo
    guard let id = info["itemId"] as? String else {
        print("no item id; open home")
        return
    }
    print("navigate to item", id)
}

اختبار سريع

تذكّروا كيفية الاستجابة للنقر على إشعار.

مراجعة

لقد تعلمتم كيفية التعامل مع الحمولات:

يحتوي قاموس aps على المحتوى الظاهر للمستخدم، بينما تحتوي المفاتيح الأخرى على بياناتكم التي تُقرأ عبر userInfo.
تجاوزوا willPresent لعرض الإشعارات أثناء وجود التطبيق في المقدمة، وdidReceive response للتعامل مع النقرات.
تؤدي content-available: 1 إلى عمليات جلب صامتة في الخلفية تعيد قيمة من النوع UIBackgroundFetchResult.
يتيح mutable-content استخدام امتداد خدمة، بينما يوطّن loc-key النص على الجهاز.

الأسئلة الشائعة

هل درس «التعامل مع حمولات الإشعارات» مجاني؟

نعم — نص درس «التعامل مع حمولات الإشعارات» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Swift Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Swift Academy 4 دروس في المجموع.

ماذا ستتعلم في «التعامل مع حمولات الإشعارات»؟

استجب للإشعارات في المقدمة والخلفية. تتمرن على Swift Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Swift Academy؟

لا تُشترط خبرة سابقة. Swift Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «التعامل مع حمولات الإشعارات»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Swift Academy هذا؟

نعم. كل درس في Swift Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Swift Academy