شروع به کار با «پیام‌رسانی ابریِ 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

هنگام مقداردهی اولیه کتابخانه 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 فراخوان دریافت خواهد کرد که باید در کلاسی که 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++ هدایت می‌کند. وقتی برنامه در پیش‌زمینه باشد (یا وقتی برنامه در پس‌زمینه باشد و پیام فقط داده دریافت کند)، پیام‌ها ازطریق یکی از توابع برگشتی ارائه‌شده در این کلاس ارسال خواهد شد. برای افزودن رفتار سفارشی به مدیریت پیام، باید 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>

نسخه‌های جدید 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 (و در Android،‏ Analytics) از تولید آن در زمان پیکربندی جلوگیری کنید. برای انجام این کار، مقدار فراداده‌ای را به 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++‎
• ارسال پیام به موضوعات