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

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

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

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

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

فعال کردن ثبت‌نام بااستفاده از «شناسه نصب Firebase»

برای فعال کردن ثبت نمونه برنامه‌تان با FCM بااستفاده از شناسه نصب Firebase (FID)، ابتدا باید شناسه‌های نصب Firebase را در پیکربندی برنامه‌تان برای هر دو پلاتفرم Android و Apple فعال کنید:

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

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 Cloud Messaging، یک کد ثبت برای نمونه برنامه کارخواه درخواست می‌شود. برنامه با OnTokenReceived callback کد را دریافت می‌کند که باید در کلاسی که 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>

نسخه‌های جدید 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 اضافه کنید:

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