إرسال رسالة اختبار إلى تطبيق Apple يعمل في الخلفية

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

إضافة Firebase إلى مشروع Apple

يتناول هذا القسم المهام التي قد تكون أكملتها إذا سبق لك تفعيلها. ميزات Firebase الأخرى لتطبيقك. بالنسبة إلى FCM على وجه التحديد، عليك بحاجة إلى تحميل مفتاح مصادقة أسماء نقاط الوصول (APN) و التسجيل لتلقي الإشعارات عن بُعد.

المتطلبات الأساسية

  • ثبِّت ما يلي:

    • Xcode 15.2 أو إصدار أحدث
  • تأكد من أن مشروعك يلبي هذه المتطلبات:

    • يجب أن يستهدف مشروعك إصدارات النظام الأساسي التالية أو الإصدارات الأحدث:
      • الإصدار 13 من نظام التشغيل iOS
      • الإصدار 10.15 من نظام التشغيل macOS
      • نظام التشغيل tvOS 13
      • ساعة تعمل بنظام التشغيل WatchOS 7
  • إعداد جهاز Apple مادي لتشغيل تطبيقك وإكمال هذه المهام:

    • احصل على مفتاح مصادقة الإشعارات الفورية من Apple من أجل حساب مطوّر برامج Apple:
    • تفعيل الإشعارات الفورية في XCode ضمن التطبيق > الإمكانات.

إذا لم يكن لديك مشروع Xcode من قبل وأردت فقط تجربة Firebase يمكنك تنزيل أحد نماذج البدء السريع لدينا.

إنشاء مشروع على Firebase

عليك إنشاء منصّة Firebase لتتمكّن من إضافة منصة Firebase إلى تطبيق Apple. مشروعك لربطه بتطبيقك. زيارة الموقع يمكنك فهم مشاريع Firebase للحصول على مزيد من المعلومات حول. مشاريع Firebase:

تسجيل تطبيقك في Firebase

لاستخدام Firebase في تطبيق Apple، يجب تسجيل تطبيقك في مشروع على Firebase. وعادةً ما يُطلق على تسجيل تطبيقك اسم "الإضافة". تطبيقك إلى مشروعك.

  1. انتقِل إلى وحدة تحكُّم Firebase.

  2. في منتصف صفحة النظرة العامة على المشروع، انقر على رمز +iOS لبدء عملية الإعداد

    إذا سبق لك إضافة تطبيق إلى مشروعك على Firebase، انقر على إضافة تطبيق. لعرض خيارات النظام الأساسي.

  3. أدخِل معرّف حزمة التطبيق في الحقل معرّف الحزمة.

  4. (اختياري) أدخِل معلومات أخرى عن التطبيق: اسم التطبيق ورقم تعريف متجر التطبيقات.

  5. انقر على تسجيل التطبيق.

إضافة ملف إعداد Firebase

  1. انقر على تنزيل GoogleService-Info.plist للحصول على جهاز Firebase Apple. ملف إعداد الأنظمة الأساسية (GoogleService-Info.plist).

  2. انقل ملف التكوين إلى جذر مشروع Xcode. إذا طُلب منك ذلك، حدد هذا الخيار لإضافة ملف الإعداد إلى جميع الأهداف.

إذا كان لديك معرّفات حِزم متعددة في مشروعك، عليك ربط كل حزمة. رقم تعريف من خلال تطبيق مسجَّل في وحدة تحكُّم "Firebase" حتى يمكن لكل تطبيق ملف GoogleService-Info.plist الخاص به.

إضافة حِزم تطوير البرامج (SDK) لمنصة Firebase إلى تطبيقك

يمكنك استخدام "مدير حزم Swift" لتثبيت اعتماديات Firebase وإدارتها.

  1. في Xcode، انتقِل إلى File (ملف) > بعد فتح مشروع التطبيق الخاص بك. إضافة حِزم
  2. أضِف مستودع حزمة تطوير البرامج (SDK) لمنصّات Firebase Apple عندما يُطلب منك ذلك:
  3.   https://github.com/firebase/firebase-ios-sdk.git
  4. اختَر مكتبة "Firebase Cloud Messaging".
  5. أضِف العلامة -ObjC إلى القسم علامات الروابط الأخرى في إعدادات إصدار هدفك.
  6. للحصول على تجربة مثالية مع Firebase Cloud Messaging، ننصح تفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصة بخدمة "إحصاءات Google" إلى تطبيقك. يمكنك اختيار إما المكتبة التي لا تتضمن جمع معرّف المعلِنين (IDFA) أو من خلال جمع معرّف المعلِنين (IDFA).
  7. عند الانتهاء، سيبدأ Xcode تلقائيًا في حل وتنزيل ملف والتبعيات في الخلفية.

تحميل مفتاح مصادقة أسماء نقاط الوصول (APN)

حمِّل مفتاح مصادقة أسماء نقاط الوصول إلى Firebase. إذا لم يكن لديك مفتاح مصادقة لأسماء نقاط الوصول (APN)، احرص على إنشاء مفتاح في مركز أعضاء مطوّري برامج Apple

  1. داخل مشروعك في وحدة تحكّم "Firebase"، اختَر رمز الترس، اختَر إعدادات المشروع، ثم حدد المراسلة عبر السحابة الإلكترونية.

  2. في مفتاح مصادقة أسماء نقاط الوصول (APN) ضمن ضبط تطبيق iOS، انقر على تحميل .

  3. تصفح المكان الذي حفظت فيه مفتاحك، وحدده، ثم انقر انقر على فتح. أضِف معرّف المفتاح للمفتاح (المتوفّر في Apple Developer Member Center) وانقر على تحميل:

إعداد Firebase في تطبيقك

سيتعيّن عليك إضافة رمز إعداد Firebase إلى تطبيقك. استيراد وحدة Firebase وإعداد مثيل مشترك كما هو موضح:

  1. استيراد وحدة FirebaseCore في UIApplicationDelegate بالإضافة إلى أي تطبيق آخر وحدات Firebase التي يستخدمها تطبيقك المفوَّض على سبيل المثال، لاستخدام Cloud Firestore وAuthentication:

    SwiftUI

    import SwiftUI
    import FirebaseCore
    import FirebaseFirestore
    import FirebaseAuth
    // ...
          

    Swift

    import FirebaseCore
    import FirebaseFirestore
    import FirebaseAuth
    // ...
          

    Objective-C

    @import FirebaseCore;
    @import FirebaseFirestore;
    @import FirebaseAuth;
    // ...
          
  2. ضبط FirebaseApp المثيل المشترك في حساب مفوَّض تطبيقك طريقة application(_:didFinishLaunchingWithOptions:):

    SwiftUI

    // Use Firebase library to configure APIs
    FirebaseApp.configure()

    Swift

    // Use Firebase library to configure APIs
    FirebaseApp.configure()

    Objective-C

    // Use Firebase library to configure APIs
    [FIRApp configure];
  3. إذا كنت تستخدم SwiftUI، عليك إنشاء تفويض تطبيق وإرفاقه. إلى بنية App عبر UIApplicationDelegateAdaptor أو NSApplicationDelegateAdaptor ويجب أيضًا إيقاف إيماءة تفويض التطبيق. بالنسبة لمزيد من المعلومات، يُرجى الاطّلاع على تعليمات SwiftUI.

    SwiftUI

    @main
    struct YourApp: App {
      // register app delegate for Firebase setup
      @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
    
      var body: some Scene {
        WindowGroup {
          NavigationView {
            ContentView()
          }
        }
      }
    }
          

التسجيل لتلقّي الإشعارات عن بُعد

سواء عند بدء التشغيل أو في المرحلة المطلوبة من عملية تقديم الطلب تسجيل التطبيق لتلقّي الإشعارات عن بُعد اتصل registerForRemoteNotifications كما هو موضّح:

Swift

UNUserNotificationCenter.current().delegate = self

let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(
  options: authOptions,
  completionHandler: { _, _ in }
)

application.registerForRemoteNotifications()

Objective-C

[UNUserNotificationCenter currentNotificationCenter].delegate = self;
UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
    UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
[[UNUserNotificationCenter currentNotificationCenter]
    requestAuthorizationWithOptions:authOptions
    completionHandler:^(BOOL granted, NSError * _Nullable error) {
      // ...
    }];

[application registerForRemoteNotifications];

الوصول إلى الرمز المميّز للتسجيل

لإرسال رسالة إلى جهاز محدد، يجب معرفة الرمز المميز للتسجيل. ولأنّك ستحتاج إلى إدخال الرمز المميّز في حقل في مؤلف الإشعارات لإكمال هذا الدليل التوجيهي، احرص على نسخ الرمز المميّز. أو تخزينها بشكل آمن بعد استرجاعها.

تُنشئ حزمة تطوير البرامج (SDK) "FCM" تلقائيًا الرمز المميز للتسجيل لمثيل تطبيق العميل عند تشغيل التطبيق. على غرار الرمز المميّز للجهاز الخاص بأسماء نقاط الوصول (APN)، يسمح لك هذا الرمز المميّز بإرسال إشعارات موجَّهة. على أي مثيل محدد من تطبيقك.

بالطريقة نفسها التي تقدم بها منصات Apple عادةً رمزًا مميزًا لأجهزة أسماء نقاط الوصول (APN) عند بدء التطبيق، توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" رمزًا مميّزًا للتسجيل عبر FIRMessagingDelegate طريقة messaging:didReceiveRegistrationToken:. تسترد حزمة تطوير البرامج لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" رمزًا مميزًا جديدًا أو موجودًا أثناء التشغيل الأولي للتطبيق كلما تم تعديل الرمز المميّز أو إبطاله. في جميع الحالات، تطلب حزمة تطوير البرامج (SDK) لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" messaging:didReceiveRegistrationToken: باستخدام رمز مميّز صالح.

قد يتغيّر الرمز المميّز للتسجيل في الحالات التالية:

  • تتم استعادة التطبيق على جهاز جديد.
  • يلغي المستخدم تثبيت التطبيق أو يعيد تثبيته
  • يمحو المستخدم بيانات التطبيق.

إعداد تفويض المراسلة

لتلقّي رموز التسجيل المميَّزة، يجب تنفيذ تفويض المراسلة. وضبط السمة delegate في FIRMessaging بعد الاتصال [FIRApp configure] على سبيل المثال، إذا كان تفويض تطبيقك متوافقًا مع المفوَّض بالمراسلة يمكنك ضبط المفوَّض على application:didFinishLaunchingWithOptions: إلى نفسه.

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

جارٍ استرجاع الرمز المميّز للتسجيل الحالي

يتم تسليم الرموز المميّزة للتسجيل من خلال الطريقة messaging:didReceiveRegistrationToken: يتم استدعاء هذه الطريقة بشكل عام مرة واحدة لكل التطبيق بالرمز المميز للتسجيل. عند استدعاء هذه الطريقة، فهذا هو الوقت المثالي لإجراء ما يلي:

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

يمكنك استرداد الرمز المميّز مباشرةً باستخدام الرمز المميّز(الإكمال:) يظهر خطأ "خالٍ" إذا فشل استرداد الرمز المميز بأي شكل من الأشكال.

Swift

Messaging.messaging().token { token, error in
  if let error = error {
    print("Error fetching FCM registration token: \(error)")
  } else if let token = token {
    print("FCM registration token: \(token)")
    self.fcmRegTokenMessage.text  = "Remote FCM registration token: \(token)"
  }
}

Objective-C

[[FIRMessaging messaging] tokenWithCompletion:^(NSString *token, NSError *error) {
  if (error != nil) {
    NSLog(@"Error getting FCM registration token: %@", error);
  } else {
    NSLog(@"FCM registration token: %@", token);
    self.fcmRegTokenMessage.text = token;
  }
}];

يمكنك استخدام هذه الطريقة في أي وقت للوصول إلى الرمز المميّز بدلاً من تخزين بها.

مراقبة إعادة تحميل الرمز المميّز

ليتم إعلامك عندما يتم تحديث الرمز المميز، قدّم مفوّضًا متوافقًا إلى بروتوكول تفويض الرسائل. يسجل المثال التالي المفوَّض ويضيف طريقة التفويض المناسبة:

Swift

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")

  let dataDict: [String: String] = ["token": fcmToken ?? ""]
  NotificationCenter.default.post(
    name: Notification.Name("FCMToken"),
    object: nil,
    userInfo: dataDict
  )
  // TODO: If necessary send token to application server.
  // Note: This callback is fired at each app startup and whenever a new token is generated.
}

Objective-C

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistrationToken:(NSString *)fcmToken {
    NSLog(@"FCM registration token: %@", fcmToken);
    // Notify about received token.
    NSDictionary *dataDict = [NSDictionary dictionaryWithObject:fcmToken forKey:@"token"];
    [[NSNotificationCenter defaultCenter] postNotificationName:
     @"FCMToken" object:nil userInfo:dataDict];
    // TODO: If necessary send token to application server.
    // Note: This callback is fired at each app startup and whenever a new token is generated.
}

ويمكنك بدلاً من ذلك الاستماع إلى صوت NSNotification باسم. kFIRMessagingRegistrationTokenRefreshNotification بدلاً من توفير طريقة تفويض. تحتوي خاصية الرمز المميز دائمًا على قيمة الرمز المميز الحالي.

إرسال رسالة إشعار

  1. ثبِّت التطبيق وشغِّله على الجهاز المستهدَف. على أجهزة Apple، ستحتاج إلى على قبول طلب الحصول على إذن بتلقي الإشعارات عن بُعد.

  2. تأكَّد من تشغيل التطبيق في الخلفية على الجهاز.

  3. في وحدة تحكُّم Firebase، افتح صفحة "المراسلة".

  4. إذا كانت هذه هي رسالتك الأولى، فحدد إنشاء رسالتك الأولى حملة.

    1. اختَر رسائل إشعارات Firebase ثم اختَر إنشاء.
  5. إذا لم يكن الأمر كذلك، اختَر حملة جديدة من علامة التبويب الحملات. ثم الإشعارات.

  6. أدخِل نص الرسالة. وجميع الحقول الأخرى اختيارية.

  7. اختَر إرسال رسالة اختبار من اللوحة على يسار الصفحة.

  8. في الحقل الذي يحمل عبارة إضافة الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، أدخِل معلومات التسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.

  9. اختَر اختبار.

بعد اختيار اختبار، جهاز العميل المستهدف (الذي يتضمن التطبيق في الخلفية) الإشعار.

للحصول على إحصاءات بشأن تسليم الرسائل إلى تطبيقك، راجِع FCM لوحة بيانات إعداد التقارير، التي تسجّل عدد الرسائل المرسَلة وفتحها على أجهزة Apple وAndroid، إلى جانب بيانات "مرات الظهور" (الإشعارات التي اطّلع عليها المستخدمون) لتطبيقات Android.

الخطوات التالية

لتجاوز رسائل الإشعارات وإضافة سلوكيات أخرى أكثر تقدمًا إلى يمكنك الاطّلاع على: