Skip to content

Commit 9d16d40

Browse files
robbiet480robbiet480
committed
Initial notify.HTML5 docs
1 parent c674e44 commit 9d16d40

File tree

2 files changed

+213
-0
lines changed

2 files changed

+213
-0
lines changed

‎source/_components/notify.html5.markdown

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
layout: page
3+
title: "HTML5"
4+
description: "Instructions how to use the HTML5 push API from Home Assistant."
5+
date: 2016-08-16 20:18
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
logo: html5.png
11+
ha_category: Notifications
12+
ha_release: 0.27
13+
---
14+
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.
16+
17+
To enable this platform, add the following lines to your `configuration.yaml` file:
18+
19+
```yaml
20+
# Example configuration.yaml entry
21+
notify:
22+
name: HTML5
23+
platform: html5
24+
gcm_api_key: 'gcm-sender-key'
25+
gcm_sender_id: 'gcm-sender-id'
26+
```
27+
28+
Configuration variables:
29+
30+
- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`.
31+
- **gcm_api_key** (*Required if pushing to Chrome*): The API key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome.
32+
- **gcm_sender_id** (*Required if pushing to Chrome*): The sender ID provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome.
33+
34+
### {% linkable_title Getting ready for Chrome %}
35+
36+
Google has [a handy guide](https://developers.google.com/web/fundamentals/getting-started/push-notifications/step-04) that goes into great detail about how to set up for pushing to Chrome. Once you have your GCM API Key and Sender ID in hand, plug them into your configuration as described above.
37+
38+
### {% linkable_title Requirements %}
39+
40+
The `html5` platform can only function if all of the following requirements are met:
41+
42+
* You are using Chrome and/or Firefox on any desktop platform, ChromeOS or Android.
43+
* Your Home Assistant instance is exposed to the world.
44+
* 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 in front of Home Assistant and this will still work.
45+
* You are willing to accept the notification permission in your browser.
46+
47+
### {% linkable_title Setting up %}
48+
49+
Assuming you have already added the platform to your configuration:
50+
51+
1. Open Home Assistant in Chrome or Firefox.
52+
2. Assuming you have met all the [requirements](#requirements) above, you should see a new slider in the sidebar labeled Push Notifications.
53+
3. Slide it to the on position.
54+
4. Within a few seconds you should be prompted to allow notifications from Home Assistant.
55+
5. Assuming you accept, that's all there is to it!
56+
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.
57+
58+
### {% linkable_title Usage %}
59+
60+
The `html5` platform accepts a standard notify payload. However, there are also some special features built in which you can control in the payload.
61+
62+
#### {% linkable_title Actions %}
63+
64+
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](https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&sq=package:chromium&dr=CSs&l=14).
65+
66+
```json
67+
{
68+
"message": "Anne has arrived home",
69+
"data": {
70+
"actions": [
71+
{
72+
"action": "open",
73+
"icon": "/static/icons/favicon-192x192.png"
74+
"title": "Open Home Assistant"
75+
},
76+
{
77+
"action": "open_door",
78+
"title": "Open door"
79+
}
80+
]
81+
}
82+
}
83+
```
84+
85+
#### {% linkable_title Data %}
86+
87+
Any parameters that you pass in the notify payload that aren't valid for use in the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be sent back to you in the [callback events](http://localhost:4000/components/notify.html5/#automating-notification-events).
88+
89+
```json
90+
{
91+
"title": "Front door",
92+
"message": "The front door is open",
93+
"data": {
94+
"my-custom-parameter": "front-door-open"
95+
}
96+
}
97+
```
98+
99+
#### {% linkable_title Tag %}
100+
101+
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:
102+
103+
```json
104+
{
105+
"title": "Front door",
106+
"message": "The front door is open",
107+
"data": {
108+
"tag": "front-door-notification"
109+
}
110+
}
111+
```
112+
113+
#### {% linkable_title Targets %}
114+
115+
If you do not provide a `target` parameter in the notify payload a notification will be sent to all registered targets as listed in `html5_push_registrations.conf`. You can provide a `target` parameter like so:
116+
117+
```json
118+
{
119+
"title": "Front door",
120+
"message": "The front door is open",
121+
"target": "unnamed device"
122+
}
123+
```
124+
125+
`target` can also be a string array of targets like so:
126+
127+
```json
128+
{
129+
"title": "Front door",
130+
"message": "The front door is open",
131+
"target": ["unnamed device", "unnamed device 2"]
132+
}
133+
```
134+
135+
#### {% linkable_title Overrides %}
136+
137+
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](https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&sq=package:chromium&dr=CSs&l=21) 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.
138+
139+
#### {% linkable_title URL %}
140+
141+
You can provide a URL to open when the notification is clicked by putting `url` in the data dictionary like so:
142+
143+
```json
144+
{
145+
"title": "Front door",
146+
"message": "The front door is open",
147+
"data": {
148+
"url": "https://google.com"
149+
}
150+
}
151+
```
152+
153+
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`.
154+
155+
### {% linkable_title Automating notification events %}
156+
157+
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.
158+
159+
Common event payload parameters are:
160+
161+
| Parameter | Description |
162+
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
163+
| `action` | The `action` key that you set when sending the notification of the action clicked. Only appears in the `clicked` event. |
164+
| `data` | The data dictionary you originally passed in the notify payload, minus any parameters that were added to the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`). |
165+
| `tag` | The unique identifier of the notification. Can be overridden when sending a notification to allow for replacing existing notifications. |
166+
| `target` | The target that this notification callback describes. |
167+
| `type` | The type of event callback received. Can be `received`, `clicked` or `closed`. |
168+
169+
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.
170+
171+
#### {% linkable_title received event %}
172+
173+
You will receive an event named `html5_notification.received` when the notification is received on the device.
174+
175+
```yaml
176+
- alias: HTML5 push notification received and displayed on device
177+
trigger:
178+
platform: event
179+
event_type: html5_notification.received
180+
```
181+
182+
#### {% linkable_title clicked event %}
183+
184+
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`.
185+
186+
```yaml
187+
- alias: HTML5 push notification clicked
188+
trigger:
189+
platform: event
190+
event_type: html5_notification.clicked
191+
```
192+
193+
or
194+
195+
```yaml
196+
- alias: HTML5 push notification action button clicked
197+
trigger:
198+
platform: event
199+
event_type: html5_notification.clicked
200+
event_data:
201+
action: open_door
202+
```
203+
204+
#### {% linkable_title closed event %}
205+
206+
You will receive an event named `html5_notification.closed` when the notification is closed.
207+
208+
```yaml
209+
- alias: HTML5 push notification clicked
210+
trigger:
211+
platform: event
212+
event_type: html5_notification.closed
213+
```

‎source/images/supported_brands/html5.png

2.17 KB
Loading

0 commit comments

Comments
 (0)