From 12007466b4592dc3f88deda8d570a1bca0ff920f Mon Sep 17 00:00:00 2001 From: samowens Date: Tue, 6 Sep 2016 13:33:56 +0100 Subject: [PATCH 1/2] added documentation for APNS --- source/_components/notify.apns.markdown | 56 +++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 source/_components/notify.apns.markdown diff --git a/source/_components/notify.apns.markdown b/source/_components/notify.apns.markdown new file mode 100644 index 000000000000..d4d4ef5b4e51 --- /dev/null +++ b/source/_components/notify.apns.markdown @@ -0,0 +1,56 @@ +--- +layout: page +title: "APNS" +description: "Instructions how to add APNS notifications to Home Assistant." +date: 2015-06-22 10:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Notifications +ha_release: pre 0.7 +--- + + +The `APNS` platform uses the Apple Push Notification service (APNS) to deliver notifications from Home Assistant. + +To use the APNS service you will need an apple developer account +and you will need to create an App to receive push notifications. +For more information see the apple developer documentation. + +```yaml +# Example configuration.yaml entry +notify: + name: NOTIFIER_NAME + platform: apns + sandbox: true or false + cert_file: cert_file.pem +``` + +Configuration variables: + +- **name** (*Required*): The name of the notifier. The notifier will bind to the service `notify.NOTIFIER_NAME`. +- **sandbox** (*Optional*): If true notifications will be sent to the sandbox (test) notification service. +- **cert_file** (*Required*): The certificate to use to authenticate with the APNS service. + + The APNS platform will register two services, `notify.NOTIFIER_NAME` and `apns.NOTIFIER_NAME`. + +### apns.NOTIFIER_NAME + +This service will register device id's with home assistant. In order to receive a notification a device must be registered. The app on the device can use this service to send an id to Home Assistant during startup, the id will be stored in the [NOTIFIER_NAME]_apns.yaml. + +See didRegisterForRemoteNotificationsWithDeviceToken in the apple developer documentation for more information about how to obtain a device id. + +### notify.NOTIFIER_NAME + +This service will send messages to a registered device. The following parameters can be used: + +- **message**: The message to send + +- **target**: The desired state of the device, only devices that match the state will receive messages. To enable state tracking a registered device must have a `tracking_device_id` attribute added to the [NOTIFIER_NAME]_apns.yaml file. If this id matches a device in known_devices.yaml the device state will be tracked. + +- **data**: + * **badge**: The number to display as the badge of the app ic + * **sound**: The name of a sound file in the app bundle or in the Library/Sounds folder. + * **category**: Provide this key with a string value that represents the identifier property of the UIMutableUserNotificationCategory + * **content_available**: Provide this key with a value of 1 to indicate that new content is available. From 2126cdf65672641a3f3763b6c438a1beb81df387 Mon Sep 17 00:00:00 2001 From: samowens Date: Thu, 8 Sep 2016 22:40:18 +0100 Subject: [PATCH 2/2] added link to Apple docs and corrected date --- source/_components/notify.apns.markdown | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/_components/notify.apns.markdown b/source/_components/notify.apns.markdown index d4d4ef5b4e51..64889a0851d8 100644 --- a/source/_components/notify.apns.markdown +++ b/source/_components/notify.apns.markdown @@ -2,13 +2,12 @@ layout: page title: "APNS" description: "Instructions how to add APNS notifications to Home Assistant." -date: 2015-06-22 10:00 +date: 2016-09-05 23:00 sidebar: true comments: false sharing: true footer: true ha_category: Notifications -ha_release: pre 0.7 --- @@ -30,16 +29,16 @@ notify: Configuration variables: - **name** (*Required*): The name of the notifier. The notifier will bind to the service `notify.NOTIFIER_NAME`. -- **sandbox** (*Optional*): If true notifications will be sent to the sandbox (test) notification service. +- **sandbox** (*Optional*): If true notifications will be sent to the sandbox (test) notification service. Default false. - **cert_file** (*Required*): The certificate to use to authenticate with the APNS service. The APNS platform will register two services, `notify.NOTIFIER_NAME` and `apns.NOTIFIER_NAME`. ### apns.NOTIFIER_NAME -This service will register device id's with home assistant. In order to receive a notification a device must be registered. The app on the device can use this service to send an id to Home Assistant during startup, the id will be stored in the [NOTIFIER_NAME]_apns.yaml. +This service will register device id's with home assistant. In order to receive a notification a device must be registered. The app on the device can use this service to send an id to Home Assistant during startup, the id will be stored in `[NOTIFIER_NAME]_apns.yaml`. -See didRegisterForRemoteNotificationsWithDeviceToken in the apple developer documentation for more information about how to obtain a device id. +See didRegisterForRemoteNotificationsWithDeviceToken in the [Apple developer documentation](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/#//apple_ref/occ/intfm/UIApplicationDelegate/application:didRegisterForRemoteNotificationsWithDeviceToken:) for more information about how to obtain a device id. ### notify.NOTIFIER_NAME @@ -47,7 +46,7 @@ This service will send messages to a registered device. The following parameters - **message**: The message to send -- **target**: The desired state of the device, only devices that match the state will receive messages. To enable state tracking a registered device must have a `tracking_device_id` attribute added to the [NOTIFIER_NAME]_apns.yaml file. If this id matches a device in known_devices.yaml the device state will be tracked. +- **target**: The desired state of the device, only devices that match the state will receive messages. To enable state tracking a registered device must have a `tracking_device_id` attribute added to the `[NOTIFIER_NAME]_apns.yaml` file. If this id matches a device in known_devices.yaml the device state will be tracked. - **data**: * **badge**: The number to display as the badge of the app ic