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

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

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

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

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

روش جایگزینی در Firebase Cloud Messaging

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

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

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

1. در کنسول Firebase، به settings تنظیمات > کلی بروید. سپس، روی زبانه «پیام‌رسانی ابری» کلیک کنید.
2. در کلید اصالت‌سنجی APNs در بخش پیکربندی برنامه 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 را در موضوعات مشترک کنید.

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.");
}];
    

«جایگزینی» غیرفعال است: نگاشتن نشان APNs و 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، می‌توانید به آن دسترسی داشته باشید و بااستفاده از همان روش‌هایی که هنگام فعال بودن «جایگزینی» استفاده می‌کنید، رویدادهای بازآوری را بشنوید.

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

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

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

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

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

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

برای دریافت نشان‌های ثبت، پروتکل نماینده پیام‌رسانی را پیاده‌سازی کنید و پس‌از فراخوانی [FIRApp configure]، دارایی delegate مربوط به FIRMessaging را تنظیم کنید. برای مثال، اگر نماینده برنامه شما با پروتکل نماینده پیام‌رسانی مطابقت داشته باشد، می‌توانید نماینده را در 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 هستید، باید کد APNs خود را به‌طور صریح به کد ثبت FCM نگاشت کنید. متد application(_:didRegisterForRemoteNotificationsWithDeviceToken:) را برای بازیابی کردن نشان APNs پیاده‌سازی کنید، و سپس ویژگی 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 است، باید افزونه سرویس اعلان اضافه کنید. این افزونه به دستگاه‌ها اجازه می‌دهد تصاویر ارائه‌شده در محتوای اعلان را نمایش دهند. اگر قصد ندارید در اعلان‌ها تصویر ارسال کنید، می‌توانید از این مرحله رد شوید.

برای افزودن افزونه سرویس، تکالیف راه‌اندازی لازم را برای اصلاح و ارائه اعلان‌ها در APNs انجام دهید، و سپس FCM extension helper API را در 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 & Engagement (عملیات توسعه و تعامل) > Messaging (پیام‌رسانی) بروید

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

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

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

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

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

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

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

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

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

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

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

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

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

مراحل بعدی

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

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