إرسال رسائل إلى أجهزة متعددة على أنظمة Apple الأساسية

لاستهداف رسالة على أجهزة متعددة، استخدِم الرسائل المخصّصة للمواضيع. تتيح لك هذه الميزة إرسال رسالة إلى أجهزة متعددة فعّلت موضوعًا معيّنًا.

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

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

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

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

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

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

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

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

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

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

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

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

  1. في وحدة تحكّم Firebase، انقر على إضافة مشروع.

    • لإضافة موارد Firebase إلى مشروع حالي على Google Cloud ، أدخِل اسم المشروع أو اختَره من القائمة المنسدلة.

    • لإنشاء مشروع جديد، أدخِل اسمًا للمشروع. يمكنك أيضًا تعديل رقم تعريف المشروع المعروض أسفل اسم المشروع بشكل اختياري.

  2. راجِع بنود Firebase واقبلها في حال طُلب منك ذلك.

  3. انقر على متابعة.

  4. (اختياري) إعداد Google Analytics لمشروعك، ما يؤدي إلى توفير تجربة مثالية باستخدام منتجات Firebase التالية: Firebase A/B Testing، Cloud Messaging، Crashlytics، In-App Messaging، Remote Config (بما في ذلك التخصيص).

    اختَر إما حساب Google Analytics حاليًا أو أنشئ حسابًا جديدًا. إذا أنشأت حسابًا جديدًا، اختَر Analytics الموقع الجغرافي لإعداد التقارير، ثم وافِق على إعدادات مشاركة البيانات وبنود Google Analytics لمشروعك.

  5. انقر على إنشاء مشروع (أو إضافة Firebase، إذا كنت بصدد إضافة Firebase إلى مشروع Google Cloud حالي).

توفّر Firebase الموارد تلقائيًا لمشروعك على Firebase. عند اكتمال العملية، سيتم نقلك إلى صفحة النظرة العامة لمشروع Firebase في وحدة تحكّم Firebase.

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

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

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

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

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

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

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

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

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

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

  4. (اختياري) أدخِل معلومات التطبيق الأخرى: الاسم المعرِّف للتطبيق ورقم تعريف التطبيق في 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 عندما يُطلب منك ذلك:
    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" إلى تطبيقك. ويمكنك اختيار المكتبة بدون جمع معرّف جهاز 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:
    SwiftUISwiftObjective-C 
    import SwiftUI
import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...
      
    import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...
      
    @import FirebaseCore;
@import FirebaseFirestore;
@import FirebaseAuth;
// ...
  2. يمكنك ضبط مثيل مشترَك لملف FirebaseApp في طريقة application(_:didFinishLaunchingWithOptions:) لمفوّض التطبيق باتّباع الخطوات التالية:
    SwiftUISwiftObjective-C 
    // Use Firebase library to configure APIs
FirebaseApp.configure()
     
    // Use Firebase library to configure APIs
FirebaseApp.configure()
     
    // 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 كما هو موضّح:
SwiftObjective-C 
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

اشتراك تطبيق العميل في موضوع

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

للاشتراك في موضوع، يمكنك استدعاء طريقة الاشتراك من سلسلة المهام الرئيسية لتطبيقك (FCM غير آمن في سلسلة المهام). إذا تعذّر طلب الاشتراك في البداية، يعيد FCM المحاولة تلقائيًا. في الحالات التي يتعذّر فيها إكمال الاشتراك، يُرسِل الاشتراك خطأً يمكنك رصده في معالج الإكمال كما هو موضّح:

SwiftObjective-C 
Messaging.messaging().subscribe(toTopic: "weather") { error in
  print("Subscribed to weather topic")
}
ViewController.swift
 
[[FIRMessaging messaging] subscribeToTopic:@"weather"
                                completion:^(NSError * _Nullable error) {
  NSLog(@"Subscribed to weather topic");
}];
ViewController.m

تُجري هذه الدعوة طلبًا غير متزامن إلى الخلفية في FCM وتشترك العميل في الموضوع المحدَّد. قبل استدعاء subscribeToTopic:topic، تأكَّد من أنّه سبق أن تلقّت مثيل تطبيق العميل رمز تنشيط التسجيل من خلال callback didReceiveRegistrationToken.

في كل مرة يتم فيها تشغيل التطبيق، تأكّد FCM من أنّه تم الاشتراك في جميع المواضيع المطلوبة. لإلغاء الاشتراك، اتصل بالرقم unsubscribeFromTopic:topic، وسيؤدي ذلك إلى إلغاء الاشتراك في الموضوع في الخلفية.FCM

تلقّي رسائل المواضيع ومعالجتها

تُرسِل FCM رسائل المواضيع بالطريقة نفسها التي تُرسِل بها رسائل الأخرى.

نفِّذ application(_:didReceiveRemoteNotification:fetchCompletionHandler:) على النحو الموضّح:

SwiftObjective-C 
func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async
  -> UIBackgroundFetchResult {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired till the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // Messaging.messaging().appDidReceiveMessage(userInfo)

  // Print message ID.
  if let messageID = userInfo[gcmMessageIDKey] {
    print("Message ID: \(messageID)")
  }

  // Print full message.
  print(userInfo)

  return UIBackgroundFetchResult.newData
}

AppDelegate.swift
 
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired till the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // [[FIRMessaging messaging] appDidReceiveMessage:userInfo];

  // ...

  // Print full message.
  NSLog(@"%@", userInfo);

  completionHandler(UIBackgroundFetchResultNewData);
}
AppDelegate.m

إنشاء طلبات الإرسال

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

في منطق الإرسال في الخلفية، حدِّد اسم الموضوع المطلوب كما هو موضّح:

Node.jsJavaPythonGo#CREST 
// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java


# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py


// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go


// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

أمر cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

لإرسال رسالة إلى مجموعة من المواضيع، حدِّد شرطًا، وهو تعبير منطقي يحدِّد topics المستهدفة. على سبيل المثال، سيؤدي الشرط التالي إلى إرسال الرسائل إلى الأجهزة التي اشتركت في TopicA وTopicB أو TopicC:

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

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

  • TopicA وTopicB
  • TopicA وTopicC

يمكنك تضمين ما يصل إلى خمس مواضيع في تعبيرك الشَرطي.

للإرسال إلى شرط:

Node.jsJavaPythonGo#CREST 
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java


# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py


// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go


// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

أمر cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

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