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

اختيار المنصة:

iOS+ Android الويب Flutter Unity 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"

Android

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

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

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

   ملاحظة مهمة: تأكَّد من إضافة مكتبة firebase_messaging إلى ملف CMakeLists.txt.

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

   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 الخاص بمشروعك، أضِف تبعية "مراسلة Firebase السحابية":

      pod 'FirebaseMessaging'

   2. اسحب إطارَي العمل firebase.framework وfirebase_messaging.framework إلى مشروع Xcode من حزمة تطوير البرامج (SDK) لـ Firebase C++.

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

   1. في وحدة تحكّم "Firebase"، انتقِل إلى الإعدادات > إعدادات عامة. بعد ذلك، انقر على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.
   2. في مفتاح مصادقة APNs ضمن إعدادات تطبيق iOS، انقر على تحميل لتحميل مفتاح مصادقة التطوير أو مفتاح مصادقة الإنتاج أو كليهما. ويجب توفير طريقة اتصال واحدة على الأقل.
   3. انتقِل إلى الموقع الذي حفظت فيه مفتاحك، واختَره، ثم انقر على فتح. أضِف معرّف المفتاح (المتوفّر في مركز أعضاء مطوّري Apple) وانقر على تحميل.

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

   1. اختَر المشروع من Navigator area (منطقة التنقّل).
   2. اختَر هدف المشروع من مساحة المحرِّر.

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

      1. انتقِل إلى أُطر العمل والمكتبات المرتبطة (Linked Frameworks and Libraries)، ثم انقر على الزر + لإضافة أُطر العمل.

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

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

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

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

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

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

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

6. إعداد مراسلة Firebase السحابية، مع ضبط التطبيق وأداة استماع تم إنشاؤها:

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

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

ملاحظة: يتم نقل Firebase Cloud Messaging من رموز تسجيل FCM إلى أرقام تعريف تثبيت Firebase (FID) لاستهداف نُسخ فردية من التطبيق.

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

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

Android

أضِف عنصر <meta-data> التالي داخل عنصر <application> في AndroidManifest.xml:

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

Swift

أضِف المفتاح FirebaseMessagingInstallationIdEnabled إلى Info.plist واضبطه على YES:

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.
  }
};

إذا أردت استهداف نسخة التطبيق الافتراضية المحدّدة هذه، أرسِل معرّف 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، لأنّه ستتم إزالة هذه الطريقة في إصدار مستقبلي.

عند إعداد مكتبة 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 فارغة.

وباختصار:

حالة التطبيق	إشعار	البيانات	كلاهما
لون الواجهة	OnMessageReceived	OnMessageReceived	OnMessageReceived
الخلفية	لوحة النظام	OnMessageReceived	الإشعار: في لوحة الإشعارات البيانات: في الإضافات الخاصة بالintent

معالجة الرسائل المخصّصة على 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>

تستخدم الإصدارات الجديدة من حزمة Firebase C++ SDK (الإصدار 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::SetRegistrationOnInitEnabled(true);

ملاحظة: تم إيقاف SetTokenRegistrationOnInitEnabled نهائيًا، لذا يُرجى استخدام SetRegistrationOnInitEnabled بدلاً منه.

وتظل هذه القيمة محفوظة عند إعادة تشغيل التطبيق بعد ضبطها.

الرسائل التي تتضمّن روابط لصفحات معيّنة على 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++‎
• إرسال الرسائل إلى المواضيع