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

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

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

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

الوصول إلى معرّف Firebase Installation ID

تفعيل التسجيل باستخدام معرّف تثبيت 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 مع معاودة الاتصال 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.
  }
};

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

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

يمكنك أيضًا تفعيل التسجيل يدويًا باستخدام 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. في هذه الحالة، يتم تلقّي حمولات الرسائل من خلال 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 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:

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

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

::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++‎
• إرسال الرسائل إلى المواضيع