HTML5 푸시 알림(HTML5 Push Notification)


html5 알림 플랫폼을 사용하면 세계 어디에 있든 Chrome 또는 Firefox에 푸시 알림을 받을 수 있습니다. html5는 안드로이드에서 크롬과 파이어 폭스도 지원하는데, 이는 네이티브 앱 없이도 네이티브 앱과 같은 연동을 가능하게 합니다.

iOS에서는 HTML5 푸시 알림이 작동하지 않습니다.

GCM 설정 옵션은 더이상 사용되지 않으며 2019 년 5 월 작동이 중지되었습니다. https://developers.google.com/cloud-messaging/faq를 참조하십시오. 이 플랫폼을 처음 설치하는 경우 VAPID 설정 단계를 수행하십시오. 현재 설치를 GCM에서 VAPID 설정으로 마이그레이션하려면 아래 지침을 따르십시오. 처음 3 단계를 건너뛰고 4 단계에서 기존 프로젝트를 계속 진행할 수 있습니다. 또한 html5_push_registrations.conf를 삭제하고 re-enable the notifications in your browser해야합니다.

설정

이 플랫폼을 활성화하려면 configuration.yaml 파일에 다음 줄을 추가하십시오 :

# Example configuration.yaml entry
notify:
  - platform: html5
    name: NOTIFIER_NAME
    vapid_pub_key: YOUR_PUBLIC_KEY
    vapid_prv_key: YOUR_PRIVATE_KEY
    vapid_email: YOUR_EMAIL

Or

# Example configuration.yaml entry. 
# Warning: this option will be deprecated soon!
notify:
  - platform: html5
    name: NOTIFIER_NAME
    gcm_api_key: YOUR_API_KEY
    gcm_sender_id: YOUR_SENDER_ID

Configuration Variables

name

(string)(Optional)

Setting the optional parameter name allows multiple notifiers to be created. The notifier will bind to the service notify.NOTIFIER_NAME.

Default value:

notify

vapid_pub_key

(string)(Required)

The VAPID public key generated by Google (this is the key that is immediately visible under “webpush certificates”), see configuring the platform.

vapid_prv_key

(string)(Required)

The VAPID private key generated by Google, see configuring the platform.

vapid_email

(string)(Required)

The e-mail account associated with your Firebase project, see configuring the platform.

gcm_api_key

(string)(Required)

The API Server key provided to you by Google for Google Cloud Messaging (GCM).

gcm_sender_id

(string)(Required)

The sender ID provided to you by Google for Google Cloud Messaging (GCM).

요구 사항

html5 플랫폼은 다음 요구 사항이 모두 충족되는 경우에만 작동할 수 있습니다.

  • 모든 데스크톱 플랫폼, ChromeOS 또는 Android에서 Chrome 및/또는 Firefox를 사용하고 있습니다.
  • 홈어시스턴트 인스턴스는 HTTPS를 통해 네트워크 외부에서 액세스할 수 있거나 홈어시스턴트가 사용하는 도메인에서 Domain Name Verification Method을 수행할 수 있습니다.
  • 프록시를 사용하는 경우 푸시 알림을 등록하거나 등록 취소하려면 HTTP 기본 인증을 해제해야합니다. 나중에 다시 활성화할 수 있습니다.
  • Hass.io를 실행하지 않으면 pywebpush가 설치되어 있어야합니다. libffi-dev,libpython-dev, libssl-devpywebpush보다 먼저 설치해야합니다 (즉, pywebpush는 자동으로 설치되지 않습니다).
  • Home Assistant에 SSL/TLS를 설정했습니다. 예를 들어 홈어시스턴트 앞에서 NGINX를 실행할 수 있지만 홈어시스턴트에서 설정할 필요는 없습니다. 인증서는 신뢰할 수 있어야합니다 (즉, 자체 서명하지 않아야 함).
  • 브라우저에서 알림 권한을 기꺼이 수락합니다.

플랫폼 설정

  1. HTTPS (see docs)를 통해 네트워크 외부에서 접속가능한 Home Assistant에 액세스하거나 Home Assistant가 사용하는 도메인에서 다른 Domain Name Verification Method을 수행할 수 있는지 확인하십시오.
  2. https://console.cloud.google.com/home/dashboard에서 새 프로젝트를 만듭니다. 이 프로젝트는 나중에 Firebase로 가져옵니다. (또는 4 단계에서 프로젝트를 만들 수도 있습니다)
  3. https://console.cloud.google.com/apis/credentials/domainverification으로 이동하여 Google Webmaster Central/Search Console을 통해 도메인을 확인합니다 - see below
  4. 도메인이 확인되면 https://console.firebase.google.com으로 이동하여 Google 프로젝트 가져 오기를 선택하고 생성한 프로젝트를 선택하십시오.
  5. 그런 다음 왼쪽 상단의 톱니바퀴를 클릭하고 “Project settings”을 선택하십시오.
  6. ‘Cloud Messaging’탭을 선택하십시오.
  7. 페이지 하단의 웹설정 목록에서 새 키 페어를 생성하십시오. 개인 키를 보려면 오른쪽에있는 세 개의 점과 ‘Show private key’를 클릭하십시오.

브라우저 설정

이미 플랫폼을 설정했다고 가정합니다.

  1. Open Home Assistant in Chrome or Firefox.
  2. Load profile page by clicking on the badge next to the Home Assistant title in the sidebar. Assuming you have met all the requirements above then you should see a new slider for Push Notifications. If the slider is greyed out, ensure you are viewing Home Assistant via its external HTTPS address. If the slider is not visible, ensure you are not in the user configuration (Sidebar, Configuration, Users, View User).
  3. Slide it to the on position.
  4. Name the device you’re using in the alert that appears.
  5. Within a few seconds you should be prompted to allow notifications from Home Assistant.
  6. Assuming you accept, that’s all there is to it!

Note: If you aren’t prompted for a device name when enabling notifications, 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.

테스트하기

이전 테스트가 성공적으로 완료되고 브라우저가 등록되었다고 가정하면 다음과 같이 알림을 테스트할 수 있습니다.

  1. Open Home Assistant in Chrome or Firefox.
  2. Open the sidebar and click the Services button at the bottom (shaped like a remote control), located below the Developer Tools.
  3. From the Services dropdown, search for your HTML5 notify service (e.g., notify.NOTIFIER_NAME) and select it.
  4. In the Service Data text box enter: {"message":"hello world"}, then press the CALL SERVICE button.
  5. If everything worked you should see a popup notification.

사용법

html5 플랫폼은 표준 통지 페이로드(standard notify payload)를 수용합니다. 그러나 페이로드에서 제어할 수 있는 특수 기능도 내장되어 있습니다.

액션(Actions)

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)는 callback events에 다시 전송됩니다.

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

태그(Tag)

기본적으로 전송된 모든 알림(notification)에는 임의로 생성된 UUID (v4)가 tag 또는 고유 식별자로 설정되어 있습니다. 태그는 특정 대상이 아닌 알림에 대해 고유합니다. 알림 페이로드에 고유 태그를 전달하면 동일한 태그로 다른 알림를 보내서 알림를 교체할 수 있습니다. 다음과 같이 ‘태그’를 제공할 수 있습니다.

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

알림에 태그를 추가하는 예. 동일한 태그가 있는 알림이 이미 있으면 새 알림을 만들지 않습니다.

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

대상(Targets)

알림 페이로드에 target 매개 변수를 제공하지 않으면 html5_push_registrations.conf에 나열된 모든 등록된 Target으로 알림이 전송됩니다. 다음과 같이 target 매개 변수를 제공할 수 있습니다.

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

target은 다음과 같이 Target의 문자열 배열이 될 수도 있습니다.

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

재정의(Overrides)

data 사전(dictionary)에서 여기에 나열된 매개 변수를 전달할 수 있습니다. Chrome은 아이콘의 최대 크기가 320x320 픽셀이고 최대 badge 크기는 96x96 픽셀이며 작업 버튼의 최대 아이콘 크기는 128x128 픽셀임을 지정합니다.

URL

다음과 같이 데이터 사전(dictionary)에 url을 넣어 알림을 클릭할 때 열고자하는 URL을 제공할 수 있습니다.

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

URL이나 작업이 제공되지 않으면 알림과 상호작용하면 브라우저에서 홈어시스턴트가 열립니다. 상대 URL을 사용하여 홈어시스턴트를 참조할 수 있습니다. 즉, /maphttps://192.168.1.2:8123/map으로 바뀝니다.

TTL and Priority

최신 Android 버전에서는 보다 강력한 배터리 최적화 기능이 도입되었으므로 기본적으로 알림은 전화가 활성화된 경우에만 전달됩니다. 옵션 TTL 및 priority는 사용자가 이러한 문제를 해결하도록 도와줍니다. TTL의 기본값은 86400s이고 priority는 normal입니다. 우선 순위를 normal 혹은 high으로 설정할 수 있습니다. TTL은 임의의 정수 값입니다.

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

해제(Dismiss)

다음과 같이 html5.dismiss 서비스를 사용하여 알림을 해제할 수 있습니다.

{
  "target": ["my phone"],
  "data": {
    "tag": "notification_tag"
  }
}

대상(target)이 제공되지 않으면 모두 해제됩니다. 태그가 제공되지 않으면 모든 알림이 해제됩니다.

알림 이벤트 자동화

단일 푸시 알림의 수명(lifespan) 동안 홈어시스턴트는 자동화를 작성하는데 사용할 수 있는 몇가지 다른 이벤트를 이벤트 버스로 생성합니다.

일반적인 이벤트 페이로드 매개 변수는 다음과 같습니다. :

Parameter Description
action The action key that you set when sending the notification of the action clicked. Only appears in the clicked event.
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, image, lang, renotify, requireInteraction, tag, timestamp, vibrate).
tag The unique identifier of the notification. Can be overridden when sending a notification to allow for replacing existing notifications.
target The target that this notification callback describes.
type The type of event callback received. Can be received, clicked or closed.

target 매개 변수를 사용하여 단일 target 에 대한 자동화를 작성할 수 있습니다. 세분성을 높이려면 actiontarget을 함께 사용하여 대상이 어떤 액션을 클릭했는지에 따라 특정 작업을 수행하는 자동화를 작성하십시오.

받은 이벤트(received event)

장치에서 알림을 받으면 html5_notification.received라는 이벤트가 나타납니다.

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

clicked event

알림 또는 알림 액션 버튼을 클릭하면 html5_notification.clicked라는 이벤트가 나타납니다. 클릭한 액션 버튼은 event_data에서 action으로 이용 가능합니다.

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

or

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

닫힌 이벤트(closed event)

알림이 닫히면 html5_notification.closed라는 이벤트가 나타납니다.

- alias: HTML5 push notification clicked
  trigger:
    platform: 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;

도메인 확인(Verify your domain)

이 구성 요소를 설정하는 동안 Google Webmaster Central/Search Console을 사용하여 도메인 소유권을 확인해야하는 경우 다음 단계를 따르십시오.

  1. Enter your domain and add /local at the end, e.g., https://example.com:8123/local
  2. Select HTML file verification and download the google*.html file.
  3. Create a directory named www in your Home Assistant configuration directory (/config/ share from Samba add-on).
  4. Place the downloaded google*.html file in the www directory.
  5. RESTART Home Assistant. This is important!
  6. 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.
  7. Go back to Google Webmaster Central/Search Console and proceed with the verification.