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

يشرح هذا الدليل كيفية البدء في استخدام Firebase Cloud Messaging في تطبيقات العميل المستندة إلى C++، ما يتيح لك إرسال الرسائل بشكل موثوق.

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

إعداد Firebase وحزمة تطوير البرامج (SDK) لـ FCM

الوصول إلى رقم تعريف تثبيت Firebase

تفعيل التسجيل باستخدام رقم تعريف تثبيت Firebase

لتفعيل تسجيل مثيل تطبيقك في FCM باستخدام رقم تعريف تثبيت Firebase (FID)، عليك أولاً تفعيل أرقام تعريف تثبيت Firebase في إعدادات تطبيقك لكلّ من منصتَي Android وApple:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

تنفيذ المستمع onRegistrationReceived

عند بدء مكتبة Firebase Cloud Messaging، يتم تسجيل مثيل تطبيق العميل لتلقّي الرسائل باستخدام رقم تعريف تثبيت Firebase (FID). سيتلقّى التطبيق رقم تعريف تثبيت Firebase باستخدام معاودة الاتصال OnRegistrationReceived، التي يجب تحديدها في عملية تنفيذ firebase::messaging::Listener:

class MyListener : public firebase::messaging::Listener {
 public:
  void OnRegistrationReceived(const char* installation_id) override {
    LogMessage("Received Firebase Installation ID: %s", installation_id);
    // TODO: Send the Firebase Installation ID (FID) to your app server to
    // target this device for messages.
  }
};

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

التسجيل يدويًا عند إيقاف الإعداد التلقائي

يمكنك أيضًا تفعيل التسجيل يدويًا في FCM في وقت التشغيل باستخدام Register():

// Manually register with FCM
firebase::Future<void> register_future = firebase::messaging::Register();
register_future.OnCompletion([](const firebase::Future<void>& future) {
  if (future.status() == firebase::kFutureStatusComplete &&
      future.error() == 0) {
    // Note: The registered Firebase Installation ID is delivered to the
    // OnRegistrationReceived callback.
    LogMessage("Registered with FCM");
  }
});

الوصول إلى رمز تسجيل FCM (تم إيقافه نهائيًا)

عند بدء مكتبة Firebase Cloud Messaging، يتم طلب رمز تسجيل لمثيل تطبيق العميل. سيتلقّى التطبيق الرمز باستخدام معاودة الاتصال OnTokenReceived، التي يجب تحديدها في الفئة التي تنفِّذ firebase::messaging::Listener.

إذا أردت استهداف مثيل التطبيق المحدّد هذا، ستحتاج إلى الوصول إلى هذا الرمز.

ملاحظة حول تسليم الرسائل على Android

عندما لا يكون التطبيق قيد التشغيل على الإطلاق وينقر المستخدم على إشعار، لا يتم تلقائيًا توجيه الرسالة من خلال FCM's built in معاودات الاتصال. في هذه الحالة، يتم تلقّي حمولات الرسائل من خلال 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 فارغًا.

وباختصار:

التعامل مع الرسائل المخصّصة على Android

تلقائيًا، يتم تمرير الإشعارات المرسَلة إلى التطبيق إلى ::firebase::messaging::Listener::OnMessageReceived، ولكن في بعض الحالات قد تريد إلغاء السلوك التلقائي. لإجراء ذلك على Android، عليك كتابة فئات مخصّصة توسِّع com.google.firebase.messaging.cpp.ListenerService بالإضافة إلى تعديل AndroidManifest.xml الخاص بمشروعك.

إلغاء طرق ListenerService

ListenerService هي فئة Java التي تعترض الرسائل الواردة المرسَلة إلى التطبيق وتوجِّهها إلى مكتبة C++. عندما يكون التطبيق في الواجهة (أو عندما يكون التطبيق في الخلفية ويتلقّى حمولة بيانات فقط)، ستمر الرسائل من خلال إحدى معاودات الاتصال المتوفّرة في هذه الفئة. لإضافة سلوك مخصّص إلى عملية التعامل مع الرسائل، عليك توسيع FCM's التلقائية 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 يعلن عن FCM التلقائية لـ ListenerService. عادةً ما يتم دمج هذا البيان مع البيان الخاص بالمشروع، ما يتيح تشغيل 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. إذا أردت الحصول على موافقة صريحة قبل استخدام الرمز، يمكنك منع إنشائه في وقت الإعداد من خلال إيقاف المراسلة عبر السحابة الإلكترونية من Firebase (و"إحصاءات Google" على Android). لإجراء ذلك، أضِف قيمة بيانات وصفية إلى ملف Info.plist (وليس GoogleService-Info.plist) على منصات Apple، أو إلى ملف AndroidManifest.xml على 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>

FirebaseMessagingAutoInitEnabled = NO

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

::firebase::messaging::SetRegistrationOnInitEnabled(true);

تظل هذه القيمة ثابتة بعد إعادة تشغيل التطبيق بعد ضبطها.

الرسائل التي تتضمّن روابط لصفحات معيّنة على Android

FCM تسمح بإرسال رسائل تحتوي على رابط عميق في تطبيقك. لتلقّي الرسائل التي تحتوي على رابط عميق، عليك إضافة intent filter جديد إلى النشاط الذي يتعامل مع الروابط العميقة في تطبيقك. يجب أن يرصد intent filter الروابط العميقة في نطاقك. إذا كانت رسائلك لا تحتوي على رابط لصفحة معيّنة، ليس من الضروري إجراء هذا الإعداد. في ملف 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 أكثر مرونة. على سبيل المثال:

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

عندما ينقر المستخدمون على إشعار يحتوي على رابط للمخطط والمضيف اللذين تحدّدهما، سيبدأ تطبيقك النشاط باستخدام intent filter هذا للتعامل مع الرابط.

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

بعد إكمال خطوات الإعداد، إليك بعض الخيارات للمتابعة باستخدام FCM للغة C++:

• إرسال الرسائل إلى الأجهزة
• تلقّي الرسائل في تطبيق مستند إلى C++
• إرسال الرسائل إلى المواضيع