Continuing conversation from home-assistant/android#125

3D touch as an interaction is all but deprecated and not included in more recent models. It is replaced by haptic touch which is essentially touch and hold/long touch. We should update accordingly

Hello,

I want to link my local HA install from a landing page in my internal network. Is there a single link that will try to open an installed mobile app whether ios or android, but if it doesn't exist, fall back to the web location? I think it's a fairly common use case, so it would be worth documenting if it were possible.

Too difficult to find the links now :)

This should be a pretty quick fix.

On this page, it says:

You may also use a device_tracker for the latitude and longitude coordinates like so: "{{states.device_tracker.<your_device_id_here>.attributes.latitude}}" but make sure to use data_template in that case.

As the automation has two levels of data object, these docs should be clarified to specify which data object should be specified as a data_template: the first, the second, or both.

At https://companion.home-assistant.io/en/getting_started/migration it seems to say that one can enter a URL if one is not on "home wifi". Later, in the Nabu Casa troubleshooting section, it says one cannot set up Nabu Casu directly, and one needs to be on the home LAN first. It is really not clear if a connection to the HA instance uses any methods other than via the https:://hass.example.com:8123 URL, or if this is merely about finding internal (presumably working only on one SSID) vs external (presumably working everywhere) URLs.

The notion of a trailing slash, presumably "https://hass.example.com:8123" vs "https://hass.example.com:8123/" is also confusing. Technically one has no path and the other a path with no components, but it does not make sense that any software would treat these separately, especially for URLs entered by humans, almost none of whom understand the syntax subtleties.

The migration guide says only "or you can manually enter the URL", and doesn't address trailing slashes.

(I am running into this helping someone not physically with me configure the iOS app to access a server that neither of us are physically at -- but it does have a straightforward, entirely accessible, domain name.)

Add step between 8 and 9 to logout of the IOS application. Without this action it is not possible to re-enroll

@danikuci1 commented on May 26, 2020, 8:52 PM UTC:

the docs contain a link to https://companion.home-assistant.io/docs/notifications/location-notification which is a non-existent page.

This issue was moved by TomBrien from home-assistant/iOS#594.

Please note, I wrote this while very tired and lacking sleep. It will receive updates over the next few days.

Right now, we live in a similar yet divided world. Home Assistant Companion (hereinafter HAC) for iOS came first and had many years to mature before HAC Android was even a glint in our eyes. Due to that time and somewhat limited thought for the future, iOS made some decisions that don't work well in the Android world. Android is starting to make decisions that will also affect iOS. We should try to cut down on as many differences between the two apps as possible. This will allow us to simplify our documentation but more importantly make it easier for users in households with both Androids and iPhones, in addition to making config sharing easier.

Notifications

The first place to start with is notifications. Right now, both apps support different functionalities. Some functionalities exist because of work developers have done, some will never exist due to OS specific limitations. As much as possible though, we should make it possible for a user to send a notification and 90% of the time it will appear similar across platform. The way that we do this is deriving a schema that both apps can hew to while also providing allowances for platform specific functionality that users want.

As a first step towards that goal, I have come up with this:

{
    "push_token": "",
    "registration_info": {
        "app_id": "io.robbie.HomeAssistant.beta",
        "app_version": "2.0.0 (68)",
        "os_name": "iOS",
        "os_version": "13.1.3"
    },
    "id": "uuid",
    "notification": {
        "message": "The front door is opened",
        "title": "Front Door",
        "badge": 5,
        "image": "https://github.com/home-assistant/home-assistant-assets/blob/master/logo-round-192x192.png?raw=true",
        "tag": "one",
        "click_action": "",
        "actions": [
            {
                "title": "Action 1",
                "id": "action_one"
            }
        ],
        "android": {
            "priority": "high",
            "ttl": "3.5s",
            "sticky": true,
            "visibility": "VISIBILITY_UNSPECIFIED",
            "local_only": true,
            "icon": "ics_launcher",
            "color": "#000000",
            "channel_id": "default",
            "ticker": "Hello World",
            "event_time": "2020-02-14T07:30:21Z",
            "notification_priority": "PRIORITY_DEFAULT",
            "default_sound": true,
            "default_vibrate_timings": true,
            "default_light_settings": true,
            "vibrate_timings": [
                "1s",
                "3.5s"
            ],
            "light_settings": {
                "color": {
                    "red": 1,
                    "green": 1,
                    "blue": 1,
                    "alpha": 0
                },
                "light_on_duration": "3.5s",
                "light_off_duration": "3.5s"
            }
        },
        "ios": {
            "image": {
                "content_type": "image/png",
                "hide_thumbnail": true
            },
            "subtitle": "TwelveTwelve",
            "sound": {
                "name": "default",
                "critical": true,
                "volume": 1
            }
        }
    }
}

As you can see, we have generic fields at the top level (under the notification dictionary) and OS specific fields in their own dictionaries. I also made a spreadsheet that shows common features and their availability across both platforms. We should conform both apps to accept this schema. It will be a pain for users to adapt to one time but will have other benefits to be explained later. The change will be opt in for existing users, at least on iOS. We also have added a UUID to the notification payload to provide lifecycle tracking. The UUID should be generated and stored by Home Assistant Core and used in all follow up events and actions. The actions are now also defined in the notification, whereas previously iOS required defining all possible actions in advance. Actions are now registered with iOS just-in-time before displaying the notification.

Action Events

The next place the apps deviate significantly to the detriment of the user is Notification Action Events. On iOS, this is the event named ios.notification_action_fired. On Android it is mobile_app_notification_action. To start, iOS should adapt the more generic mobile_app_notification_action event name. However, the payloads sent in the events are also very different between platforms and deserve to be unified into one

My proposal is this:

{
    "event_type": "mobile_app_notification_action",
    "data": {
        "action_chosen": "action_one",
        "action_data": {},
        "device_name": "Robbie's iPhone",
        "id": "uuid"
    },
    "origin": "REMOTE",
    "time_fired": "2020-02-02T04:45:05.550251+00:00",
    "context": {
        "id": "abc123",
        "parent_id": null,
        "user_id": "123abc"
    }
}

This provides everything we need to let users determine where the event came from, as well as provides them flexibility to customize by providing the action_data dictionary, a totally user controlled space. They can fill the action_data dict when sending the notification. The id is the same one from the notification example above.

Providing turnkey automation support

Great, so notifications and events are well defined and traceable. That will allow us to implement a new type of automation block which will allow pausing an automation until such time as a user responds to a notification by tapping an action. Users will no longer have to worry about setting up two automations (one to send the notification and one to catch the response event), it will just be handled seamlessly by Home Assistant Core. @balloob came up with this idea and can expand more on it.

Notification Lifecycle Tracking

Now that notifications have unique IDs attached to them, we can monitor them through their entire lifecycle. I propose adding the following new events:

• Notification received by device
• Notification tapped
• Notification dismissed

In addition, I propose that Home Assistant Core start storing these notifications and providing a API to mobile_app implementors to allow viewing notification history.

End to end encrypted notifications

As somewhat of a carrot to get iOS users to opt in to the new notification and event formats, we will begin offering end to end encryption of push notifications on both platforms. On iOS, this is made possible by UNNotificationServiceExtension which will decrypt and map the notification payload before displaying the notification to the user. On Android, we already are in a position where the app is the one processing and displaying the notification, not the OS. mobile_app will be modified to encrypt outgoing notifications using libsodium with the same webhook secret the apps already have. A very minimal forwarder has already been developed and deployed and is available for review here. Here's everything that the forwarder receives:

{
    "encrypted": true,
    "encrypted_data": "j6lwIesVlc+1rYltzw1iFgZZgir3QcZzs+erYXIB6TphTl6bY6xQUYYqhXQ6tGjFAWvMetre/FC89Z85OLExlm3AwX4TzEbbmpLLAoD+zuiG+FugGk756fju58ImTA+Ci5echwgyMNwehKC/RYsbS0V0YieMU34RG/2DT6SDAh++/DmktPBpealTBLnEHRx4/PuNMeqdC7kB5nfkr1gYaBBEXON0R/yLc0sR4qk42RcIyOMd2VrG1apRBSxJizhQVyBrwUWe4z8UdhlXuwLDUhBtieB/xRJSJg1B74ywGvfEtsVJVLlFii8BSsgP/wp/RlcRMLRy8ixa/WPNHLj9YSXLCNYrIvjhTwlxhjAEZncO6fHy0jOuAWbiCrWPgju2q7zWwUxtNO13rGV5pXju++sjiuGn0gKvDBsaw9ZWnVZmR50NeBVha7e4XgUPpS5+Wx78DukpCcuRU/s3N9Q4yCQHkiPtFKszEg6A5FDYb9gGnzD5aSBfKINbNDmh6oBQvN6G2HBsO8E8AdA1cOupMWEFE6b6Y7taHxgNAaX3ik1zYKGe+zDSUSv0SWqIsx8MbbgG+qkSvdNqHswvOw==",
    "push_token": "",
    "registration_info": {
        "app_id": "io.robbie.HomeAssistant.beta",
        "app_version": "2.0.0 (68)",
        "os_version": "13.1.3"
    }
}

and what it sends to the device:

{
	"apns": {
		"payload": {
			"aps": {
				"alert": {
					"title": "Encrypted notification",
					"body": "If you're seeing this, something has gone wrong with encryption"
				},
				"mutable-content": 1
			}
		}
	},
	"data": {
		"encrypted_data": "j6lwIesVlc+1rYltzw1iFgZZgir3QcZzs+erYXIB6TphTl6bY6xQUYYqhXQ6tGjFAWvMetre/FC89Z85OLExlm3AwX4TzEbbmpLLAoD+zuiG+FugGk756fju58ImTA+Ci5echwgyMNwehKC/RYsbS0V0YieMU34RG/2DT6SDAh++/DmktPBpealTBLnEHRx4/PuNMeqdC7kB5nfkr1gYaBBEXON0R/yLc0sR4qk42RcIyOMd2VrG1apRBSxJizhQVyBrwUWe4z8UdhlXuwLDUhBtieB/xRJSJg1B74ywGvfEtsVJVLlFii8BSsgP/wp/RlcRMLRy8ixa/WPNHLj9YSXLCNYrIvjhTwlxhjAEZncO6fHy0jOuAWbiCrWPgju2q7zWwUxtNO13rGV5pXju++sjiuGn0gKvDBsaw9ZWnVZmR50NeBVha7e4XgUPpS5+Wx78DukpCcuRU/s3N9Q4yCQHkiPtFKszEg6A5FDYb9gGnzD5aSBfKINbNDmh6oBQvN6G2HBsO8E8AdA1cOupMWEFE6b6Y7taHxgNAaX3ik1zYKGe+zDSUSv0SWqIsx8MbbgG+qkSvdNqHswvOw==",
		"encrypted": "true",
		"registration_info": "{\"app_id\":\"io.robbie.HomeAssistant.beta\",\"app_version\":\"2.0.0 (68)\",\"os_version\":\"13.1.3\"}"
	},
	"token": ""
}

Obviously our servers are unable to break the encryption and the secret is only ever exchanged directly via app and Home Assistant Core. iOS requires alert and mutable-content to be set to engage our UNNotificationServiceExtension. The user should never actually see that text except if decryption fails for some reason.

The identified downsides to e2e encryption are the following:

• There is no support for Android's ttl or priority fields or APNS headers such as apns-collapse-id or apns-priority. Modifications could be made to notify.mobile_app to allow sending certain whitelisted parameters in the clear.
• All notification translation logic is shipped client side instead of on the server. Therefore, we would either need to commit to only ever adding fields and not removing/modifying existing ones, lest we break older apps, or we version the schema somehow.
• Could make one on one debugging with users harder.

I'm excited to hear the communities thoughts on this proposal. Thanks for reading.

So as discussed on Discord a little. I think versioning is causing us a bit of pain. Main issue is that when someone uses the edit function these edits are made against the next version docs and require moving back to the 2.0.0 which are the landing version.

I've built a demo version of the docs site here from scratch and used Docusaurus 2 to do so. I ported over the conent but this is a couple of PRs out of date now but it is pretty much just a copy and paste the files job to update. Little summary

Cons

• Docusaurus 2 is at a late-stage alpha at the moment, although it is pretty well documented and seemed fine to me
• No translations at the moment, these are coming in Docusaurus 2 soon I believe, and I don't think they were working on the old site to be honest
• I found Docusaurus 2 requires slightly stricter markdown. I.e. underscores required escaping or putting in code ticks (I see no case where the ever should not be!)
• We lose the versioned docs (1.x had little in it). The can be enabled down the line if needed again if we have a version with major changes.

Pros

• I was able to build a fresh version of the site with no leftovers from versioning
• Docusaurus 2 has more useful behind the scenes features and more coming online
• Edits done online will be in the landing version when merged with no need to port back to versioned docs
• Pretty dark mode!
• We lose the versioned docs!

Notes

I haven't enabled the search bar yet for the proof of concept page but this should be trivial on the deployment

Need to make sure the case and restart requirements are clear

It seems (i searched every doc page without finding at least) there is missing documentation about the feature Enable receiving broadcast to update location introduced in Home Assistant Companion Android 1.7.0.
Link to PR home-assistant/android#355

OS: Android 10
Companion version: 2.2.1-274-full

When setting a clock alarm to whichever time, the sensor sets to five minutes before the time the alarm in reality is set to.
For example, when setting a phone alarm to 11.00 the sensor shows:

State: 2020-08-20T08:55:01.000

Attributes:

Local Time: Thu Aug 20 10:55:01 GMT+02:00 2020
Time in Milliseconds: 1597913701000
Package: com.sec.android.app.clockpackage
friendly_name: [devicename] Next Alarm
icon: mdi:alarm
device_class: timestamp

Setting the alarm to 11.16 generates the sensors state state to be 2020-08-20T09:11:01.000Z instead.

It's the same issue for both of our phones having the Android version as above as well as Companion app version.

However - it's not the same for the calendar provider. When deactivation the phone alarm, the next upcoming alarm is a calendar event set with a notification. The event starts at 17.00 local time and is set to notify 15 minutes prior. That gives this in Home Assistance:

State: 2020-08-20T14:45:00.000Z

Attributes:

Local Time: Thu Aug 20 16:45:00 GMT+02:00 2020
Time in Milliseconds: 1597934700000
Package: com.android.providers.calendar
friendly_name: [devicename] Next Alarm
icon: mdi:alarm
device_class: timestamp

Thanks!

The problem

Menu item 'Requesting location updates' links to page https://companion.home-assistant.io/docs/notifications/location-notification but it returns Page Not Found

A suggestion from me: is it a handy addition to include a package-lock.json file in the repo by default?

Since npm install uses this to install all packages, this also ensures that everyone that is working on the companion docs uses the same packages with local development.

Just think about it 😉

Have been thinking of altering the site structure to make things easier to find and navigate. Proposing a new structure here which I think would be a massive improvement personally.

Current way has things more siloed off and in kind of weird, hard to discover areas imo. Theming is not really an integration, and I don't feel like Sensors are an integration either... And then in the Notifications section for example it feels like there's a sort of arbitrary differentiation between basic and advanced. And depending on which section you clicked first you can't really see the other pages easily, Location section for example has no sidebar at all.

Proposed Structure & Sidebar:

• Getting Started
  • Beginners Guide
  • Migrating from Old App
• Core Features
  • Location
  • Sensors
  • Actions
• Notifications
  • Basic Notifications
  • Sounds
  • Attachments
    • Dynamic Attachments (renamed from Dynamic Content)
  • Actionable Notifications
  • Critical Alerts
  • Technical Details (Merge "Architecture" & "Privacy, rate limiting and security" page)
• Integrations
  • Apple Watch
    • Actions
    • Complications
  • NFC & Universal Links
  • Siri Shortcuts
  • URL Handler
  • X-Callback-URL
• Other
  • Theming
  • Haptics
  • App Events
• Troubleshooting
  • Setup and Connectivity
  • Integration Troubleshooting
  • Resetting app
  • Get more Help (Discord, Forum, etc)

I think those are broken out into clearly distinct categories, and it solves the issues mentioned above, makes navigation easier, makes it easy to discover the various features of the app. Probably only a handful of page redirects would be needed.

Header would stay mostly the same I think, except "Misc" & "Help" links get merged to one "Troubleshooting" link.

Just updated the app via Google Play to version 3.0.0-full, which should include the change to be able to use the alarm stream for notifications, thus bypass silent mode / do not disturb. Unfortunately when testing it's not working. I only see another channel called 'alarm-stream' that has been added into notifications under the Home Assistant app, but still silent notifications.

My automation in HA:

action:
  -   service: notify.mobile_app_phone
       data:
         message: "Some message"
         title: "Some title"
           data:
             ttl: 0
             priority: high
             channel: alarm_stream

This just gives me a silent notification when the action is triggered. When I use my alarm clock on my phone it gives me a sound, so I would assume my alarm notifications are properly set-up on my Android device. Running Android v10.

What am I doing wrong here?

Is your feature request related to a problem? Please describe.
I have a security system integrated and sending notifications. I'd like to be able to add actionable buttons such as:

1. A "Call Police" button that takes a tel://911 (or similar) URL to initiate a phone call
2. A "Connect to Intercom" button that takes a URL that matches a URL scheme registered by another app that allows me to deep link into it and initiate a video call

Describe the solution you'd like
Something that allows me to create buttons on a notification that opens a URL directly on the device. It doesn't really have to reach back to HA for anything. Would like to be able to set a Title and a URL, as well as the usual "destructive" and other settings.

It seems the example under:
https://companion.home-assistant.io/en/next/notifications/basic#notification-sounds
has the word "sounds:" when it should be "sound:"

Sorry if this isn't the correct way to get this corrected.

this issue is still on, was reported before, but not solved yet Ha 106.6, latest mobile-app

incorrect mdi: icons showing no icon

please have another look? thanks!

When home-assistant/core#44094 is fixed revert #416

• Client certificates
• HealthKit
• Why doesn't my location update
• How can I build it myself

I get to the logon page and get stuck, cannot add username/pass or traverse fields to select trusted network user.

https://companion.home-assistant.io/en/notifications/basic#replacing-notifications

This

message: "Someone might be in the backyard."
  data:
    apns_headers:
     'apns-collapse-id': 'backyard-motion-detected'

should be this

message: "Someone might be in the backyard."
data:
  apns_headers:
   'apns-collapse-id': 'backyard-motion-detected'

• Minimum requirements
• Onboarding walk through

We have loads of great iOS on-boarding info in the migration guide. However, 2019.1 has been out for about 6 months now and I would hope most people have migrated by now. We should probably consider moving a lot of the problem solving steps to a troubleshooting set up page as the current title isn't clear that these steps apply to fresh installs too

• Actions
• Complications
• Notification Looks

Looks like the search result link locations need to be updated.

Example: searching for Location leads to

https://companion.home-assistant.io/en/core/location#__docusaurus

while it should be: https://companion.home-assistant.io/docs/core/location

So far it seems to be impacting all results. Not entirely sure where the issue relies. We had a similar issue with the links on the feature comparison table and I had to update them to be exact locations.

The sensors doc looks bad on mobile devices (see below) since the table is too wide for a screen. We should re write this plain text with each sensor as a sub-section heading to allow for easy direct linking. I'm thinking something like how configuration variables are shown in the main docs, see here for example.

Current page in Safari on a iPhone Xs:

And in Chrome on a Galaxy S10: