لكتابة تطبيق عميل Firebase Cloud Messaging متوافق مع جميع الأنظمة الأساسية باستخدام C++، استخدِم واجهة برمجة التطبيقات Firebase Cloud Messaging. تعمل حزمة تطوير البرامج (SDK) لـ C++ مع نظامَي التشغيل Android وApple، مع ضرورة إجراء بعض عمليات الإعداد الإضافية لكل نظام تشغيل.
إعداد Firebase وحزمة تطوير البرامج (SDK) لمنصّة FCM
Android
أضِف Firebase إلى مشروع C++ الخاص بك، في حال لم يسبق لك إجراء ذلك.
في تعليمات الإعداد المرتبطة، راجِع متطلبات الجهاز والتطبيق لاستخدام حزمة تطوير البرامج (SDK) Firebase C++، بما في ذلك الاقتراح لاستخدام CMake لإنشاء تطبيقك.
في ملف
build.gradle
على مستوى المشروع، احرص على تضمين مستودع Maven من Google في كلّ من القسمَينbuildscript
وallprojects
.
أنشئ عنصر تطبيق Firebase، مع تضمين بيئة JNI و Activity:
app = ::firebase::App::Create(::firebase::AppOptions(), jni_env, activity);
حدِّد فئة تنفِّذ واجهة
firebase::messaging::Listener
.يمكنك إعداد FCM، مع إدخال التطبيق ومستمع تم إنشاؤه:
::firebase::messaging::Initialize(app, listener);
على التطبيقات التي تعتمد على حزمة تطوير البرامج (SDK) لـ "خدمات Google Play" التحقّق من الجهاز بحثًا عن حزمة APK متوافقة من "خدمات Google Play" قبل الوصول إلى الميزات. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة البحث عن حزمة APK الخاصة بخدمة "خدمات Google Play".
iOS+
-
أضِف Firebase إلى مشروع C++ الخاص بك، في حال لم يسبق لك إجراء ذلك. بعد ذلك،
لإعداد مشروعك في FCM:
- في ملف Podfile الخاص بمشروعك، أضِف التبعية لـ FCM:
pod 'FirebaseMessaging'
- اسحب إطارَي عمل
firebase.framework
وfirebase_messaging.framework
إلى مشروع Xcode من حزمة تطوير البرامج (SDK) Firebase C++.
- في ملف Podfile الخاص بمشروعك، أضِف التبعية لـ FCM:
حمِّل مفتاح مصادقة APNs إلى Firebase. إذا لم يكن لديك مفتاح مصادقة APNs، احرص على إنشاء مفتاح في Apple Developer Member Center.
-
داخل مشروعك في وحدة تحكّم Firebase، انقر على رمز الترس، ثم على إعدادات المشروع، ثم على علامة التبويب الرسائل عبر السحابة الإلكترونية.
-
في مفتاح مصادقة APNs ضمن إعدادات تطبيق iOS، انقر على الزر تحميل.
-
انتقِل إلى المكان الذي حفظت فيه مفتاحك، واختَره، ثم انقر على فتح. أضِف معرّف المفتاح (متاحًا في Apple Developer Member Center) وانقر على تحميل.
-
يمكنك ضبط مشروع Xcode لتفعيل الإشعارات الفورية باتّباع الخطوات التالية:
- اختَر المشروع من منطقة المستكشف.
- اختَر هدف المشروع من منطقة المحرِّر.
اختَر علامة التبويب عام من منطقة المحرِّر.
- انتقِل للأسفل إلى الإطارات والمراجع المرتبطة، ثم انقر على زر + لإضافة إطارات عمل.
في النافذة التي تظهر، انتقِل إلى UserNotifications.framework، وانقر على هذا الإدخال، ثم انقر على إضافة.
لا يظهر هذا الإطار إلا في الإصدار 8 من Xcode والإصدارات الأحدث، وهو مطلوب من هذه المكتبة.
انقر على علامة التبويب الإمكانات من منطقة المحرِّر.
- اضبط الإشعارات الفورية على تفعيل.
- انتقِل للأسفل إلى الأوضاع التي تعمل في الخلفية، ثم اضبط الخيار على تفعيل.
- اختَر الإشعارات عن بُعد ضمن الأوضاع التي تعمل في الخلفية.
أنشئ عنصر تطبيق Firebase:
app = ::firebase::App::Create(::firebase::AppOptions());
حدِّد فئة تنفِّذ واجهة
firebase::messaging::Listener
.يمكنك إعداد خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، مع إدخال التطبيق وأحد Listeners الذي تم إنشاؤه:
::firebase::messaging::Initialize(app, listener);
الوصول إلى الرمز المميّز لتسجيل الجهاز
عند بدء مكتبة "المراسلة عبر السحابة الإلكترونية من Firebase"، يتم طلب رمز تنشيط تسجيل
لمثيل تطبيق العميل. سيتلقّى التطبيق الرمز المميّز مع دالة callback الخاصة بـ
OnTokenReceived
، والتي يجب تحديدها في الفئة التي تنفِّذ
firebase::messaging::Listener
.
إذا أردت استهداف هذا الجهاز تحديدًا، عليك الوصول إلى هذا الرمز المميّز.
ملاحظة حول تسليم الرسائل على Android
عندما لا يكون التطبيق قيد التشغيل على الإطلاق وينقر المستخدم على إشعار،
لا يتم توجيه الرسالة تلقائيًا من خلال FCM
الاستدعاءات المضمّنة. في هذه الحالة، يتم استلام حِزم بيانات الرسائل من خلال Intent
تُستخدَم لبدء التطبيق. لتوجيه FCM هذه الرسائل القادمة
إلى دالة الاستدعاء في مكتبة C++، عليك إلغاء الطريقة
onNewIntent
في نشاطك وضبط Intent
على
MessageForwardingService
.
import com.google.firebase.messaging.MessageForwardingService; class MyActivity extends Activity { private static final String TAG = "MyActvity"; @Override protected void onNewIntent(Intent intent) { Log.d(TAG, "A message was sent to this app while it was in the background."); Intent message = new Intent(this, MessageForwardingService.class); message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT); message.putExtras(intent); message.setData(intent.getData()); // For older versions of Firebase C++ SDK (< 7.1.0), use `startService`. // startService(message); MessageForwardingService.enqueueWork(this, message); } }
إنّ الرسائل التي يتم استلامها عندما يكون التطبيق في الخلفية تتضمّن محتوى
حقل الإشعار الذي يتم استخدامه لتعبئة إشعار لوحة النظام، ولكن
لن يتم إرسال محتوى هذا الإشعار إلى FCM. وهذا يعني أنّه
سيكون Message::notification
فارغًا.
وباختصار:
حالة التطبيق | إشعار | البيانات | كلاهما |
---|---|---|---|
لون الواجهة | OnMessageReceived |
OnMessageReceived |
OnMessageReceived |
الخلفية | لوحة النظام | OnMessageReceived |
الإشعار: علبة النظام البيانات: في إضافات الطلب |
التعامل مع الرسائل المخصّصة على Android
يتم تلقائيًا تمرير الإشعارات المُرسَلة إلى التطبيق إلى
::firebase::messaging::Listener::OnMessageReceived
، ولكن قد تحتاج في بعض الحالات إلى
تجاوز السلوك التلقائي. لتنفيذ ذلك على Android، عليك
كتابة فئات مخصّصة تمتد إلى
com.google.firebase.messaging.cpp.ListenerService
بالإضافة إلى تعديل
AndroidManifest.xml
في مشروعك.
إلغاء طرق ListenerService
ListenerService
هي فئة Java التي تعترض الرسائل الواردة المُرسَلة إلى
التطبيق وتوجّهها إلى مكتبة C++. عندما يكون التطبيق في المقدّمة،
(أو عندما يكون التطبيق في الخلفية ويتلقّى حمولة بيانات فقط)،
ستتمّ معالجة الرسائل من خلال إحدى وظائف الاستدعاء المقدَّمة في هذه الفئة. لإضافة
سلوك مخصّص إلى معالجة الرسائل، عليك توسيع FCM
ListenerService
التلقائي:
import com.google.firebase.messaging.cpp.ListenerService; class MyListenerService extends ListenerService {
من خلال إلغاء الطريقة ListenerService.onMessageReceived
، يمكنك
تنفيذ الإجراءات استنادًا إلى عنصر
RemoteMessage
المستلَم والحصول على بيانات الرسالة:
@Override public void onMessageReceived(RemoteMessage message) { Log.d(TAG, "A message has been received."); // Do additional logic... super.onMessageReceived(message); }
تتوفّر أيضًا في ListenerService
بعض الطرق الأخرى التي يتم استخدامها بشكل أقل تكرارًا.
ويمكن إلغاء هذه الإعدادات أيضًا. للمزيد من المعلومات، يُرجى الاطّلاع على مرجع
FirebaseMessagingService
.
@Override public void onDeletedMessages() { Log.d(TAG, "Messages have been deleted on the server."); // Do additional logic... super.onDeletedMessages(); } @Override public void onMessageSent(String messageId) { Log.d(TAG, "An outgoing message has been sent."); // Do additional logic... super.onMessageSent(messageId); } @Override public void onSendError(String messageId, Exception exception) { Log.d(TAG, "An outgoing message encountered an error."); // Do additional logic... super.onSendError(messageId, exception); }
تحديث AndroidManifest.xml
بعد كتابة الفئات المخصّصة، يجب تضمينها في ملف
AndroidManifest.xml
لكي يتم تطبيقها. تأكَّد من أنّ البيان يتضمّن
أدوات الدمج من خلال تحديد السمة المناسبة داخل علامة <manifest>
،
على النحو التالي:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.google.firebase.messaging.cpp.samples" xmlns:tools="http://schemas.android.com/tools">
في أرشيف firebase_messaging_cpp.aar
، يتوفّر ملف AndroidManifest.xml
يوضّح ListenerService
التلقائي لـ FCM. يتم عادةً دمج هذا البيان
مع البيان الخاص بالمشروع، وهو الطريقة التي يمكن بها تنفيذ
ListenerService
. يجب استبدال ListenerService
هذا ب
خدمة مستمع مخصّصة. يتمّ ذلك من خلال إزالة القيمة التلقائية
ListenerService
وإضافة الخدمة المخصّصة، ويمكن إجراء ذلك باستخدام
السطور التالية في ملف AndroidManifest.xml
الخاص بمشاريعك:
<service android:name="com.google.firebase.messaging.cpp.ListenerService" tools:node="remove" />
<service android:name="com.google.firebase.messaging.cpp.samples.MyListenerService" android:exported="false"> <intent-filter> <action android:name="com.google.firebase.MESSAGING_EVENT"/> </intent-filter> </service>
تستخدِم الإصدارات الجديدة من حزمة تطوير البرامج (SDK) لـ C++ في Firebase (بدءًا من الإصدار 7.1.0) JobIntentService
، ما يتطلّب تعديلات إضافية في ملف AndroidManifest.xml
.
<service android:name="com.google.firebase.messaging.MessageForwardingService" android:permission="android.permission.BIND_JOB_SERVICE" android:exported="false" > </service>
منع الإعداد التلقائي
تُنشئ FCM رمزًا مميزًا للتسجيل لاستهداف الأجهزة.
عند إنشاء رمز مميّز، تحمّل المكتبة
معرّف بيانات الضبط إلى Firebase. إذا كنت تريد الحصول على موافقة صريحة
قبل استخدام الرمز المميّز، يمكنك منع إنشائه في وقت الضبط من خلال
إيقاف خدمة "إشعارات Google من خادم Firebase" (و"إحصاءات Google" على Android). لإجراء ذلك، أضِف قيمة بيانات وصفية إلى
Info.plist
(وليس GoogleService-Info.plist
) على منصات Apple،
أو إلى AndroidManifest.xml
على Android:
Android
<?xml version="1.0" encoding="utf-8"?> <application> <meta-data android:name="firebase_messaging_auto_init_enabled" android:value="false" /> <meta-data android:name="firebase_analytics_collection_enabled" android:value="false" /> </application>
Swift
FirebaseMessagingAutoInitEnabled = NO
لإعادة تفعيل "خدمة إرسال الرسائل إلى الأجهزة الجوّالة من Google"، يمكنك إجراء مكالمة وقت التشغيل:
::firebase::messaging::SetTokenRegistrationOnInitEnabled(true);
تظل هذه القيمة محفوظة عند إعادة تشغيل التطبيق بعد ضبطها.
التعامل مع الرسائل باستخدام روابط صفحات في التطبيقات على Android
يسمح FCM بإرسال رسائل تتضمّن رابطًا لصفحة معيّنة في تطبيقك. لتلقّي الرسائل التي تحتوي على رابط لصفحة معيّنة، عليك إضافة فلتر أهداف جديد إلى النشاط الذي يعالج الروابط لصفحات في تطبيقك. ومن المفترض أن يرصد فلتر الأهداف الروابط لصفحات في نطاقك. إذا كانت رسائلك لا تحتوي على رابط لصفحة في التطبيق، لن يكون هذا الإعداد ضروريًا. في ملف AndroidManifest.xml:
<intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/> <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/> </intent-filter>
من الممكن أيضًا تحديد عنصر نائب لجعل فلتر الأهداف أكثر مرونة. على سبيل المثال:
<intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:host="*.example.com" android:scheme="http"/> <data android:host="*.example.com" android:scheme="https"/> </intent-filter>
عندما ينقر المستخدمون على إشعار يحتوي على رابط يؤدي إلى المخطّط والمضيف الذيحددته، سيبدأ تطبيقك النشاط باستخدام فلتر الغرض هذا لمعالجة الرابط.
الخطوات التالية
بعد إعداد تطبيق العميل، تكون مستعدًا لإرسال رسائل رسائل العميل ورسائل الموضوع باستخدام Firebase. للاطّلاع على مزيد من المعلومات، يمكنك الاطّلاع على هذه الوظيفة التي تم توضيحها في نموذج البدء السريع الذي يمكنك تنزيله وتشغيله ومراجعته.
لإضافة سلوك آخر أكثر تقدمًا إلى تطبيقك، اطّلِع على أدلة إرسال الرسائل من خادم التطبيق:
يُرجى العِلم أنّك ستحتاج إلى تنفيذ الخادم للاستفادة من هذه الميزات.