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

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

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

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

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

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

    • ‫Xcode 16.2 أو إصدار أحدث

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

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

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

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

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

إنشاء مشروع Firebase

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Swift

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()

AppDelegate.swift

Objective-C

[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 عند بدء تشغيل التطبيق، توفّر خدمة FCM رمز تسجيل من خلال طريقة FIRMessagingDelegatemessaging:didReceiveRegistrationToken:. تستردّ حزمة تطوير البرامج (SDK) الخاصة بميزة "المراسلة عبر السحابة الإلكترونية من Firebase" رمزًا مميزًا جديدًا أو حاليًا أثناء تشغيل التطبيق الأوّلي وكلما تم تعديل الرمز المميز أو إبطاله. في جميع الحالات، يستدعي حزمة تطوير البرامج (SDK) لخدمة FCM الدالة messaging:didReceiveRegistrationToken: مع رمز مميّز صالح.

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

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

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

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

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

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

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

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

AppDelegate.swift

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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