2025.3.4
首页 ▸ Integrations ▸

HTML5 推送通知

html5 通知 integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 使您能够接收发送到 Chrome 或 Firefox 的推送通知，无论您身在世界何处。html5 还支持 Android 上的 Chrome 和 Firefox，这使得无需本地应用即可实现类似本地应用的集成。

Important

HTML5 推送通知 不支持 iOS 16.4 以下版本。

要求

只有满足以下所有要求时，html5 平台才能正常运行：

  • 您正在任何桌面平台、ChromeOS 或 Android 上使用 Chrome 和/或 Firefox。或者，您已将 Home Assistant 实例添加到 iOS 16.4 或更高版本的主屏幕。
  • 您的 Home Assistant 实例可以通过 HTTPS 从外部网络访问，或者可以在 Home Assistant 使用的域上执行替代的 域名验证方法。
  • 如果使用代理，则必须禁用 HTTP 基本身份验证以注册或注销推送通知。之后可以重新启用。
  • 如果您不运行 Hass.io：必须安装 pywebpush。在安装 pywebpush 之前，必须安装 libffi-dev、libpython-dev 和 libssl-dev（即，pywebpush 可能不会自动安装）。
  • 您已为 Home Assistant 配置了 SSL/TLS。它不需要在 Home Assistant 中配置，例如，您可以在 Home Assistant 前运行 NGINX，这仍然可以正常工作。证书必须是可信的（即，不是自签名的）。
  • 您愿意在浏览器中接受通知权限。

配置

要将 HTML5 推送通知 integration 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

手动配置步骤

如果上述 My 按钮不起作用，您也可以手动执行以下步骤：

  • 浏览到您的 Home Assistant 实例。

  • 转到 设置 > 设备与服务。

  • 在右下角，选择 Add Integration 按钮。

  • 从列表中选择 HTML5 推送通知。

  • 按照屏幕上的说明完成设置。

设置您的浏览器

假设您已经配置了平台：

  1. 在 Chrome、Firefox 或 iOS 中的 webapp 中打开 Home Assistant，并通过单击上面的 My 按钮或单击侧边栏中 Home Assistant 标题旁边的徽章加载配置文件页面。假设您已满足上述所有要求，那么您应该会看到一个新的推送通知滑块。如果滑块变灰，请确保您通过其外部 HTTPS 地址查看 Home Assistant（并且您已在 Home Assistant 中配置了 notify HTML5 集成）。如果滑块不可见，请确保您不在用户配置中（侧边栏，配置，用户，查看用户）。
  2. 打开滑块，并在出现的警报中命名您正在使用的设备。
  3. 几秒钟内，您应该会收到允许 Home Assistant 通知的提示。
  4. 假设您接受了，就是这样！

注意： 如果在启用通知时未提示您输入设备名称，请打开配置目录中的 html5_push_registrations.conf 文件。您将看到一个新条目，表示您刚刚添加的浏览器。将其从 unnamed device 重命名为您选择的名称，这将使以后更容易识别。不要更改此文件中的任何其他内容！ 您需要在对文件进行任何更改后重新启动 Home Assistant。

测试

假设上一个测试成功完成并且您的浏览器已注册，您可以按如下方式测试通知：

  1. 点击上面的 My 按钮。
  2. 从 Actions 下拉列表中，搜索您的 HTML5 通知操作 (notify.html5) 并选择它。
  3. 在数据文本框中输入：{"message":"hello world"}，然后选择 Perform action 按钮。
  4. 如果一切正常，您应该会看到一个弹出通知。

用法

html5 平台接受标准通知负载。但是，内置了一些特殊功能，您可以在负载中控制这些功能。

操作

Chrome 支持通知操作，这些操作是随通知一起到达的可配置按钮，按下时可以在 Home Assistant 上执行操作。您最多可以发送 2 个操作。

message: Anne has arrived home
data:
  actions:
    - action: open
      icon: "/static/icons/favicon-192x192.png"
      title: Open Home Assistant
    - action: open_door
      title: Open door

数据

您在通知负载中传递的任何参数，如果在 HTML5 通知中无效（actions、badge、body、dir、icon、image、lang、renotify、requireInteraction、tag、timestamp、vibrate、priority、ttl、silent），将会在回调事件中发送回给您。

title: Front door
message: The front door is open
data:
  my-custom-parameter: front-door-open

标签

默认情况下，发送的每个通知都有一个随机生成的 UUID (v4) 作为其 tag 或唯一标识符。标签对于通知是唯一的，而不是特定目标。如果您在通知负载中传递自己的标签，则可以通过发送具有相同标签的另一个通知来替换通知。您可以这样提供 tag：

title: Front door
message: The front door is open
data:
  tag: front-door-notification

为通知添加标签的示例。如果已经存在具有相同标签的通知，则不会创建新通知。

  - alias: "Push/update notification of sensor state with tag"
    triggers:
      - trigger: state
        entity_id: sensor.sensor
    actions:
      - action: notify.html5
        data:
          message: "Last known sensor state is {{ states('sensor.sensor') }}."
          data:
            tag: "notification-about-sensor"

目标

如果您在通知负载中未提供 target 参数，则会将通知发送到 html5_push_registrations.conf 中列出的所有注册目标。您可以这样提供 target 参数：

title: Front door
message: The front door is open
target: unnamed device

target 也可以是目标的字符串数组，如下所示：

title: Front door
message: The front door is open
target:
  - unnamed device
  - unnamed device 2

覆盖

您可以在 data 字典中传递此处列出的任何参数。请注意，Chrome 指定图标的最大尺寸为 320px x 320px，badge 的最大尺寸为 96px x 96px，操作按钮的最大图标尺寸为 128px x 128px。

URL

您可以通过在数据字典中放置 url 来提供点击通知时要打开的 URL，如下所示：

title: Front door
message: The front door is open
data:
  url: https://google.com

如果未提供 URL 或操作，则与通知交互将会在浏览器中打开您的 Home Assistant。您可以使用相对 URL 来引用 Home Assistant，即 /map 将变成 https://192.168.1.2:8123/map。

TTL 和优先级

较新的 Android 版本引入了更强的电池优化，因此默认情况下，通知仅在手机唤醒时传递。 TTL 和优先级选项尝试帮助用户解决这些问题。TTL 的默认值为 86400s，优先级为 normal。 您可以将优先级设置为 normal 或 high。TTL 是任何整数值。

title: Front door
message: The front door is open
data:
  ttl: 86400
  priority: high

取消

您可以使用 html5.dismiss 操作来取消通知，如下所示：

target: ['my phone']
data:
  tag: notification_tag

如果未提供目标，则会为所有目标取消通知。 如果未提供标签，则会取消所有通知。

自动化通知事件

在单个推送通知的生命周期内，Home Assistant 将向事件总线发出一些不同的事件，您可以使用这些事件编写自动化。

常见的事件负载参数是：

参数 描述
action 您在发送通知时设置的 action 键，表示点击的操作。仅出现在 clicked 事件中。
data 您在通知负载中最初传递的数据字典，减去添加到 HTML5 通知中的任何参数（actions、badge、body、dir、icon、image、lang、renotify、requireInteraction、tag、timestamp、vibrate、silent）。
tag 通知的唯一标识符。发送通知时可以覆盖，以允许替换现有通知。
target 此通知回调描述的目标。
type 接收到的事件回调类型。可以是 received、clicked 或 closed。

您可以使用 target 参数编写针对单个 target 的自动化。为了更细粒度的控制，请同时使用 action 和 target 编写自动化，这将根据哪个目标点击了操作来执行特定操作。

received 事件

当设备上接收到通知时，您将收到一个名为 html5_notification.received 的事件。

- alias: "HTML5 push notification received and displayed on device"
  triggers:
    - trigger: event
      event_type: html5_notification.received

clicked 事件

当点击通知或通知操作按钮时，您将收到一个名为 html5_notification.clicked 的事件。点击的操作按钮在 event_data 中可用，作为 action。

- alias: "HTML5 push notification clicked"
  triggers:
    - trigger: event
      event_type: html5_notification.clicked

或

- alias: "HTML5 push notification action button clicked"
  triggers:
    - trigger: event
      event_type: html5_notification.clicked
      event_data:
        action: open_door

closed 事件

当通知关闭时，您将收到一个名为 html5_notification.closed 的事件。

- alias: "HTML5 push notification clicked"
  triggers:
    - trigger: event
      event_type: html5_notification.closed

使通知与 NGINX 代理一起工作

如果您使用 NGINX 作为代理并在 Home Assistant 实例前进行身份验证，您可能会遇到接收返回 Home Assistant 的事件的问题。这是因为无法通过代理传递身份验证令牌。

要解决此问题，请在您的 NGINX 站点配置中添加额外的位置：

location /api/notify.html5/callback {
    if ($http_authorization = "") { return 403; }
    allow all;
    proxy_pass http://localhost:8123;
    proxy_set_header Host $host;
    proxy_redirect http:// https://;
}

此规则检查请求是否具有 Authorization HTTP 头，并绕过 htpasswd（如果您使用了一个）。

如果即使有上述规则，您仍然遇到问题，请尝试添加以下代码：

    proxy_set_header Authorization $http_authorization;
    proxy_pass_header Authorization;

相关主题