شروع به کار با «پیام‌رسانی ابریِ Firebase» در برنامه‌های پلاتفرم Apple

این راهنما نحوه شروع به کار با Firebase Cloud Messaging در برنامه‌های مشتری پلاتفرم Apple (مانند iOS) را توضیح می‌دهد تا بتوانید پیام‌ها را به‌طور مطمئن ارسال کنید.

برای برنامه‌های کارخواه Apple، می‌توانید ازطریق رابط Firebase Cloud Messaging APNs، اعلان و داده‌بار تا ۴۰۹۶ بایت دریافت کنید.

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

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

روش تغییر پیاده‌سازی در Firebase Cloud Messaging

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

کلید اصالت‌سنجی APNs را بارگذاری کنید

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

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

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

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
MigratedSnippets.swift

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

[application registerForRemoteNotifications];
ObjCMigratedSnippets.m

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

به‌طور پیش‌فرض، FCM کیت توسعه نرم‌افزار نمونه برنامه را با FCM ثبت می‌کند و شناسه نصب Firebase (FID) را برای نمونه برنامه مشتری در راه‌اندازی برنامه برمی‌گرداند. مشابه با کد APNs دستگاه، این FID به شما امکان می‌دهد اعلان‌های هدف‌یابی‌شده را به هر نمونه خاصی از برنامه‌تان ارسال کنید.

همان‌طور که پلاتفرم‌های Apple معمولاً یک کد APNs دستگاه را در راه‌اندازی برنامه ارائه می‌دهند، FCM یک FID برای هدف‌یابی اعلان‌ها ارائه می‌دهد. ‫FCM SDK بااستفاده از روش FIRMessagingDelegate messaging:didReceiveRegistration: «شناسه تبلیغات» را ارائه می‌کند، به‌طور خودکار تغییرات «شناسه تبلیغات» را پایش می‌کند، و وقتی تغییری تشخیص داده می‌شود، روش را با «شناسه تبلیغات» جدید فرا می‌خواند. توصیه می‌کنیم که به‌طور منظم FID را بازیابی و بارگذاری کنید زیرا FID می‌تواند پس‌از راه‌اندازی اولیه تغییر کند.

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

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

FirebaseMessagingInstallationIdEnabled = YES

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

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

روش didReceiveRegistration را پیاده‌سازی کنید

پس‌از تکمیل ثبت‌نام، نمونه‌های برنامه بااستفاده از FID هدف‌یابی می‌شوند. برای دریافت FID پس‌از ثبت‌نام، روش messaging:didReceiveRegistration: را پیاده‌سازی کنید. این روش معمولاً یک‌بار در هر راه‌اندازی برنامه با FID فراخوانی می‌شود. وقتی این روش فراخوانی می‌شود، می‌توانید کنش‌های زیر را انجام دهید:

• اگر FID را به سرورتان ارسال نکرده‌اید، یا FID را اخیراً ارسال کرده‌اید، آن را به سرور برنامه‌تان ارسال کنید.
• اگر اشتراک جدید است یا کاربر برنامه را دوباره نصب کرده است، FID را در موضوعات مشترک کنید.

func messaging(_ messaging: Messaging, didReceiveRegistration installationId: String?) {
  print("Firebase Installation ID: \(String(describing: installationId))")
  // Note: This callback is fired at each app startup.

  if let installationId = installationId {
    // Send the Firebase Installation ID to your app server.
    sendRegistrationToServer(installationId)
  }
}
    

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistration:(nullable NSString *)installationId {
  NSLog(@"Firebase Installation ID: %@", installationId);
  // Note: This callback is fired at each app startup.

  if (installationId != nil) {
    // Send the Firebase Installation ID to your app server.
    [self sendRegistrationToServer:installationId];
  }
}
    

وقتی مقداردهی اولیه خودکار غیرفعال است، به‌صورت دستی ثبت کنید

اگر مقداردهی اولیه خودکار را غیرفعال کرده باشید، FCM SDK نمونه برنامه را هنگام راه‌اندازی برنامه به‌طور خودکار در FCM ثبت نخواهد کرد. باید register را هنگام راه‌اندازی برنامه فراخوانی کنید تا ثبت‌نام و تحویل FID ازطریق روش messaging:didReceiveRegistration: راه‌اندازی شود:

// Trigger manual registration if auto-initialization is turned off.
Messaging.messaging().register { error in
    if let error = error {
        // Handle the error
        print("Failed registering: \(error)")
        return
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    print("Successfully registered.")
}
    

// Trigger manual registration if auto-initialization is turned off.
[[FIRMessaging messaging] registerWithCompletion:^(NSError * _Nullable error) {
    if (error) {
        // Handle the error
        NSLog(@"Failed registering: %@", error);
        return;
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    NSLog(@"Successfully registered.");
}];
    

Swizzling غیرفعال شد: درحال نگاشت کردن توکن APN و FID شما

اگر روش جایگزینی را غیرفعال کرده‌اید یا درحال ساختن برنامه SwiftUI هستید، باید به‌طور صریح کد APNs خود را به «شناسه‌های نصب Firebase» (FID) نگاشت کنید. برای بازیابی کردن رمز APNs، متد application(_:didRegisterForRemoteNotificationsWithDeviceToken:) را پیاده‌سازی کنید، و سپس خصوصیت 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;
}

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

دسترسی به کد ثبت (منسوخ)

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

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

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

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

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

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

درحال واکشی کد ثبت‌نام فعلی

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

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

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

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

[[FIRMessaging messaging] tokenWithCompletion:^(NSString * _Nullable token, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error fetching the remote FCM registration token: %@", error);
  } else {
    NSLog(@"Remote FCM registration token: %@", token);
    NSString* message =
      [NSString stringWithFormat:@"FCM registration token: %@", token];
    // display message
    NSLog(@"%@", message);
  }
}];

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

نظارت بر بازآوری کردن ژتون

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

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")
  // TODO: If necessary send token to application server.
  // Note: This callback is fired at each app startup and whenever a new token is generated.
}
MigratedSnippets.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.
}
ObjCMigratedSnippets.m

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

«ترکیب» غیرفعال است: کد APNs و کد ثبت شما را نگاشت می‌کنیم

اگر روش تغییر پیاده‌سازی را غیرفعال کرده‌اید یا درحال ساختن برنامه 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;

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

راه‌اندازی افزونه سرویس اعلان

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

برای افزودن افزونه سرویس، کارهای راه‌اندازی لازم را برای اصلاح و ارائه اعلان‌ها در APN انجام دهید، سپس میانای برنامه‌سازی کاربردی کمکی افزونه 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. برنامه را در دستگاه هدف نصب و اجرا کنید. در دستگاه‌های Apple، درخواست اجازه برای دریافت اعلان‌های راه دور را بپذیرید.

2. بررسی کنید که برنامه در پس‌زمینه دستگاه باشد.

3. در کنسول Firebase، به DevOps و تعامل > پیام‌رسانی بروید

4. پویشی ایجاد کنید.

   • اگر این اولین پیام شما است:

     1. ایجاد اولین پویش را انتخاب کنید.

     2. پیام‌های اعلان Firebase و سپس ایجاد را انتخاب کنید.

   • اگر قبلاً پویش ایجاد کرده‌اید:

     1. در برگه پویش‌ها، پویش جدید را انتخاب کنید.

     2. روی اعلان‌ها کلیک کنید.

5. نوشتار پیام را وارد کنید.

6. ارسال پیام آزمایشی را از قاب سمت راست انتخاب کنید.

7. در فیلد دارای برچسب افزودن شناسه نصب Firebase یا FCM کد ثبت‌نام، کد ثبت‌نامتان را وارد کنید.

8. آزمایش را انتخاب کنید.

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

برای دریافت اطلاعات آماری درباره تحویل پیام به برنامه‌تان، به داشبورد DevOps و تعامل > پیام‌رسانی > گزارش‌ها در کنسول Firebase بروید. این داشبورد تعداد پیام‌های ارسال‌شده و بازشده در دستگاه‌های Apple و Android را به‌همراه داده‌های مربوط به «ظهورها» (اعلان‌های دیده‌شده توسط کاربران) برای برنامه‌های Android ثبت می‌کند.

مراحل بعدی

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

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