بدء استخدام "المراسلة عبر السحابة الإلكترونية من 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 وFCM SDK

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

عند تهيئة مكتبة "مراسلة Firebase السحابية"، يتم طلب رمز مميز للتسجيل لمثيل تطبيق العميل. سيتلقّى التطبيق الرمز المميّز مع معاودة الاتصال 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++. عندما يكون التطبيق في المقدّمة (أو عندما يكون التطبيق في الخلفية ويتلقّى حمولة بيانات فقط)، ستمر الرسائل عبر إحدى دوال الرجوع المقدَّمة في هذه الفئة. لإضافة سلوك مخصّص إلى معالجة الرسائل، عليك توسيع نطاق ListenerService التلقائي في FCM:

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 (وAnalytics على نظام التشغيل 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::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>

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

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

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

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