Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Delineate platform support of various deeplink types #1159

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
+52 −12
Open

Delineate platform support of various deeplink types #1159

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
2043176
Indicate URL Handler support for Android
travissanderson Jan 10, 2025
877b539
Add platform compatibility table
travissanderson Jan 10, 2025
aa31fa9
Update server specify instructions
travissanderson Jan 10, 2025
fb9f2e9
Remove unused closing anchor tag
travissanderson Jan 10, 2025
77cdc80
Correct table header
travissanderson Jan 10, 2025
9816aa4
Correct copypasta
travissanderson Jan 10, 2025
bbff8ca
Consolidate Android columns since they support the same set
travissanderson Jan 10, 2025
2ec9eac
Combine iOS and macOS
travissanderson Jan 10, 2025
58a5dba
Merge branch 'master' of github.com:home-assistant/companion.home-ass…
Jan 16, 2025
e5a40c3
Use sentence casing and consistency between headers
Jan 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/core/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ Not all features are supported by Android at the moment but eventually most feat
</tr>
<tr>
<td><a href="/docs/integrations/url-handler">URL Handler</a></td>
<td></td>
<td></td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
</tr>
Expand Down
68 changes: 59 additions & 9 deletions docs/integrations/url-handler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,51 @@ id: 'url-handler'

Home Assistant supports opening from other apps via URL.

Query parameters are passed as a dictionary in the call.
## Platform Compatibility
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use sentence case - the current page may not always match the standards but let's try to keep them in mind for new documentation.


:::info
If multiple servers are connected to an app, you will be prompted to select a server when handling a `navigate` link. `call_service` and `fire_event` links will be handled using the first server in the list.
:::
Platform support of different types of deeplinks will vary, consult the table below to see which deeplink types are available for your platform.

<table className="core-table">
<thead>
<tr>
<th><strong>Integrations</strong></th>
<th><img alt="Android" src="/assets/android.svg" /> Full</th>
<th><img alt="Android" src="/assets/android.svg" /> Minimal</th>
<th><img alt="iOS" src="/assets/iOS.svg" /></th>
<th><img alt="macOS" src="/assets/macOS.svg" /></th>
</tr>
</thead>
<tbody>
<tr>
<td>Navigate</a></td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>Call Service</a></td>
<td></td>
<td></td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>Fire Event</a></td>
<td></td>
<td></td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>Send Location</a></td>
<td></td>
<td></td>
<td>✅</td>
<td>✅</td>
</tr>
</tbody>
</table>

## Navigate
This allows you to update the frontend page location via a deeplink. To build a deeplink, follow these steps:
Expand All @@ -18,22 +58,32 @@ This allows you to update the frontend page location via a deeplink. To build a
2. Copy the path portion of the URL, in this example that would be `/dashboard-mobile/my-subview`
3. Craft your URL by starting with `homeassistant://navigate` and adding the path, e.g. `homeassistant://navigate/dashboard-mobile/my-subview`

### Specify server to navigate to
![iOS](/assets/iOS.svg) <span class='beta'>BETA</span><br />
jpelgrom marked this conversation as resolved.
Show resolved Hide resolved
:::info
![iOS](/assets/iOS.svg) **Specifying which server to navigate to is currently only supported in iOS**<br />
By default the App will ask which server you want to navigate to in case you have multiple servers.
To define which server you want to navigate to, use the query param `?server=` like the example below:<br /><br />
`homeassistant://navigate/webcams?server=My%20home` when your server name is `My Home`, or use `?server=default` if you want to navigate to the first server available.
:::

## Call service
![iOS](/assets/iOS.svg)<br />
Example: `homeassistant://call_service/device_tracker.see?entity_id=device_tracker.entity`

Query parameters are passed as a dictionary in the call.

:::info
If multiple servers are connected to an app, `call_service` links will be handled using the first server in the list.
:::

## Fire event
![iOS](/assets/iOS.svg)<br />
You can create an [event trigger](https://www.home-assistant.io/docs/automation/trigger/#event-trigger) and fire the event.

Example: `homeassistant://fire_event/custom_event?entity_id=MY_CUSTOM_EVENT`

Query parameters are passed as a dictionary in the call.

:::info
If multiple servers are connected to an app, `call_service` links will be handled using the first server in the list.
:::

## Send one shot location
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious what the use case for this is. Is it for if you don't share your location by default but want to once to trigger automations etc? Or to force a precise GPS location update? Maybe both are valid usages?

![iOS](/assets/iOS.svg)<br />
Example: `homeassistant://send_location/`