إعداد تطبيق عميل "المراسلة عبر السحابة الإلكترونية من Firebase" باستخدام C++

لكتابة تطبيق عميل Firebase Cloud Messaging متوافق مع عدّة منصات باستخدام C++، استخدِم واجهة برمجة التطبيقات Firebase Cloud Messaging. تعمل حزمة تطوير البرامج (SDK) للغة C++ على كلّ من نظام التشغيل Android ومنصّة Apple، مع الحاجة إلى بعض عمليات الإعداد الإضافية لكلّ منصّة.

إعداد Firebase وFCM SDK

Android

1. أضِف Firebase إلى مشروع C++ إذا لم يسبق لك إجراء ذلك.

   • في تعليمات الإعداد المرتبطة، راجِع متطلبات الجهاز والتطبيق لاستخدام حزمة تطوير البرامج (SDK) Firebase C++، بما في ذلك الاقتراح باستخدام CMake لإنشاء تطبيقك.

   • في ملف build.gradle على مستوى المشروع، تأكَّد من تضمين مستودع Maven من Google في كل من القسمَين buildscript وallprojects.

   ملاحظة مهمة: احرص على إضافة مكتبة firebase_messaging إلى ملف CMakeLists.txt.

2. أنشئ عنصرًا من عناصر تطبيق Firebase، مع تمرير بيئة JNI وActivity:

   app = ::firebase::App::Create(::firebase::AppOptions(), jni_env, activity);

3. حدِّد فئة تنفّذ واجهة firebase::messaging::Listener.

4. ابدأ FCM، مع تمرير التطبيق وListener تم إنشاؤه:

   ::firebase::messaging::Initialize(app, listener);

5. يجب أن تتحقّق التطبيقات التي تعتمد على حزمة تطوير البرامج (SDK) لخدمات Google Play من توفّر حزمة APK متوافقة من خدمات Google Play على الجهاز قبل الوصول إلى الميزات. لمزيد من المعلومات، يُرجى الرجوع إلى مقالة التحقّق من حزمة APK الخاصة بـ "خدمات Google Play".

iOS+‎

1. أضِف Firebase إلى مشروع C++ إذا لم يسبق لك إجراء ذلك. بعد ذلك، لإعداد مشروعك لاستخدام FCM:
   1. في ملف Podfile الخاص بمشروعك، أضِف تبعية FCM:

      pod 'FirebaseMessaging'

   2. اسحب إطارَي العمل firebase.framework وfirebase_messaging.framework إلى مشروع Xcode من Firebase C++ SDK.

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

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

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

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

3. اضبط مشروع Xcode لتفعيل الإشعارات الفورية:

   1. اختَر المشروع من مساحة المستكشف.
   2. اختَر هدف المشروع من مساحة المحرّر.

   3. اختَر علامة التبويب عام من مساحة المحرّر.

      1. انتقِل للأسفل إلى الأُطر والمكتبات المرتبطة، ثم انقر على الزر + لإضافة الأُطر.

      2. في النافذة التي تظهر، انتقِل إلى UserNotifications.framework، وانقر على هذا الإدخال، ثم انقر على إضافة.

         لا يظهر إطار العمل هذا إلا في الإصدار 8 والإصدارات الأحدث من Xcode، وهو مطلوب من أجل استخدام هذه المكتبة.

   4. انقر على علامة التبويب الإمكانات من مساحة المحرّر.

      1. فعِّل الإشعارات الفورية.
      2. انتقِل للأسفل إلى أوضاع الخلفية، ثم فعِّلها.
      3. اختَر الإشعارات عن بُعد ضمن أوضاع التشغيل في الخلفية.

4. أنشئ عنصر تطبيق Firebase:

   app = ::firebase::App::Create(::firebase::AppOptions());

5. حدِّد فئة تنفّذ واجهة firebase::messaging::Listener.

6. يمكنك إعداد "المراسلة عبر السحابة الإلكترونية من Firebase" من خلال تمرير التطبيق وListener تم إنشاؤه:

   ::firebase::messaging::Initialize(app, listener);

الوصول إلى الرمز المميز لتسجيل الجهاز

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

لإعادة تفعيل FCM، يمكنك إجراء عملية استدعاء وقت التشغيل:

::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. لمزيد من المعلومات، يمكنك الاطّلاع على هذه الوظيفة في نموذج التشغيل السريع الذي يمكنك تنزيله وتشغيله ومراجعته.

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

• إرسال رسائل المواضيع
• الإرسال إلى مجموعات الأجهزة

يُرجى العِلم أنّه يجب أن يكون لديك تنفيذ على الخادم للاستفادة من هذه الميزات.