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

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

إضافة Firebase إلى مشروع Apple الخاص بك

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

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

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

  • الإصدار 15.2 من Xcode أو إصدار أحدث

• تأكَّد من أنّ مشروعك يستوفي المتطلبات التالية:

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

• عليك إعداد جهاز Apple لتشغيل تطبيقك، وإكمال المهام التالية:

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

• سجِّل الدخول إلى Firebase باستخدام حسابك على Google.

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

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

قبل أن تتمكّن من إضافة Firebase إلى تطبيقك على Apple، عليك إنشاء مشروع على Firebase لربطه بتطبيقك. يُرجى الانتقال إلى مقالة فهم مشاريع Firebase لمعرفة مزيد من المعلومات عن مشاريع Firebase.

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

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

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

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

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

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

   ما هو معرّف الحزمة، وأين يمكن العثور عليه؟

   • يحدِّد معرّف الحزمة التطبيق بشكلٍ فريد في منظومة Apple المتكاملة.

   • العثور على معرّف الحزمة: افتح مشروعك في Xcode، واختَر التطبيق من المستوى الأعلى في نافذة التنقّل في المشروع، ثم اختَر علامة التبويب عام.

     قيمة حقل معرّف الحزمة هي معرّف الحزمة (على سبيل المثال، com.yourcompany.yourproject).

   • يُرجى العِلم أنّ قيمة معرّف الحِزمة حسّاسة لحالة الأحرف، ولا يمكن تغييرها لتطبيق Firebase هذا بعد تسجيله في مشروع Firebase.

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

   كيف يتم استخدام الاسم المعرِّف للتطبيق ورقم تعريف متجر التطبيقات في Firebase؟

   • الاسم المعرِّف للتطبيق: معرّف داخلي لتسهيل الاستخدام لا يظهر إلا لك في وحدة تحكّم Firebase

   • رقم تعريف متجر التطبيقات: يستخدمه Firebase Dynamic Links لإعادة توجيه المستخدمين إلى صفحة تطبيقك على App Store ويستخدمه Google Analytics لاستيراد أحداث الإحالات الناجحة إلى Google Ads. إذا لم يكن تطبيقك يتضمّن رقم تعريف على App Store، يمكنك إضافة رقم التعريف لاحقًا في إعدادات المشروع.

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

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

1. انقر على تنزيل GoogleService-Info.plist للحصول على ملف إعدادات منصّات Apple في Firebase (GoogleService-Info.plist).

   ما الذي يجب معرفته عن ملف الإعدادات هذا؟

   • يحتوي ملف إعدادات Firebase على معرّفات فريدة، ولكنها غير سرية لمشروعك. لمعرفة المزيد من المعلومات عن ملف الإعدادات هذا، يُرجى الانتقال إلى مقالة فهم مشاريع Firebase.

   • يمكنك تنزيل ملف إعداد Firebase مجددًا في أي وقت.

   • تأكَّد من عدم إلحاق اسم ملف الإعدادات بأحرف إضافية، مثل (2).

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

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

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

استخدِم أداة Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.

1. في Xcode، مع فتح مشروع تطبيقك، انتقِل إلى ملف > إضافة حِزم.
2. أضِف مستودع حزمة تطوير البرامج (SDK) لمنصّات Apple من Firebase عندما يُطلب منك ذلك:

  https://github.com/firebase/firebase-ios-sdk.git

3. اختَر مكتبة Firebase Cloud Messaging.
4. أضِف العلامة -ObjC إلى قسم رموز ربط أخرى في إعدادات الإنشاء الخاصة بالهدف.
5. للحصول على تجربة مثالية مع Firebase Cloud Messaging، ننصحك بتفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase في "إحصاءات Google" إلى تطبيقك. ويمكنك اختيار المكتبة بدون جمع معرّف جهاز IDFA أو مع جمع معرّف جهاز IDFA.
6. عند الانتهاء، سيبدأ Xcode تلقائيًا في حلّ ملفاتك المضمّنة وتنزيلها في الخلفية.

تحميل مفتاح مصادقة APNs

حمِّل مفتاح مصادقة APNs إلى Firebase. إذا لم يكن لديك مفتاح مصادقة APNs، احرص على إنشاء مفتاح في Apple Developer Member Center.

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

2. في مفتاح مصادقة APNs ضمن إعدادات تطبيق 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()
         }
       }
     }
   }
         

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

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
AppDelegate.swift

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

[application registerForRemoteNotifications];
AppDelegate.m

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

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

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

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

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

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

ضبط حساب المفوّض للمراسلة

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

جلب الرمز المميّز الحالي للتسجيل

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

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

يمكنك استرداد الرمز المميّز مباشرةً باستخدام token(completion:). يتم تقديم خطأ غير صفري إذا تعذّر استرداد الرمز المميّز بأي شكل من الأشكال.

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)"
  }
}

[[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;
  }
}];

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

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

لتلقّي إشعارات عند تعديل الرمز المميّز، يجب تقديم مفوّض يتوافق مع بروتوكول مفوّض المراسلة. يسجِّل المثال التالي الوكيل ويضيف طريقة الوكيل المناسبة:

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.
}
AppDelegate.swift

- (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.
}
AppDelegate.m

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

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

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

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

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

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

   1. اختَر رسائل إشعارات Firebase ثمّ إنشاء.

5. بخلاف ذلك، في علامة التبويب الحملات، اختَر حملة جديدة ثم الإشعارات.

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

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

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

9. انقر على اختبار.

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

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

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

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

• تلقّي الرسائل في تطبيق عميل Apple
• إرسال الرسائل إلى أجهزة متعددة