شروع به کار با «پیام‌رسانی ابریِ Firebase» در برنامه‌های C++‎

انتخاب پلاتفرم:

iOS+ Android Web Flutter Unity C++‎

این راهنما نحوه شروع به کار با Firebase Cloud Messaging در برنامه‌های مشتری C++ را توضیح می‌دهد تا بتوانید پیام‌ها را به‌طور مطمئن ارسال کنید.

برای نوشتن برنامه کارخواه Firebase Cloud Messaging چندسکویی با C++‎، از Firebase Cloud Messaging API استفاده کنید. «کیت توسعه نرم‌افزار C++‎» هم برای پلاتفرم‌های Android و هم Apple کار می‌کند، اما برای هر پلاتفرم به راه‌اندازی اضافی نیاز دارد. برای کسب اطلاعات بیشتر درباره نحوه عملکرد کیت توسعه نرم‌افزار C++‎ برای iOS و Android با FCM، به آشنایی با Firebase برای C++‎ مراجعه کنید.

راه‌اندازی Firebase و کیت توسعه نرم‌افزار FCM

Android

1. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه C++‎ خود اضافه کنید.

   • در دستورالعمل‌های راه‌اندازی پیوندشده، الزامات دستگاه و برنامه را برای استفاده از کیت توسعه نرم‌افزار Firebase C++، ازجمله توصیه استفاده از CMake برای ساختن برنامه، مرور کنید.

   • در فایل build.gradle سطح پروژه، حتماً مخزن Maven متعلق به Google را در هر دو بخش buildscript و allprojects اضافه کنید.

   مهم: حتماً کتابخانه firebase_messaging را به فایل CMakeLists.txt اضافه کنید.

2. با ارسال محیط JNI و Activity، شیء Firebase App ایجاد کنید:

   app = ::firebase::App::Create(::firebase::AppOptions(), jni_env, activity);

3. کلاسی را تعریف کنید که میانای firebase::messaging::Listener را پیاده‌سازی می‌کند.

4. ‫FCM را مقداردهی اولیه کنید و «برنامه» و «شنونده» ساخته‌شده را به آن ارسال کنید:

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

5. برنامه‌هایی که به «کیت توسعه نرم‌افزار خدمات Google Play» متکی هستند باید قبل‌از دسترسی به ویژگی‌ها، دستگاه را ازنظر داشتن فایل APK سازگار «خدمات Google Play» بررسی کنند. برای کسب اطلاعات بیشتر، به بررسی APK «خدمات Google Play» مراجعه کنید.

iOS+‎

1. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه C++‎ خود اضافه کنید. سپس، برای راه‌اندازی پروژه برای FCM:
   1. در Podfile پروژه خود، وابستگی FCM را اضافه کنید:

      pod 'FirebaseMessaging'

   2. چارچوب‌های firebase.framework و firebase_messaging.framework را از Firebase C++ SDK به پروژه Xcode خود بکشید.

2. کلید اصالت‌سنجی APNs را در Firebase بارگذاری کنید. اگر ازقبل کلید اصالت‌سنجی APNs ندارید، حتماً در مرکز اعضای توسعه‌دهندگان Apple یکی ایجاد کنید.

   1. در کنسول Firebase، به تنظیمات > موارد کلی بروید. سپس، روی برگه پیام‌رسانی ابری کلیک کنید.
   2. در کلید اصالت‌سنجی APNs در بخش پیکربندی برنامه iOS، روی بارگذاری کلیک کنید تا کلید اصالت‌سنجی توسعه، یا کلید اصالت‌سنجی تولید، یا هر دو را بارگذاری کنید. حداقل یکی لازم است.
   3. به مکانی که کلیدتان را ذخیره کرده‌اید بروید، آن را انتخاب کنید، و روی باز کردن کلیک کنید. شناسه کلید را برای کلید (در مرکز اعضای توسعه‌دهنده Apple دردسترس است) اضافه کنید و روی بارگذاری کلیک کنید.

3. پروژه Xcode خود را برای فعال کردن «اعلان‌های لحظه‌ای» پیکربندی کنید:

   1. پروژه را از بخش پیمایشگر انتخاب کنید.
   2. هدف پروژه را از بخش ویرایشگر انتخاب کنید.

   3. زبانه عمومی را از بخش ویرایشگر انتخاب کنید.

      1. به چارچوب‌ها و کتابخانه‌های پیوندشده پیمایش کنید، سپس روی دکمه + کلیک کنید تا چارچوب‌ها را اضافه کنید.

      2. در پنجره‌ای که ظاهر می‌شود، به UserNotifications.framework پیمایش کنید، روی ورودی کلیک کنید، سپس روی افزودن کلیک کنید.

         این چارچوب فقط در Xcode نسخه ۸ و بالاتر نشان داده می‌شود و این کتابخانه به آن نیاز دارد.

   4. برگه قابلیت‌ها را از بخش ویرایشگر انتخاب کنید.

      1. اعلان‌های لحظه‌ای را روی روشن قرار دهید.
      2. به حالت‌های پس‌زمینه پیمایش کنید، سپس آن را به روشن تغییر دهید.
      3. اعلان‌های ازراه‌دور را در بخش حالت‌های پس‌زمینه انتخاب کنید.

4. ایجاد کردن شیء Firebase App:

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

5. کلاسی را تعریف کنید که میانای firebase::messaging::Listener را پیاده‌سازی می‌کند.

6. «پیام‌رسانی ابریِ Firebase» را مقداردهی اولیه کنید و «برنامه» و «شنونده» ساخته‌شده را به آن ارسال کنید:

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

دسترسی به شناسه نصب Firebase

توجه: Firebase Cloud Messaging درحال انتقال از FCM نشان‌های ثبت به شناسه‌های نصب Firebase (FIDs) برای هدف‌یابی نمونه‌های برنامه است.

فعال کردن ثبت‌نام بااستفاده از «شناسه نصب 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 Listener

هنگام مقداردهی اولیه کتابخانه 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 تهی خواهد بود.

به‌طور خلاصه:

وضعیت برنامه	اعلان	Data	هردو
پیش‌زمینه	OnMessageReceived	OnMessageReceived	OnMessageReceived
پس‌زمینه	سینی سیستم	OnMessageReceived	اعلان: سینی سیستم داده‌ها: در موارد اضافی هدف.

مدیریت پیام سفارشی در 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 (از ۷.۱.۰ به بعد) از 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 اضافه کنید:

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 اجازه می‌دهد پیام‌هایی حاوی پیوند عمیق به برنامه‌تان ارسال شود. برای دریافت پیام‌هایی که حاوی پیوند عمیق هستند، باید فیلتر هدف جدیدی به فعالیتی که پیوندهای عمیق را برای برنامه‌تان مدیریت می‌کند اضافه کنید. فیلتر هدف باید پیوندهای عمیق دامنه شما را دریافت کند. اگر پیام‌هایتان حاوی پیوند عمیق نیست، این پیکربندی لازم نیست. در 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>

وقتی کاربران روی اعلانی که حاوی پیوندی به طرح و میزبان مشخص‌شده توسط شما است تک‌ضرب می‌زنند، برنامه شما فعالیت را با این فیلتر قصد برای مدیریت پیوند شروع می‌کند.

مراحل بعدی

پس‌از تکمیل مراحل راه‌اندازی، در اینجا چند گزینه برای پیشبرد کار با FCM برای C++‎ ارائه شده است:

• ارسال پیام به دستگاه‌ها
• دریافت پیام‌ها در برنامه C++‎
• ارسال پیام به موضوعات