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

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

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

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

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

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

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

  • تأكد من أن مشروعك يلبي هذه المتطلبات:

    • يجب أن يستهدف مشروعك إصدارات النظام الأساسي التالية أو الإصدارات الأحدث:
      • الإصدار 11 من نظام التشغيل iOS
      • الإصدار 10.13 من نظام التشغيل macOS
      • نظام التشغيل tvOS 12
      • ساعة تعمل بنظام التشغيل WatchOS 6

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

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

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

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

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

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

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

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

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

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

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

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

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

    واجهة المستخدم

    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:) الخاصة بمفوَّض تطبيقك:

    واجهة المستخدم

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

    واجهة المستخدم

    @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) لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تلقائيًا رمزًا مميّزًا للتسجيل لمثيل تطبيق العميل عند تشغيل التطبيق. وكما هو الحال مع الرمز المميز للجهاز لأسماء نقاط الوصول (APNs)، يتيح لك هذا الرمز المميز إرسال إشعارات مستهدفة إلى أي مثيل محدد من تطبيقك.

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

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

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

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

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

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

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

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

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. اختَر اختبار.

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

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

الخطوات اللاحقة

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