بدء استخدام "المراسلة عبر السحابة الإلكترونية من 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 و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، انتقِل إلى الإعدادات > الإعدادات العامة. بعد ذلك، انقر على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.
   2. في مفتاح مصادقة APNs ضمن إعداد تطبيق iOS، انقر على تحميل لتحميل مفتاح مصادقة التطوير أو مفتاح مصادقة الإنتاج أو كليهما. ويجب توفير طريقة اتصال واحدة على الأقل.
   3. انتقِل إلى الموقع الذي حفظت فيه المفتاح، واختَره، ثم انقر على فتح. أضِف رقم تعريف المفتاح (المتوفر في Apple Developer Member Center) وانقر على تحميل.

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

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

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

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

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

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

   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

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

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

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

عند تهيئة مكتبة 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	الإشعار: في لوحة النظام البيانات: في الإضافات الخاصة بالغرض.

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