با Firebase Cloud Messaging شروع کنید

iOS+ اندروید وب فلاتر یونیتی سی پلاس پلاس

این راهنمای سریع نحوه راه‌اندازی Firebase Cloud Messaging را در برنامه‌های موبایل و کلاینت وب شما شرح می‌دهد تا بتوانید پیام‌ها را به طور قابل اعتمادی ارسال کنید. برای محیط‌های سرور، به بخش Your server environment and FCM مراجعه کنید.

راه‌اندازی یک برنامه کلاینت Firebase Cloud Messaging با C++

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

فایربیس و FCM SDK را راه‌اندازی کنید

اندروید

1. اگر هنوز Firebase را به پروژه ++C خود اضافه نکرده‌اید، آن را اضافه کنید.

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

   • در فایل build.gradle سطح پروژه خود، مطمئن شوید که مخزن Maven گوگل را هم در بخش‌های buildscript و هم allprojects خود وارد کرده‌اید.

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

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

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

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

4. مقداردهی اولیه FCM ، ارسال App و یک Listener ساخته شده:

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

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

آی‌او‌اس+

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

      pod 'FirebaseMessaging'

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

2. کلید احراز هویت APN خود را در Firebase آپلود کنید. اگر از قبل کلید احراز هویت APN ندارید، حتماً آن را در مرکز اعضای توسعه‌دهنده اپل ایجاد کنید.

   1. در داخل پروژه خود در کنسول Firebase ، نماد چرخ دنده را انتخاب کنید، تنظیمات پروژه را انتخاب کنید و سپس برگه Cloud Messaging را انتخاب کنید.

   2. در کلید احراز هویت APNs در بخش پیکربندی برنامه iOS ، روی دکمه آپلود کلیک کنید تا کلید احراز هویت توسعه یا کلید احراز هویت تولید یا هر دو را آپلود کنید. حداقل یکی از آنها لازم است.

   3. به محلی که کلید خود را ذخیره کرده‌اید بروید، آن را انتخاب کنید و روی «باز کردن» کلیک کنید. شناسه کلید را برای کلید (که در مرکز اعضای توسعه‌دهنده اپل موجود است) اضافه کنید و روی «بارگذاری» کلیک کنید.

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

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

   3. از قسمت ویرایشگر، برگه عمومی (General) را انتخاب کنید.

      1. به بخش Linked Frameworks and Libraries بروید، سپس برای افزودن فریم‌ورک‌ها روی دکمه + کلیک کنید.

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

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

   4. از قسمت ویرایشگر، برگه قابلیت‌ها (Capabilities) را انتخاب کنید.

      1. اعلان‌های فوری را روی روشن (On) قرار دهید.
      2. به حالت‌های پس‌زمینه بروید، سپس آن را روی روشن (On) قرار دهید.
      3. در قسمت «حالت‌های پس‌زمینه»، «اعلان‌های از راه دور» را انتخاب کنید.

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

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

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

6. مقداردهی اولیه Firebase Cloud Messaging، ارسال App و یک Listener ساخته شده:

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

دسترسی به توکن ثبت دستگاه

پس از مقداردهی اولیه کتابخانه Firebase Cloud Messaging، یک توکن ثبت نام برای نمونه برنامه کلاینت درخواست می‌شود. برنامه، توکن را با فراخوانی OnTokenReceived دریافت می‌کند که باید در کلاسی که firebase::messaging::Listener پیاده‌سازی می‌کند، تعریف شود.

اگر می‌خواهید آن دستگاه خاص را هدف قرار دهید، به این توکن نیاز خواهید داشت.

نکاتی در مورد ارسال پیام در اندروید

وقتی برنامه اصلاً اجرا نمی‌شود و کاربر روی یک اعلان ضربه می‌زند، پیام به طور پیش‌فرض از طریق فراخوانی‌های داخلی FCM هدایت نمی‌شود. در این حالت، بارهای پیام از طریق Intent مورد استفاده برای شروع برنامه دریافت می‌شوند. برای اینکه FCM این پیام‌های دریافتی را به فراخوانی کتابخانه C++ ارسال کند، باید متد onNewIntent در Activity خود بازنویسی کنید و 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 برابر با null خواهد بود.

به طور خلاصه:

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

مدیریت سفارشی پیام‌ها در اندروید

به طور پیش‌فرض، اعلان‌های ارسالی به برنامه به ::firebase::messaging::Listener::OnMessageReceived ارسال می‌شوند، اما در برخی موارد ممکن است بخواهید رفتار پیش‌فرض را لغو کنید. برای انجام این کار در اندروید، باید کلاس‌های سفارشی بنویسید که com.google.firebase.messaging.cpp.ListenerService را ارث‌بری کنند و همچنین AndroidManifest.xml پروژه خود را به‌روزرسانی کنید.

متدهای ListenerService نادیده بگیرید

ListenerService کلاس جاوایی است که پیام‌های ورودی ارسال شده به برنامه را رهگیری کرده و آنها را به کتابخانه C++ هدایت می‌کند. وقتی برنامه در پیش‌زمینه است (یا وقتی برنامه در پس‌زمینه است و یک payload فقط داده دریافت می‌کند)، پیام‌ها از طریق یکی از callbackهای ارائه شده در این کلاس عبور می‌کنند. برای افزودن رفتار سفارشی به مدیریت پیام، باید ListenerService پیش‌فرض FCM را گسترش دهید:

import com.google.firebase.messaging.cpp.ListenerService;

class MyListenerService extends ListenerService {

با بازنویسی (override) متد 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 را اعلان می‌کند. این manifest معمولاً با manifest مخصوص پروژه ادغام می‌شود که نحوه اجرای ListenerService را نشان می‌دهد. این ListenerService باید با سرویس listener سفارشی جایگزین شود. این کار با حذف ListenerService پیش‌فرض و اضافه کردن Service سفارشی انجام می‌شود که می‌تواند با استفاده از خطوط زیر در فایل 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) از تولید آن در زمان پیکربندی جلوگیری کنید. برای انجام این کار، یک مقدار فراداده به Info.plist خود (نه GoogleService-Info.plist خود) در پلتفرم‌های اپل یا AndroidManifest.xml خود در اندروید اضافه کنید:

اندروید

<?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::SetTokenRegistrationOnInitEnabled(true);

این مقدار پس از تنظیم، در طول راه‌اندازی مجدد برنامه حفظ می‌شود.

پیام‌هایی با لینک‌های عمیق در اندروید

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

<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 برای مدیریت لینک آغاز می‌کند.

مراحل بعدی

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

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