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


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

یک برنامه کلاینت Firebase Cloud Messaging را روی پلتفرم‌های اپل راه‌اندازی کنید

برای برنامه‌های کلاینت اپل، می‌توانید اعلان‌ها و داده‌های بارگیری‌شده را تا سقف ۴۰۹۶ بایت از طریق رابط APNهای Firebase Cloud Messaging دریافت کنید.

برای نوشتن کد کلاینت خود در Objective-C یا Swift، توصیه می‌کنیم از API FIRMessaging استفاده کنید. مثال شروع سریع، نمونه کدی را برای هر دو زبان ارائه می‌دهد.

قبل از شروع، Firebase را به پروژه اپل خود اضافه کنید .

روش swizzling در Firebase Cloud Messaging

کیت توسعه نرم‌افزار FCM swizzling متد را در دو حوزه کلیدی انجام می‌دهد: نگاشت توکن APN شما به توکن ثبت FCM و ثبت داده‌های تحلیلی در طول مدیریت فراخوانی پیام‌های downstream . توسعه‌دهندگانی که ترجیح می‌دهند از swizzling استفاده نکنند، می‌توانند با اضافه کردن پرچم FirebaseAppDelegateProxyEnabled در فایل Info.plist برنامه و تنظیم آن روی NO (مقدار بولی) آن را غیرفعال کنند. بخش‌های مرتبط راهنماها، نمونه‌های کد را چه با فعال بودن swizzling متد و چه بدون آن ارائه می‌دهند.

کلید احراز هویت APN خود را آپلود کنید

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

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

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

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

برای اعلان‌های از راه دور ثبت‌نام کنید

یا در هنگام راه‌اندازی یا در نقطه دلخواه در جریان برنامه، برنامه خود را برای اعلان‌های از راه دور ثبت کنید. تابع registerForRemoteNotifications مطابق شکل زیر فراخوانی کنید:

سویفت 

UNUserNotificationCenter.current().delegate = self

let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(
  options: authOptions,
  completionHandler: { _, _ in }
)

application.registerForRemoteNotifications()

AppDelegate.swift

هدف-سی 

[UNUserNotificationCenter currentNotificationCenter].delegate = self;
UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
    UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
[[UNUserNotificationCenter currentNotificationCenter]
    requestAuthorizationWithOptions:authOptions
    completionHandler:^(BOOL granted, NSError * _Nullable error) {
      // ...
    }];

[application registerForRemoteNotifications];
AppDelegate.m

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

به طور پیش‌فرض، FCM SDK در هنگام اجرای برنامه، یک توکن ثبت نام برای نمونه برنامه کلاینت ایجاد می‌کند. مشابه توکن دستگاه APN، این توکن به شما امکان می‌دهد اعلان‌های هدفمند را به هر نمونه خاص از برنامه خود ارسال کنید.

همانطور که پلتفرم‌های اپل معمولاً یک توکن دستگاه APN را در هنگام شروع برنامه ارائه می‌دهند، FCM یک توکن ثبت نام را از طریق messaging:didReceiveRegistrationToken: در FIRMessagingDelegate ارائه می‌دهد. FCM SDK یک توکن جدید یا موجود را در هنگام راه‌اندازی اولیه برنامه و هر زمان که توکن به‌روزرسانی یا نامعتبر شود، بازیابی می‌کند. در همه موارد، FCM SDK messaging:didReceiveRegistrationToken: با یک توکن معتبر فراخوانی می‌کند.

توکن ثبت نام ممکن است در موارد زیر تغییر کند:

  • برنامه روی دستگاه جدید بازیابی شده است
  • کاربر برنامه را حذف/نصب مجدد می‌کند
  • کاربر داده‌های برنامه را پاک می‌کند.

نماینده پیام رسانی را تنظیم کنید

برای دریافت توکن‌های ثبت، پروتکل messaging delegate را پیاده‌سازی کنید و پس از فراخوانی [FIRApp configure] ، ویژگی delegate مربوط به FIRMessaging را تنظیم کنید. برای مثال، اگر application delegate شما با پروتکل messaging delegate مطابقت دارد، می‌توانید delegate موجود در application:didFinishLaunchingWithOptions: را روی خودش تنظیم کنید.

سویفت 

Messaging.messaging().delegate = self

هدف-سی 

[FIRMessaging messaging].delegate = self;

واکشی توکن ثبت نام فعلی

توکن‌های ثبت‌نام از طریق متد messaging:didReceiveRegistrationToken: ارسال می‌شوند. این متد معمولاً یک بار در هر برنامه‌ای که با توکن ثبت‌نام شروع می‌شود، فراخوانی می‌شود. وقتی این متد فراخوانی می‌شود، زمان ایده‌آل برای موارد زیر است:

  • اگر توکن ثبت نام جدید است، آن را به سرور برنامه خود ارسال کنید.
  • توکن ثبت نام را در موضوعات مشترک کنید. این فقط برای اشتراک‌های جدید یا برای موقعیت‌هایی که کاربر برنامه را دوباره نصب کرده است، لازم است.

شما می‌توانید توکن را مستقیماً با استفاده از token(completion:) بازیابی کنید. اگر بازیابی توکن به هر نحوی با شکست مواجه شود، یک خطای غیر تهی (non null) نمایش داده می‌شود.

سویفت 

Messaging.messaging().token { token, error in
  if let error = error {
    print("Error fetching FCM registration token: \(error)")
  } else if let token = token {
    print("FCM registration token: \(token)")
    self.fcmRegTokenMessage.text  = "Remote FCM registration token: \(token)"
  }
}

هدف-سی 

[[FIRMessaging messaging] tokenWithCompletion:^(NSString *token, NSError *error) {
  if (error != nil) {
    NSLog(@"Error getting FCM registration token: %@", error);
  } else {
    NSLog(@"FCM registration token: %@", token);
    self.fcmRegTokenMessage.text = token;
  }
}];

شما می‌توانید از این روش در هر زمانی برای دسترسی به توکن به جای ذخیره آن استفاده کنید.

نظارت بر به‌روزرسانی توکن

برای اینکه هر زمان توکن به‌روزرسانی شد، مطلع شوید، یک delegate مطابق با پروتکل message delegate ارائه دهید. مثال زیر delegate را ثبت کرده و متد delegate مناسب را اضافه می‌کند:

سویفت 

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")

  let dataDict: [String: String] = ["token": fcmToken ?? ""]
  NotificationCenter.default.post(
    name: Notification.Name("FCMToken"),
    object: nil,
    userInfo: dataDict
  )
  // TODO: If necessary send token to application server.
  // Note: This callback is fired at each app startup and whenever a new token is generated.
}

AppDelegate.swift

هدف-سی 

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistrationToken:(NSString *)fcmToken {
    NSLog(@"FCM registration token: %@", fcmToken);
    // Notify about received token.
    NSDictionary *dataDict = [NSDictionary dictionaryWithObject:fcmToken forKey:@"token"];
    [[NSNotificationCenter defaultCenter] postNotificationName:
     @"FCMToken" object:nil userInfo:dataDict];
    // TODO: If necessary send token to application server.
    // Note: This callback is fired at each app startup and whenever a new token is generated.
}
AppDelegate.m

به عنوان یک روش جایگزین، می‌توانید به جای ارائه یک متد delegate، به یک NSNotification با نام kFIRMessagingRegistrationTokenRefreshNotification گوش دهید. ویژگی token همیشه مقدار token فعلی را دارد.

Swizzling غیرفعال است: نگاشت توکن APN و توکن ثبت نام شما

اگر متد swizzling را غیرفعال کرده‌اید، یا در حال ساخت یک برنامه SwiftUI هستید، باید توکن APN خود را به طور صریح به توکن ثبت FCM نگاشت کنید. متد application(_:didRegisterForRemoteNotificationsWithDeviceToken:) را برای بازیابی توکن APN پیاده‌سازی کنید و سپس ویژگی apnsToken مربوط به Messaging را تنظیم کنید:

سویفت 

func application(application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

هدف-سی 

// With "FirebaseAppDelegateProxyEnabled": NO
- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [FIRMessaging messaging].APNSToken = deviceToken;
}

پس از ایجاد توکن ثبت FCM ، می‌توانید با استفاده از همان روش‌هایی که با فعال کردن swizzling انجام می‌شد، به آن دسترسی پیدا کرده و منتظر رویدادهای به‌روزرسانی باشید.

جلوگیری از مقداردهی اولیه خودکار

وقتی یک توکن ثبت FCM ایجاد می‌شود، کتابخانه، شناسه و داده‌های پیکربندی را در Firebase آپلود می‌کند. اگر می‌خواهید ابتدا از کاربران اجازه‌ی ورود صریح بگیرید، می‌توانید با غیرفعال کردن FCM از تولید توکن در زمان پیکربندی جلوگیری کنید. برای انجام این کار، یک مقدار فراداده به Info.plist خود اضافه کنید (نه GoogleService-Info.plist ):

FirebaseMessagingAutoInitEnabled = NO

برای فعال کردن مجدد FCM، می‌توانید یک فراخوانی در زمان اجرا انجام دهید:

سویفت 

Messaging.messaging().autoInitEnabled = true

هدف-سی 

[FIRMessaging messaging].autoInitEnabled = YES;

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

افزونه سرویس اعلان را تنظیم کنید

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

برای افزودن یک افزونه سرویس، وظایف راه‌اندازی مورد نیاز برای تغییر و ارائه اعلان‌ها در APNها را انجام دهید و سپس API کمکی افزونه FCM را در NotificationService.m اضافه کنید. به طور خاص، به جای تکمیل فراخوانی با self.contentHandler(self.bestAttemptContent); آن را با FIRMessaging extensionHelper همانطور که نشان داده شده است، تکمیل کنید: 

@interface NotificationService () <NSURLSessionDelegate>
@property(nonatomic) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property(nonatomic) UNMutableNotificationContent *bestAttemptContent;
@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];

    // Modify the notification content here as you want
    self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]",
    self.bestAttemptContent.title];

  // Call FIRMessaging extension helper API.
  [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent
                                            withContentHandler:contentHandler];

}
...

ارسال پیام اطلاع رسانی

  1. برنامه را روی دستگاه هدف نصب و اجرا کنید. در دستگاه‌های اپل، درخواست اجازه دریافت اعلان‌های از راه دور را بپذیرید.
  2. بررسی کنید که برنامه در پس‌زمینه دستگاه فعال باشد.
  3. در کنسول فایربیس، صفحه پیام‌رسانی (Messaging) را باز کنید.
  4. اگر این اولین پیام شماست، گزینه «ایجاد اولین کمپین» را انتخاب کنید.
    1. پیام‌های اعلان فایربیس و سپس ایجاد را انتخاب کنید.
  5. در غیر این صورت، در برگه کمپین‌ها ، کمپین جدید و سپس اعلان‌ها را انتخاب کنید.
  6. متن پیام را وارد کنید.
  7. از پنل سمت راست، گزینه ارسال پیام آزمایشی را انتخاب کنید.
  8. در فیلدی با عنوان «افزودن یک توکن ثبت نام FCM ، توکن ثبت نام خود را وارد کنید.
  9. آزمون را انتخاب کنید.

پس از انتخاب Test ، دستگاه کلاینت مورد نظر، با برنامه در پس‌زمینه، باید اعلان را دریافت کند.

برای اطلاع از نحوه‌ی ارسال پیام به برنامه‌ی خود، به داشبورد گزارش‌دهی FCM مراجعه کنید که تعداد پیام‌های ارسالی و باز شده در دستگاه‌های اپل و اندروید را ثبت می‌کند.

مراحل بعدی

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