chrome.gcm

refresh date: 2026-09-25 robots: noindex

说明

使用 chrome.gcm 可让应用和扩展程序通过 Firebase Cloud Messaging (FCM) 收发消息。

权限

gcm

属性

MAX_MESSAGE_SIZE

消息中所有键值对的大小上限（以字节为单位）。

值

4096

方法

register()

Promise 
chrome.gcm.register(
  senderIds: string[],
  callback?: function,
): Promise<string>

向 FCM 注册应用。注册 ID 将由 callback 返回。如果使用相同的 senderIds 列表再次调用 register，系统将返回相同的注册 ID。

参数

  • senderIds

    字符串[]

    允许向应用发送消息的服务器 ID 列表。它应包含至少 1 个且不超过 100 个发送者 ID。

  • callback

    函数可选

    callback 参数如下所示： 

    (registrationId: string) => void

    • registrationId

      字符串

      FCM 为应用分配的注册 ID。

返回

  • Promise<string>

    Chrome 116 及更高版本

    在注册完成后解析。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

send()

Promise 
chrome.gcm.send(
  message: object,
  callback?: function,
): Promise<string>

根据消息内容发送消息。

参数

  • 私信

    对象

    通过 FCM 发送给另一方的消息。

    • 数据

      对象

      要发送到服务器的消息数据。不区分大小写的 goog. 和 google 以及区分大小写的 collapse_key 不允许用作键前缀。所有键值对的总和不应超过 gcm.MAX_MESSAGE_SIZE。

    • destinationId

      字符串

      Google API 控制台分配的消息接收服务器的 ID。

    • messageId

      字符串

      消息的 ID。在应用范围内，每条消息的 ID 必须是唯一的。如需有关选择和处理 ID 的建议，请参阅 Cloud Messaging 文档。

    • timeToLive

      number 可选

      消息的存留时间（以秒为单位）。如果无法在该时间内发送消息，系统会引发 onSendError 事件。存留时间为 0 表示应立即发送消息，如果无法立即发送，则发送失败。存留时间的默认值为 86,400 秒（1 天），最大值为 2,419,200 秒（28 天）。

  • callback

    函数可选

    callback 参数如下所示： 

    (messageId: string) => void

    • messageId

      字符串

      发出回调的消息的 ID。

返回

  • Promise<string>

    Chrome 116 及更高版本

    在消息成功排队等待发送后解析。如果发生错误，promise 将被拒绝。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

unregister()

Promise 
chrome.gcm.unregister(
  callback?: function,
): Promise<void>

从 FCM 取消注册应用。

参数

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 116 及更高版本

    在取消注册完成后解析。如果 promise 未拒绝，则表示取消注册成功。

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onMessage

chrome.gcm.onMessage.addListener(
  callback: function,
)

在通过 FCM 收到消息时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (message: object) => void

    • 私信

      对象

      • collapseKey

        字符串 可选

        消息的折叠键。如需了解详情，请参阅不可折叠消息和可折叠消息。

      • 数据

        对象

        消息数据。

      • 来自

        字符串 可选

        发送消息的发件人。

onMessagesDeleted

chrome.gcm.onMessagesDeleted.addListener(
  callback: function,
)

当 FCM 服务器必须删除应用服务器发送到应用的消息时触发。如需详细了解如何处理此事件，请参阅消息的生命周期。

参数

  • callback

    函数

    callback 参数如下所示： 

    () => void

onSendError

chrome.gcm.onSendError.addListener(
  callback: function,
)

在无法向 FCM 服务器发送消息时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (error: object) => void

    • 错误

      对象

      • 详细信息

        对象

        与错误相关的其他详细信息（如有）。

      • errorMessage

        字符串

        描述问题的出错提示。

      • messageId

        字符串 可选

        出现此错误的邮件的 ID（如果错误与特定邮件相关）。