Gửi tin nhắn đến nhiều thiết bị trên các nền tảng của Apple

Để nhắm mục tiêu một thông báo đến nhiều thiết bị, hãy sử dụng tính năng Thông báo theo chủ đề. Tính năng này cho phép bạn gửi tin nhắn đến nhiều thiết bị đã chọn nhận một chủ đề cụ thể.

Hướng dẫn này tập trung vào việc gửi thông báo theo chủ đề từ máy chủ ứng dụng của bạn bằng SDK quản trị hoặc API REST cho FCM, đồng thời nhận và xử lý thông báo đó trong ứng dụng của Apple. Trang này liệt kê tất cả các bước để thực hiện việc này, từ thiết lập đến xác minh. Trang này có thể bao gồm các bước bạn đã hoàn tất nếu bạn đã thiết lập ứng dụng khách của Apple cho FCM hoặc đã thực hiện các bước để Gửi tin nhắn đầu tiên.

Thêm Firebase vào dự án Apple

Phần này trình bày các thao tác mà bạn có thể đã hoàn thành nếu đã bật các tính năng khác của Firebase cho ứng dụng. Riêng đối với FCM, bạn cần phải tải khoá xác thực APN lên và đăng ký thông báo từ xa.

Điều kiện tiên quyết

  • Cài đặt như sau:

    • Xcode 14.1 trở lên

  • Hãy đảm bảo dự án của bạn đáp ứng các yêu cầu sau:

    • Dự án của bạn phải nhắm đến các phiên bản nền tảng sau đây trở lên:
      • iOS 11
      • macOS 10.13
      • tvOS 12
      • watchOS 6

  • Thiết lập một thiết bị Apple thực để chạy ứng dụng của bạn và hoàn thành những thao tác sau:

    • Lấy Khoá xác thực thông báo đẩy của Apple cho Tài khoản nhà phát triển Apple của bạn.
    • Bật thông báo đẩy trong XCode trong phần App > Capabilities (Ứng dụng > Khả năng).

Nếu chưa có dự án Xcode và chỉ muốn dùng thử một sản phẩm của Firebase, bạn có thể tải một trong các mẫu bắt đầu nhanh của chúng tôi xuống.

Tạo một dự án Firebase

Trước khi có thể thêm Firebase vào ứng dụng Apple, bạn cần tạo một dự án Firebase để kết nối với ứng dụng của mình. Hãy xem bài viết Tìm hiểu các dự án Firebase để tìm hiểu thêm về các dự án Firebase.

Đăng ký ứng dụng của bạn với Firebase

Để sử dụng Firebase trong ứng dụng của Apple, bạn cần đăng ký ứng dụng của mình với dự án Firebase. Việc đăng ký ứng dụng thường được gọi là "thêm" ứng dụng vào dự án.

  1. Truy cập vào bảng điều khiển của Firebase.

  2. Ở giữa trang tổng quan về dự án, hãy nhấp vào biểu tượng iOS+ để bắt đầu quy trình thiết lập.

    Nếu bạn đã thêm một ứng dụng vào dự án Firebase, hãy nhấp vào Add app (Thêm ứng dụng) để hiển thị các lựa chọn về nền tảng.

  3. Nhập mã gói của ứng dụng vào trường mã gói.

  4. (Không bắt buộc) Nhập thông tin khác về ứng dụng: Biệt hiệu của ứng dụng và Mã cửa hàng ứng dụng.

  5. Nhấp vào Đăng ký ứng dụng.

Thêm tệp cấu hình Firebase

  1. Nhấp vào Download GoogleService-Info.plist xuống để nhận tệp cấu hình Firebase Apple nền tảng (GoogleService-Info.plist).

  2. Di chuyển tệp cấu hình vào gốc của dự án Xcode. Nếu được nhắc, hãy chọn thêm tệp cấu hình vào tất cả mục tiêu.

Nếu có nhiều mã nhận dạng gói trong dự án, bạn phải liên kết từng mã nhận dạng gói với một ứng dụng đã đăng ký trong bảng điều khiển của Firebase để mỗi ứng dụng đều có thể có tệp GoogleService-Info.plist riêng.

Thêm Firebase SDK vào ứng dụng của bạn

Sử dụng Trình quản lý gói Swift để cài đặt và quản lý các phần phụ thuộc Firebase.

  1. Trong Xcode, khi dự án ứng dụng của bạn đang mở, hãy chuyển đến File > Add Packages (Tệp > Thêm gói).
  2. Khi được nhắc, hãy thêm kho lưu trữ SDK nền tảng Apple của Firebase:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. Chọn thư viện Giải pháp gửi thông báo qua đám mây của Firebase.
  4. Thêm cờ -ObjC vào mục Cờ trình liên kết khác trong chế độ cài đặt bản dựng của mục tiêu.
  5. Để có trải nghiệm tối ưu với Giải pháp gửi thông báo qua đám mây của Firebase, bạn nên bật Google Analytics trong dự án Firebase và thêm Firebase SDK cho Google Analytics vào ứng dụng của mình. Bạn có thể chọn thư viện không thu thập IDFA hoặc thư viện có thu thập IDFA.
  6. Khi hoàn tất, Xcode sẽ tự động bắt đầu phân giải và tải các phần phụ thuộc của bạn xuống ở chế độ nền.

Tải khoá xác thực APN lên

Tải khoá xác thực APN của bạn lên Firebase. Nếu bạn chưa có khoá xác thực APN, hãy nhớ tạo một khoá trong Trung tâm thành viên dành cho nhà phát triển của Apple.

  1. Bên trong dự án của bạn trong bảng điều khiển của Firebase, hãy chọn biểu tượng bánh răng, chọn Cài đặt dự án, sau đó chọn thẻ Gửi thông báo qua đám mây.

  2. Trong khoá xác thực ANG ở bên dưới phần Cấu hình ứng dụng iOS, hãy nhấp vào nút Tải lên.

  3. Duyệt đến vị trí bạn đã lưu khoá, chọn khoá đó rồi nhấp vào Open (Mở). Thêm mã khoá của khoá (có trong Trung tâm thành viên dành cho nhà phát triển của Apple) rồi nhấp vào Tải lên.

Khởi chạy Firebase trong ứng dụng của bạn

Bạn cần thêm mã khởi chạy Firebase vào ứng dụng của mình. Nhập mô-đun Firebase và định cấu hình một bản sao được chia sẻ như sau:

  1. Nhập mô-đun FirebaseCore trong UIApplicationDelegate, cũng như bất kỳ mô-đun Firebase nào khác mà đại diện ứng dụng của bạn sử dụng. Ví dụ: Cách sử dụng Cloud Firestore và Xác thực:

    SwiftUI

    import SwiftUI
import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Swift

    import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Objective-C

    @import FirebaseCore;
@import FirebaseFirestore;
@import FirebaseAuth;
// ...
  2. Định cấu hình một thực thể dùng chung của FirebaseApp trong phương thức application(_:didFinishLaunchingWithOptions:) của uỷ quyền ứng dụng:

    SwiftUI

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Swift

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Objective-C

    // Use Firebase library to configure APIs
[FIRApp configure];
  3. Nếu đang sử dụng SwiftUI, bạn phải tạo một ứng dụng uỷ quyền và đính kèm ứng dụng đó vào cấu trúc App thông qua UIApplicationDelegateAdaptor hoặc NSApplicationDelegateAdaptor. Bạn cũng phải tắt tính năng uỷ quyền ứng dụng. Để biết thêm thông tin, hãy xem hướng dẫn về SwiftUI.

    SwiftUI

    @main
struct YourApp: App {
  // register app delegate for Firebase setup
  @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

Đăng ký nhận thông báo từ xa

Khi khởi động hoặc tại thời điểm mong muốn trong quy trình đăng ký của ứng dụng, hãy đăng ký thông báo từ xa cho ứng dụng của bạn. Gọi registerForRemoteNotifications như sau:

Swift


UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()

AppDelegate.swift

Objective-C


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

[application registerForRemoteNotifications];
AppDelegate.m

Đăng ký ứng dụng khách theo một chủ đề

Ứng dụng khách có thể đăng ký theo dõi bất kỳ chủ đề hiện có nào hoặc có thể tạo một chủ đề mới. Khi một ứng dụng khách đăng ký một tên chủ đề mới (tên chưa tồn tại cho dự án Firebase của bạn), một chủ đề mới của tên đó sẽ được tạo trong FCM và mọi ứng dụng sau đó có thể đăng ký chủ đề đó.

Để đăng ký một chủ đề, hãy gọi phương thức đăng ký từ luồng chính của ứng dụng (FCM không an toàn cho luồng). Nếu ban đầu yêu cầu đăng ký không thành công, FCM sẽ tự động thử lại. Đối với trường hợp không thể hoàn tất gói thuê bao, gói thuê bao sẽ gửi thông báo lỗi mà bạn có thể phát hiện trong trình xử lý hoàn thành như sau:

Swift

Messaging.messaging().subscribe(toTopic: "weather") { error in
  print("Subscribed to weather topic")
}
ViewController.swift

Objective-C

[[FIRMessaging messaging] subscribeToTopic:@"weather"
                                completion:^(NSError * _Nullable error) {
  NSLog(@"Subscribed to weather topic");
}];
ViewController.m

Lệnh gọi này thực hiện một yêu cầu không đồng bộ đến phần phụ trợ FCM và đăng ký ứng dụng vào chủ đề đã cho. Trước khi gọi subscribeToTopic:topic, hãy đảm bảo rằng phiên bản ứng dụng khách đã nhận được mã thông báo đăng ký qua lệnh gọi lại didReceiveRegistrationToken.

Mỗi lần ứng dụng khởi động, FCM đảm bảo rằng tất cả các chủ đề được yêu cầu đều đã được đăng ký. Để huỷ đăng ký, hãy gọi unsubscribeFromTopic:topic và FCM sẽ huỷ đăng ký khỏi chủ đề ở chế độ nền.

Nhận và xử lý thông báo theo chủ đề

FCM gửi thông điệp theo chủ đề theo cách giống như các thông báo tiếp theo khác.

Triển khai application(_:didReceiveRemoteNotification:fetchCompletionHandler:) như sau:

Swift

func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async
  -> UIBackgroundFetchResult {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired till the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // Messaging.messaging().appDidReceiveMessage(userInfo)

  // Print message ID.
  if let messageID = userInfo[gcmMessageIDKey] {
    print("Message ID: \(messageID)")
  }

  // Print full message.
  print(userInfo)

  return UIBackgroundFetchResult.newData
}

AppDelegate.swift

Objective-C

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired till the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // [[FIRMessaging messaging] appDidReceiveMessage:userInfo];

  // ...

  // Print full message.
  NSLog(@"%@", userInfo);

  completionHandler(UIBackgroundFetchResultNewData);
}
AppDelegate.m

Tạo yêu cầu gửi

Sau khi tạo một chủ đề, bằng cách đăng ký các phiên bản ứng dụng khách với chủ đề ở phía máy khách hoặc thông qua API máy chủ, bạn có thể gửi thông báo đến chủ đề. Nếu đây là lần đầu tiên bạn tạo yêu cầu gửi cho FCM, hãy xem hướng dẫn về môi trường máy chủ và FCM để biết thông tin quan trọng về nền tảng và cách thiết lập.

Trong logic gửi trên phần phụ trợ, hãy chỉ định tên chủ đề mong muốn như sau:

Node.js

// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Tiến hành

// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

Kiến trúc chuyển trạng thái đại diện (REST)

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

Lệnh cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Để gửi thông báo đến một tổ hợp chủ đề, hãy chỉ định một điều kiện (là biểu thức boolean chỉ định các chủ đề mục tiêu). Ví dụ: điều kiện sau đây sẽ gửi thông báo đến các thiết bị đã đăng ký TopicA và TopicB hoặc TopicC:

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

Trước tiên, FCM sẽ đánh giá mọi điều kiện trong dấu ngoặc đơn, sau đó đánh giá biểu thức từ trái sang phải. Trong biểu thức trên, người dùng đăng ký bất kỳ chủ đề nào sẽ không nhận được thông báo. Tương tự như vậy, người dùng không đăng ký TopicA sẽ không nhận được thông báo. Những tổ hợp này nhận được nội dung:

  • TopicA và TopicB
  • TopicA và TopicC

Bạn có thể đưa tối đa 5 chủ đề vào biểu thức có điều kiện.

Để gửi đến một điều kiện:

Node.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Tiến hành

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

Kiến trúc chuyển trạng thái đại diện (REST)

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

Lệnh cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Các bước tiếp theo