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

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

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

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

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

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

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

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

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

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

إذا لم يكن لديك مشروع 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 Apple (GoogleService-Info.plist).

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

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

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

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

  1. في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى File > Add Packages (ملف > إضافة حِزم).
  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) لمنصّة Firebase الخاصة بخدمة "إحصاءات Google" إلى تطبيقك. يمكنك اختيار المكتبة التي لا تتضمّن جمع معرّف المعلِنين (IDFA) أو من خلال جمع معرّف المعلِنين (IDFA).
  6. عند الانتهاء، سيبدأ Xcode تلقائيًا في حلّ ملفاتك المضمّنة وتنزيلها في الخلفية.

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

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

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

  2. في مفتاح مصادقة APNs ضمن إعدادات تطبيق iOS، انقر على الزر تحميل .

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

إعداد 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()

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 عادةً رمزًا مميّزًا للأجهزة الخاصة بأسماء نقاط الوصول (APN) عند بدء تشغيل التطبيق، توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" رمزًا مميّزًا للتسجيل من خلال طريقة messaging:didReceiveRegistrationToken: في FIRMessagingDelegate. تسترجع حزمة تطوير البرامج (SDK) لميزة "المراسلة عبر السحابة الإلكترونية من Firebase" رمزًا مميّزًا جديدًا أو حاليًا أثناء التشغيل الأولي للتطبيق وكلما تم تعديل الرمز المميّز أو إبطاله. في جميع الحالات، تستدعي حزمة تطوير البرامج (SDK) لنظام "إرسال الرسائل الفورية من Google" 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. في الحقل المُسمَّى إضافة الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، أدخِل الرمز المميّز للتسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.

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

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

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

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

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