ส่งข้อความถึงหัวข้อในแพลตฟอร์ม Apple

FCMการรับส่งข้อความตามหัวข้อช่วยให้คุณส่งข้อความไปยังอุปกรณ์หลายเครื่องที่เลือกใช้หัวข้อหนึ่งๆ ได้ โดยอิงตามรูปแบบการเผยแพร่/การสมัครรับข้อมูล คุณเขียนข้อความหัวข้อได้ตามต้องการ และ FCM จะจัดการการกำหนดเส้นทางและนำส่งข้อความไปยังอุปกรณ์ที่ถูกต้องอย่างน่าเชื่อถือ

ตัวอย่างเช่น ผู้ใช้แอปการคาดการณ์น้ำขึ้นน้ำลงในพื้นที่อาจเลือกรับหัวข้อ "การแจ้งเตือนกระแสน้ำขึ้นน้ำลง" และรับการแจ้งเตือนเกี่ยวกับสภาพการตกปลาน้ำเค็มที่ดีที่สุดในพื้นที่ที่ระบุ ผู้ใช้แอปกีฬาสามารถสมัครรับการอัปเดตอัตโนมัติเกี่ยวกับคะแนนการแข่งขันแบบสดของทีมโปรด

สิ่งที่ควรคำนึงถึงเกี่ยวกับหัวข้อมีดังนี้

  • การรับส่งข้อความตามหัวข้อเหมาะสําหรับเนื้อหา เช่น สภาพอากาศ หรือข้อมูลอื่นๆ ที่เผยแพร่ต่อสาธารณะ
  • ข้อความหัวข้อจะเพิ่มประสิทธิภาพเพื่อการรับส่งข้อมูลแทนเวลาในการตอบสนอง หากต้องการส่งข้อความไปยังอุปกรณ์เครื่องเดียวหรือกลุ่มอุปกรณ์เล็กๆ อย่างปลอดภัยและรวดเร็ว ให้กำหนดเป้าหมายข้อความไปยังโทเค็นการลงทะเบียน ไม่ใช่หัวข้อ
  • หากต้องการส่งข้อความไปยังอุปกรณ์หลายเครื่องต่อผู้ใช้ ให้พิจารณาใช้ การส่งข้อความกลุ่มในอุปกรณ์สำหรับกรณีการใช้งานเหล่านั้น
  • การรับส่งข้อความในหัวข้อรองรับการติดตามแบบไม่จำกัดสำหรับแต่ละหัวข้อ อย่างไรก็ตาม FCM บังคับใช้ขีดจํากัดในขอบเขตต่อไปนี้
    • อินสแตนซ์แอป 1 รายการจะติดตามหัวข้อได้ไม่เกิน 2,000 หัวข้อ
    • หากคุณใช้การนําเข้าแบบเป็นกลุ่มเพื่อสมัครใช้บริการอินสแตนซ์แอป คําขอแต่ละรายการจะจํากัดไว้ที่ 1, 000 อินสแตนซ์แอป
    • ความถี่ของการสมัครใช้บริการใหม่จะจำกัดอัตราต่อโปรเจ็กต์ หากคุณส่งคำขอสมัครใช้บริการมากเกินไปในช่วงเวลาสั้นๆ เซิร์ฟเวอร์ FCM จะตอบกลับด้วย 429 RESOURCE_EXHAUSTED ("ใช้โควต้าเกิน") ลองอีกครั้งโดยใช้ Exponential Backoff

สมัครใช้บริการแอปไคลเอ็นต์ในหัวข้อ

แอปไคลเอ็นต์สามารถสมัครรับหัวข้อที่มีอยู่หรือสร้างหัวข้อใหม่ก็ได้ เมื่อแอปไคลเอ็นต์ติดตามชื่อหัวข้อใหม่ (หัวข้อที่ไม่มีอยู่ในโปรเจ็กต์ Firebase ของคุณ) ระบบจะสร้างหัวข้อใหม่ชื่อนั้นใน FCM และไคลเอ็นต์ทุกรายจะติดตามหัวข้อดังกล่าวได้ในภายหลัง

หากต้องการติดตามหัวข้อ ให้เรียกใช้เมธอดการติดตามจากเธรดหลักของแอปพลิเคชัน (FCM ไม่ปลอดภัยสำหรับเธรด) หากคำขอสมัครใช้บริการไม่สำเร็จในตอนแรก FCM จะลองอีกครั้งโดยอัตโนมัติ ในกรณีที่สมัครใช้บริการไม่สำเร็จ การสมัครใช้บริการจะแสดงข้อผิดพลาดที่คุณจับได้ในตัวแฮนเดิลการเสร็จสิ้นดังที่แสดง

Swift

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

Objective-C

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

การเรียกนี้จะทำคำขอแบบไม่พร้อมกันไปยังแบ็กเอนด์ FCM และสมัครใช้บริการไคลเอ็นต์ในหัวข้อที่ระบุ ก่อนเรียก subscribeToTopic:topic ให้ตรวจสอบว่าอินสแตนซ์แอปไคลเอ็นต์ได้รับโทเค็นการลงทะเบียนผ่าน Callback didReceiveRegistrationToken แล้ว

ทุกครั้งที่แอปเริ่มทำงาน FCM จะตรวจสอบว่าได้ติดตามหัวข้อทั้งหมดที่ขอแล้ว หากต้องการยกเลิกการสมัครรับข้อมูล ให้เรียกใช้ unsubscribeFromTopic:topic แล้ว FCM จะยกเลิกการสมัครรับข้อมูลหัวข้อในเบื้องหลัง

จัดการการสมัครรับหัวข้อในเซิร์ฟเวอร์

Firebase Admin SDK ช่วยให้คุณทํางานพื้นฐานในการจัดการหัวข้อได้จากฝั่งเซิร์ฟเวอร์ เมื่อได้รับโทเค็นการลงทะเบียนแล้ว คุณจะสมัครใช้บริการและยกเลิกการสมัครใช้บริการอินสแตนซ์แอปไคลเอ็นต์ได้หลายรายการพร้อมกันโดยใช้ตรรกะเซิร์ฟเวอร์

คุณสามารถสมัครใช้บริการอินสแตนซ์แอปไคลเอ็นต์กับหัวข้อที่มีอยู่ หรือจะสร้างหัวข้อใหม่ก็ได้ เมื่อคุณใช้ API เพื่อสมัครใช้บริการแอปไคลเอ็นต์กับหัวข้อใหม่ (หัวข้อที่ไม่มีอยู่ในโปรเจ็กต์ Firebase ของคุณ) ระบบจะสร้างหัวข้อใหม่ที่มีชื่อนั้นใน FCM และไคลเอ็นต์ทุกรายจะสมัครใช้บริการหัวข้อดังกล่าวได้ในภายหลัง

คุณสามารถส่งรายการโทเค็นการลงทะเบียนไปยังFirebase Admin SDKวิธีสมัครใช้บริการเพื่อสมัครใช้บริการอุปกรณ์ที่เกี่ยวข้องในหัวข้อได้ ดังนี้

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Subscribe the devices corresponding to the registration tokens to the
// topic.
getMessaging().subscribeToTopic(registrationTokens, topic)
  .then((response) => {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully subscribed to topic:', response);
  })
  .catch((error) => {
    console.log('Error subscribing to topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Subscribe the devices corresponding to the registration tokens to the
// topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were subscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Subscribe the devices corresponding to the registration tokens to the
# topic.
response = messaging.subscribe_to_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were subscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Subscribe the devices corresponding to the registration tokens to the
// topic.
response, err := client.SubscribeToTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were subscribed successfully")

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};

// Subscribe the devices corresponding to the registration tokens to the
// topic
var response = await FirebaseMessaging.DefaultInstance.SubscribeToTopicAsync(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were subscribed successfully");

นอกจากนี้ FCM API สำหรับผู้ดูแลระบบยังช่วยให้คุณยกเลิกการสมัครรับข้อมูลของอุปกรณ์จากหัวข้อได้ด้วยการส่งโทเค็นการลงทะเบียนไปยังเมธอดที่เหมาะสม ดังนี้

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
getMessaging().unsubscribeFromTopic(registrationTokens, topic)
  .then((response) => {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully unsubscribed from topic:', response);
  })
  .catch((error) => {
    console.log('Error unsubscribing from topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().unsubscribeFromTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were unsubscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Unubscribe the devices corresponding to the registration tokens from the
# topic.
response = messaging.unsubscribe_from_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were unsubscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
response, err := client.UnsubscribeFromTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were unsubscribed successfully")

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};

// Unsubscribe the devices corresponding to the registration tokens from the
// topic
var response = await FirebaseMessaging.DefaultInstance.UnsubscribeFromTopicAsync(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were unsubscribed successfully");

เมธอด subscribeToTopic() และ unsubscribeFromTopic() จะแสดงผลเป็นออบเจ็กต์ที่มีคําตอบจาก FCM ประเภทผลลัพธ์มีรูปแบบเดียวกัน ไม่ว่าจะระบุโทเค็นการลงทะเบียนกี่รายการในคำขอ

ในกรณีที่เกิดข้อผิดพลาด (การตรวจสอบสิทธิ์ไม่สำเร็จ โทเค็นหรือหัวข้อไม่ถูกต้อง ฯลฯ) วิธีการเหล่านี้จะทำให้เกิดข้อผิดพลาด ดูรายการรหัสข้อผิดพลาดทั้งหมด รวมถึงคำอธิบายและขั้นตอนการแก้ปัญหาได้ที่ข้อผิดพลาด FCM API ของผู้ดูแลระบบ

รับและจัดการข้อความในหัวข้อ

FCM จะส่งข้อความหัวข้อในลักษณะเดียวกับข้อความดาวน์สตรีมอื่นๆ

ติดตั้งใช้งาน application(_:didReceiveRemoteNotification:fetchCompletionHandler:) ตามที่แสดง

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
}

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);
}

สร้างคำขอส่ง

หลังจากสร้างหัวข้อแล้ว คุณสามารถส่งข้อความไปยังหัวข้อได้ด้วยการสมัครใช้บริการอินสแตนซ์แอปไคลเอ็นต์เพื่อรับหัวข้อที่ฝั่งไคลเอ็นต์หรือผ่าน server API หากนี่เป็นการสร้างคําขอส่งสําหรับ FCM เป็นครั้งแรก ให้ดูคำแนะนำเกี่ยวกับสภาพแวดล้อมเซิร์ฟเวอร์และ FCM เพื่อดูข้อมูลเบื้องต้นและข้อมูลการตั้งค่าที่สําคัญ

ในตรรกะการส่งในแบ็กเอนด์ ให้ระบุชื่อหัวข้อที่ต้องการดังที่แสดง

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);

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)

Go

// 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)

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);

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"
      }
   }
}

คำสั่ง 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

หากต้องการส่งข้อความไปยังชุดค่าผสมของหัวข้อ ให้ระบุเงื่อนไข ซึ่งเป็นนิพจน์บูลีนที่กำหนดหัวข้อเป้าหมาย ตัวอย่างเช่น เงื่อนไขต่อไปนี้จะส่งข้อความไปยังอุปกรณ์ที่สมัครใช้บริการ TopicA และ TopicB หรือ TopicC

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

FCM จะประเมินเงื่อนไขในวงเล็บก่อน แล้วจึงประเมินนิพจน์จากซ้ายไปขวา ในนิพจน์ข้างต้น ผู้ใช้ที่สมัครรับข้อมูลหัวข้อเดียวใดๆ จะไม่ได้รับการแจ้งเตือน ในทำนองเดียวกัน ผู้ใช้ที่ไม่ได้ติดตาม TopicA จะไม่ได้รับการแจ้งเตือน รายการต่อไปนี้จะได้รับเครดิต

  • TopicA และ TopicB
  • TopicA และ TopicC

คุณสามารถใส่หัวข้อได้สูงสุด 5 หัวข้อในนิพจน์เงื่อนไข

หากต้องการส่งไปยังเงื่อนไข

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);

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)

Go

// 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)

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);

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",
    }
  }
}

คำสั่ง 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

ขั้นตอนถัดไป