You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: source/_components/notify.html5.markdown
+32-66Lines changed: 32 additions & 66 deletions
Original file line number
Diff line number
Diff line change
@@ -12,17 +12,15 @@ ha_category: Notifications
12
12
ha_release: 0.27
13
13
---
14
14
15
-
The `html5` notification platform enables you to receive push notifications to
16
-
Chrome or Firefox, no matter where you are in the world. `html5` also supports
17
-
Chrome and Firefox on Android, which enables native-app-like integrations
18
-
without actually needing a native app.
15
+
The `html5` notification platform enables you to receive push notifications to Chrome or Firefox, no matter where you are in the world. `html5` also supports Chrome and Firefox on Android, which enables native-app-like integrations without actually needing a native app.
19
16
20
17
<pclass='note'>
21
18
HTML5 push notifications **do not** work on iOS.
22
19
</p>
23
20
24
-
To enable this platform,
25
-
add the following lines to your `configuration.yaml` file:
21
+
## {% linkable_title Configuration %}
22
+
23
+
To enable this platform, add the following lines to your `configuration.yaml` file:
26
24
27
25
```yaml
28
26
# Example configuration.yaml entry
@@ -51,23 +49,23 @@ gcm_sender_id:
51
49
52
50
### {% linkable_title Getting ready for Chrome %}
53
51
54
-
1. Make sure you can access your Home Assistant installation from outside your network over https ([see docs](/docs/configuration/remote/)).
52
+
1. Make sure you can access your Home Assistant installation from outside your network over HTTPS ([see docs](/docs/configuration/remote/)).
55
53
2. Create a new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard).
56
54
3. Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain via Google Webmaster Central / Search Console - [instructions](#verify-your-domain).
57
-
4. With the domain verified, go to [https://console.firebase.google.com](https://console.firebase.google.com), select import Google project, and select the project you created.
55
+
4. With the domain verified, go to [https://console.firebase.google.com](https://console.firebase.google.com), select import Google project and select the project you created.
58
56
5. Then, click the cogwheel on top left and select "Project settings".
59
57
6. Select 'Cloud Messaging' tab, listed beneath Project Credentials will be your 152 character 'Server Key' and 12 digit ID 'Sender ID' you need for configuring this component.
60
58
61
59
#### {% linkable_title Verify your domain %}
62
60
63
-
Follow these steps to verify domain ownership with Google Webmaster Central / Search Console:
64
-
1. Enter your domain and add **'/local'** at the end, ie. https://example.com:8123/local
61
+
Follow these steps to verify domain ownership with Google Webmaster Central/Search Console:
62
+
1. Enter your domain and add `/local` at the end, e.g., `https://example.com:8123/local`
65
63
2. Select HTML file verification and download the google*.html file.
66
-
2. Create a directory named "www" in your Home Assistant configuration directory (/config share from Samba add-on).
67
-
3. Place the downloaded google*.html file in the "www" directory.
68
-
4. RESTART Home Assistant - this is important!
69
-
5. Verify the file can be accessed in the browser, ie. **https://example.com:8123/local/google123456789.html** (change filename) - you should see a plain text message saying "google-site-verification: ..." - if you see "404: Not Found" or something else, retry the above steps.
70
-
6. Go back to Google Webmaster Central / Search Console and proceed with the verification.
64
+
2. Create a directory named `www` in your Home Assistant configuration directory (`/config/` share from Samba add-on).
65
+
3. Place the downloaded `google*.html` file in the `www` directory.
66
+
4. RESTART Home Assistant. **This is important!**
67
+
5. Verify the file can be accessed in the browser, e.g., **https://example.com:8123/local/google123456789.html** (change filename). You should see a plain text message saying "google-site-verification: ...". If you see "404: Not Found" or something else, retry the above steps.
68
+
6. Go back to Google Webmaster Central/Search Console and proceed with the verification.
71
69
72
70
### {% linkable_title Requirements %}
73
71
@@ -76,11 +74,10 @@ The `html5` platform can only function if all of the following requirements are
76
74
* You are using Chrome and/or Firefox on any desktop platform, ChromeOS or Android.
77
75
* Your Home Assistant instance is exposed to the world.
78
76
* If using a proxy, HTTP basic authentication must be off for registering or unregistering for push notifications. It can be re-enabled afterwards.
79
-
* If you don't run Hass.io: `pywebpush` must be installed. `libffi-dev`, `libpython-dev`, and `libssl-dev` must be installed prior to `pywebpush` (i.e. `pywebpush` probably won't automatically install).
80
-
* You have configured SSL for your Home Assistant. It doesn't need to be configured in Home Assistant though, i.e. you can be running [NGINX](/ecosystem/nginx/) in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e. not self signed).
77
+
* If you don't run Hass.io: `pywebpush` must be installed. `libffi-dev`, `libpython-dev` and `libssl-dev` must be installed prior to `pywebpush` (i.e. `pywebpush` probably won't automatically install).
78
+
* You have configured SSL/TLS for your Home Assistant. It doesn't need to be configured in Home Assistant though, e.g., you can be running [NGINX](/ecosystem/nginx/) in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e. not self signed).
81
79
* You are willing to accept the notification permission in your browser.
82
80
83
-
84
81
### {% linkable_title Setting up %}
85
82
86
83
Assuming you have already added the platform to your configuration:
@@ -92,7 +89,6 @@ Assuming you have already added the platform to your configuration:
92
89
5. Assuming you accept, that's all there is to it!
93
90
6. (Optional, but highly recommended!) Open the `html5_push_registrations.conf` file in your configuration directory. You will see a new entry for the browser you just added. Rename it from `unnamed device` to a name of your choice, which will make it easier to identify later. _Do not change anything else in this file!_ You need to restart Home Assistant after making any changes to the file.
94
91
95
-
96
92
### {% linkable_title Testing %}
97
93
98
94
Assuming the previous test completed successfully and your browser was registered, you can test the notification as follows:
@@ -103,18 +99,14 @@ Assuming the previous test completed successfully and your browser was registere
103
99
4. In the Service Data text box enter: {"message":"hello world"}, then press the CALL SERVICE button.
104
100
5. If everything worked you should see a popup notification.
105
101
106
-
107
102
### {% linkable_title Usage %}
108
103
109
-
The `html5` platform accepts a standard notify payload. However, there are also
110
-
some special features built in which you can control in the payload.
104
+
The `html5` platform accepts a standard notify payload. However, there are also some special features built in which you can control in the payload.
111
105
112
106
113
107
#### {% linkable_title Actions %}
114
108
115
-
Chrome supports notification actions,
116
-
which are configurable buttons that arrive with the notification and can cause
117
-
actions on Home Assistant to happen when pressed. You can send up to 2 actions.
109
+
Chrome supports notification actions, which are configurable buttons that arrive with the notification and can cause actions on Home Assistant to happen when pressed. You can send up to 2 actions.
118
110
119
111
```yaml
120
112
message: Anne has arrived home
@@ -129,10 +121,7 @@ data:
129
121
130
122
#### {% linkable_title Data %}
131
123
132
-
Any parameters that you pass in the notify payload that aren't valid for use in
133
-
the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `image`,
134
-
`lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be
135
-
sent back to you in the [callback events](#automating-notification-events).
124
+
Any parameters that you pass in the notify payload that aren't valid for use in the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `image`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be sent back to you in the [callback events](#automating-notification-events).
136
125
137
126
```yaml
138
127
title: Front door
@@ -143,23 +132,18 @@ data:
143
132
144
133
#### {% linkable_title Tag %}
145
134
146
-
By default, every notification sent has a randomly generated UUID (v4) set as
147
-
its _tag_ or unique identifier. The tag is unique to the notification, _not_ to
148
-
a specific target. If you pass your own tag in the notify payload you can
149
-
replace the notification by sending another notification with the same tag.
150
-
You can provide a `tag` like so:
135
+
By default, every notification sent has a randomly generated UUID (v4) set as its _tag_ or unique identifier. The tag is unique to the notification, _not_ to a specific target. If you pass your own tag in the notify payload you can replace the notification by sending another notification with the same tag. You can provide a `tag` like so:
151
136
152
137
```yaml
153
138
title: Front door
154
139
message: The front door is open
155
140
data:
156
141
tag: front-door-notification
157
-
158
142
```
159
143
160
-
Example of adding a tag to your notification. This won't create new notification
161
-
if there already exists one with the same tag.
144
+
Example of adding a tag to your notification. This won't create new notification if there already exists one with the same tag.
162
145
146
+
{% raw %}
163
147
```yaml
164
148
- alias: Push/update notification of sensor state with tag
165
149
trigger:
@@ -168,11 +152,12 @@ if there already exists one with the same tag.
168
152
action:
169
153
service: notify.html5
170
154
data_template:
171
-
message: "Last known sensor state is {% raw %}{{ states('sensor.sensor') }}{% endraw %}."
155
+
message: "Last known sensor state is {{ states('sensor.sensor') }}."
in the `data` dictionary. Please note, Chrome specifies that the maximum size
204
-
for an icon is 320px by 320px, the maximum `badge` size is 96px by 96px and the
205
-
maximum icon size for an action button is 128px by 128px.
186
+
You can pass any of the parameters listed [here](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/showNotification#Parameters) in the `data` dictionary. Please note, Chrome specifies that the maximum size for an icon is 320px by 320px, the maximum `badge` size is 96px by 96px and the maximum icon size for an action button is 128px by 128px.
206
187
207
188
#### {% linkable_title URL %}
208
189
209
-
You can provide a URL to open when the notification is clicked by putting `url`
210
-
in the data dictionary like so:
190
+
You can provide a URL to open when the notification is clicked by putting `url` in the data dictionary like so:
211
191
212
192
```yaml
213
193
title: Front door
@@ -216,15 +196,11 @@ data:
216
196
url: https://google.com
217
197
```
218
198
219
-
If no URL or actions are provided, interacting with a notification will open
220
-
your Home Assistant in the browser. You can use relative URLs to refer to Home
221
-
Assistant, i.e. `/map` would turn into `https://192.168.1.2:8123/map`.
199
+
If no URL or actions are provided, interacting with a notification will open your Home Assistant in the browser. You can use relative URLs to refer to Home Assistant, i.e. `/map` would turn into `https://192.168.1.2:8123/map`.
During the lifespan of a single push notification,
226
-
Home Assistant will emit a few different events to the event bus which you can
227
-
use to write automations against.
203
+
During the lifespan of a single push notification, Home Assistant will emit a few different events to the event bus which you can use to write automations against.
228
204
229
205
Common event payload parameters are:
230
206
@@ -236,10 +212,7 @@ Common event payload parameters are:
236
212
| `target` | The target that this notification callback describes. |
237
213
| `type` | The type of event callback received. Can be `received`, `clicked` or `closed`. |
238
214
239
-
You can use the `target` parameter to write automations against a single
240
-
`target`. For more granularity,
241
-
use `action` and `target` together to write automations which will do specific
242
-
things based on what target clicked an action.
215
+
You can use the `target` parameter to write automations against a single `target`. For more granularity, use `action` and `target` together to write automations which will do specific things based on what target clicked an action.
243
216
244
217
#### {% linkable_title received event %}
245
218
@@ -255,9 +228,7 @@ notification is received on the device.
255
228
256
229
#### {% linkable_title clicked event %}
257
230
258
-
You will receive an event named `html5_notification.clicked` when the
259
-
notification or a notification action button is clicked.
260
-
The action button clicked is available as `action` in the `event_data`.
231
+
You will receive an event named `html5_notification.clicked` when the notification or a notification action button is clicked. The action button clicked is available as `action` in the `event_data`.
261
232
262
233
```yaml
263
234
- alias: HTML5 push notification clicked
@@ -279,8 +250,7 @@ or
279
250
280
251
#### {% linkable_title closed event %}
281
252
282
-
You will receive an event named `html5_notification.closed` when the
283
-
notification is closed.
253
+
You will receive an event named `html5_notification.closed` when the notification is closed.
284
254
285
255
```yaml
286
256
- alias: HTML5 push notification clicked
@@ -291,10 +261,7 @@ notification is closed.
291
261
292
262
### {% linkable_title Making notifications work with NGINX proxy %}
293
263
294
-
If you use [NGINX](/ecosystem/nginx/) as a proxy with authentication in front of
295
-
your Home Assistant instance,
296
-
you may have trouble with receiving events back to Home Assistant.
297
-
It's because of authentication token that cannot be passed through the proxy.
264
+
If you use [NGINX](/ecosystem/nginx/) as a proxy with authentication in front of your Home Assistant instance, you may have trouble with receiving events back to Home Assistant. It's because of authentication token that cannot be passed through the proxy.
298
265
299
266
To solve the issue put additional location into your nginx site's configuration:
0 commit comments