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

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

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

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

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

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

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

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

کلید اصالت‌سنجی 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 شناسه نصب Firebase را بااستفاده از روش messaging:didReceiveRegistration: مربوط به FIRMessagingDelegate ارائه می‌دهد، تغییرات شناسه نصب Firebase را به‌طور خودکار پایش می‌کند، و وقتی تغییری شناسایی شد، روش را با شناسه نصب Firebase جدید فراخوانی می‌کند. توصیه می‌کنیم FID را به‌طور منظم بازیابی و بارگذاری کنید زیرا FID می‌تواند پس‌از راه‌اندازی اولیه تغییر کند.

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

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

FirebaseMessagingInstallationIdEnabled = YES

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

برای دریافت شناسه‌های نصب Firebase، پروتکل نماینده پیام‌رسانی را پیاده‌سازی کنید و ویژگی delegate مربوط به FIRMessaging را پس‌از فراخوانی [FIRApp configure] تنظیم کنید. برای مثال، اگر نماینده برنامه شما با پروتکل نماینده پیام‌رسانی مطابقت دارد، می‌توانید نماینده را روی 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 به‌طور خودکار نمونه برنامه را با 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 هستید، باید به‌طور صریح کد APN خود را به «شناسه‌های نصب Firebase» (FID) نگاشت کنید. روش 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;
}

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

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

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

همان‌طور که پلاتفرم‌های Apple معمولاً یک کد APNs دستگاه را در شروع برنامه ارائه می‌دهند، FCM یک کد ثبت را ازطریق روش messaging:didReceiveRegistrationToken: FIRMessagingDelegate ارائه می‌دهد. کیت توسعه نرم‌افزار 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 گوش دهید. ویژگی توکن همیشه مقدار توکن فعلی را دارد.

Swizzling غیرفعال است: درحال نگاشت کردن کد 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
• ارسال پیام به موضوعات