لاستهداف رسالة على أجهزة متعددة، استخدِم رسائل المواضيع. تتيح لك هذه الميزة إرسال رسالة إلى أجهزة متعددة تم تفعيلها لموضوع معيّن.
تركّز هذه المقالة التعليمية على إرسال رسائل المواضيع من خادم تطبيقك باستخدام Admin SDK أو واجهة برمجة التطبيقات REST API لنظام التشغيل FCM، وتلقّيها ومعالجتها في تطبيق Apple. وتسرد هذه الصفحة جميع الخطوات اللازمة لتحقيق ذلك، بدءًا من الإعداد وحتى التحقّق، لذا قد تتضمّن الخطوات التي سبق لك إكمالها إذا سبق لك إعداد تطبيق عميل 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. غالبًا ما يُشار إلى عملية تسجيل تطبيقك باسم "إضافة" تطبيقك إلى مشروعك.
انتقِل إلى وحدة تحكّم Firebase.
في وسط صفحة النظرة العامة على المشروع، انقر على رمز iOS+ لبدء سير عمل الإعداد.
إذا سبق لك إضافة تطبيق إلى مشروعك على Firebase، انقر على إضافة تطبيق لعرض خيارات المنصة.
أدخِل معرّف حزمة تطبيقك في حقل معرّف الحزمة.
(اختياري) أدخِل معلومات التطبيق الأخرى: الاسم المعرِّف للتطبيق ورقم تعريف التطبيق على App Store.
انقر على تسجيل التطبيق.
إضافة ملف إعدادات Firebase
انقر على تنزيل GoogleService-Info.plist للحصول على ملف إعدادات منصّات Apple في Firebase (
GoogleService-Info.plist
).انقل ملف الإعداد إلى جذر مشروع Xcode. إذا طُلب منك ذلك، اختَر إضافة ملف الإعدادات إلى جميع الاستهدافات.
إذا كان لديك أرقام تعريف حِزم متعددة في مشروعك، عليك ربط كل رقم تعريف
حزمة بتطبيق مسجَّل في وحدة تحكّم Firebase حتى يتمكّن كل تطبيق من استخدام
ملف GoogleService-Info.plist
الخاص به.
إضافة حِزم تطوير البرامج (SDK) لمنصّة Firebase إلى تطبيقك
استخدِم أداة Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.
- في Xcode، مع فتح مشروع تطبيقك، انتقِل إلى ملف > إضافة حِزم.
- أضِف مستودع حزمة تطوير البرامج (SDK) لمنصّات Apple من Firebase عندما يُطلب منك ذلك:
- اختَر مكتبة Firebase Cloud Messaging.
- أضِف العلامة
-ObjC
إلى قسم رموز ربط أخرى في إعدادات الإنشاء الخاصة بالهدف. - للحصول على تجربة مثالية مع Firebase Cloud Messaging، ننصحك بتفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase في "إحصاءات Google" إلى تطبيقك. ويمكنك اختيار المكتبة بدون جمع معرّف جهاز IDFA أو مع جمع معرّف جهاز IDFA.
- عند الانتهاء، سيبدأ Xcode تلقائيًا في حلّ ملفاتك المضمّنة وتنزيلها في الخلفية.
https://github.com/firebase/firebase-ios-sdk.git
تحميل مفتاح مصادقة APNs
حمِّل مفتاح مصادقة APNs إلى Firebase. إذا لم يكن لديك مفتاح مصادقة APNs، احرص على إنشاء مفتاح في Apple Developer Member Center.
-
داخل مشروعك في وحدة تحكّم Firebase، انقر على رمز الترس، ثم على إعدادات المشروع، ثم على علامة التبويب الرسائل عبر السحابة الإلكترونية.
-
في مفتاح مصادقة APNs ضمن إعدادات تطبيق iOS، انقر على الزر تحميل.
-
انتقِل إلى المكان الذي حفظت فيه مفتاحك، واختَره، ثم انقر على فتح. أضِف معرّف المفتاح (متاحًا في Apple Developer Member Center) وانقر على تحميل.
إعداد Firebase في تطبيقك
عليك إضافة رمز إعداد Firebase إلى تطبيقك. استورِد وحدة Firebase وضبط مثيل مشترَك كما هو موضّح:
- استورِد وحدة
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; // ...
- يمكنك ضبط مثيل مشترَك لملف
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];
- إذا كنت تستخدم 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()
Objective-C
[UNUserNotificationCenter currentNotificationCenter].delegate = self; UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge; [[UNUserNotificationCenter currentNotificationCenter] requestAuthorizationWithOptions:authOptions completionHandler:^(BOOL granted, NSError * _Nullable error) { // ... }]; [application registerForRemoteNotifications];
اشتراك تطبيق العميل في موضوع
يمكن للتطبيقات التابعة للعملاء الاشتراك في أي موضوع حالي، أو يمكنها إنشاء موضوع جديد. عندما يشترك تطبيق العميل في اسم موضوع جديد (موضوع لم يكن متوفّرًا في مشروعك على Firebase)، يتم إنشاء موضوع جديد يحمل هذا الاسم في FCM ويمكن لأي عميل الاشتراك فيه لاحقًا.
للاشتراك في موضوع، يمكنك استدعاء طريقة الاشتراك من سلسلة المهام الرئيسية لتطبيقك (FCM غير آمن في سلسلة المهام). إذا تعذّر إتمام طلب الاشتراك في البداية، يعيد FCM المحاولة تلقائيًا. في الحالات التي يتعذّر فيها إكمال الاشتراك، يُرسِل الاشتراك خطأً يمكنك رصده في معالج الإكمال كما هو موضّح:
Swift
Messaging.messaging().subscribe(toTopic: "weather") { error in print("Subscribed to weather topic") }
Objective-C
[[FIRMessaging messaging] subscribeToTopic:@"weather" completion:^(NSError * _Nullable error) { NSLog(@"Subscribed to weather topic"); }];
تُجري هذه الدعوة طلبًا
غير متزامن إلى الخلفية في FCM وتشترك العميل في
الموضوع المحدّد. قبل استدعاء subscribeToTopic:topic
، تأكَّد من أنّه سبق أن تلقّت
مثيل تطبيق العميل رمز تنشيط التسجيل من خلال callback didReceiveRegistrationToken
.
في كل مرة يتم فيها تشغيل التطبيق،
تأكّد FCM من أنّه تم الاشتراك في جميع المواضيع المطلوبة. لإلغاء الاشتراك، اتصل بالرقم unsubscribeFromTopic:topic
،
وسيؤدي ذلك إلى إلغاء الاشتراك في الموضوع في الخلفية.FCM
تلقّي رسائل المواضيع ومعالجتها
تُرسِل FCM رسائل المواضيع بالطريقة نفسها التي تُرسِل بها رسائل الأخرى.
نفِّذ application(_:didReceiveRemoteNotification:fetchCompletionHandler:)
كما هو موضّح:
Swift
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 }
Objective-C
- (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); }
إنشاء طلبات الإرسال
بعد إنشاء موضوع، إما من خلال اشتراك نُسخ تطبيق العميل في الموضوع من جهة العميل أو من خلال واجهة برمجة تطبيقات الخادم، يمكنك إرسال الرسائل إلى الموضوع. إذا كانت هذه هي المرة الأولى التي تنشئ فيها طلبات إرسال لـ FCM، اطّلِع على دليل بيئة الخادم وFCM للحصول على معلومات مهمة عن الخلفية والإعداد.
في منطق الإرسال في الخلفية، حدِّد اسم الموضوع المطلوب كما هو موضّح:
Node.js
// 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);
Python
# 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)
انتقال
// 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)
#C
// 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);
REST
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.js
// 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);
Python
# 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)
انتقال
// 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)
#C
// 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);
REST
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
الخطوات التالية
- يمكنك استخدام الخادم لاشتراك نُسخ تطبيق العميل في المواضيع و تنفيذ مهام الإدارة الأخرى. راجِع مقالة إدارة اشتراكات المواضيع على الخادم.