mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-11-09 10:59:44 +00:00
Restructure docs APIs (#504)
This commit is contained in:
Franck Nijhof
87
docs/api/native-app-integration/setup.md
Normal file
87
docs/api/native-app-integration/setup.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: "Connecting to an instance"
|
||||
---
|
||||
|
||||
When a user first opens the app, they will need to connect to their local instance to authenticate and register the device.
|
||||
|
||||
## Authenticating the user
|
||||
|
||||
The local instance can be discovered if Home Assistant has the [zeroconf component] configured by searching for `_home-assistant._tcp.local.`. If not configured, the user will need to be asked for the local address of their instance.
|
||||
|
||||
When the address of the instance is known, the app will ask the user to authenticate via [OAuth2 with Home Assistant]. Home Assistant uses IndieAuth, which means that to be able to redirect to a url that triggers your app, you need to take some extra steps. Make sure to read the last paragraph of the "Clients" section thoroughly.
|
||||
|
||||
[zeroconf component]: https://www.home-assistant.io/components/zeroconf
|
||||
[OAuth2 with Home Assistant]: auth_api.md
|
||||
|
||||
## Registering the device
|
||||
|
||||
_This requires Home Assistant 0.90 or later._
|
||||
|
||||
Home Assistant has a `mobile_app` component that allows applications to register themselves and interact with the instance. This is a generic component to handle most common mobile application tasks. This component is extendable with custom interactions if your app needs more types of interactions than are offered by this component.
|
||||
|
||||
Once you have tokens to authenticate as a user, it's time to register the app with the mobile app component in Home Assistant.
|
||||
|
||||
### Getting Ready
|
||||
|
||||
First, you must ensure that the `mobile_app` component is loaded. There are two ways to do this:
|
||||
|
||||
- You can publish a Zeroconf/Bonjour record `_hass-mobile-app._tcp.local.` to trigger the automatic load of the `mobile_app` component. You should wait at least 60 seconds after publishing the record before continuing.
|
||||
- You can ask the user to add `mobile_app` to their configuration.yaml and restart Home Assistant. If the user already has `default_config` in their configuration, then `mobile_app` will have been already loaded.
|
||||
|
||||
You can confirm the `mobile_app` component has been loaded by checking the `components` array of the [`/api/config` REST API call](external_api_rest.md#get-api-config). If you continue to device registration and receive a 404 status code, then it most likely hasn't been loaded yet.
|
||||
|
||||
### Registering the device
|
||||
|
||||
To register the device, make an authenticated POST request to `/api/mobile_app/registrations`. [More info on making authenticated requests.](auth_api.md#making-authenticated-requests)
|
||||
|
||||
Example payload to send to the registration endpoint:
|
||||
|
||||
```json
|
||||
{
|
||||
"device_id": "ABCDEFGH",
|
||||
"app_id": "awesome_home",
|
||||
"app_name": "Awesome Home",
|
||||
"app_version": "1.2.0",
|
||||
"device_name": "Robbies iPhone",
|
||||
"manufacturer": "Apple, Inc.",
|
||||
"model": "iPhone X",
|
||||
"os_name": "iOS",
|
||||
"os_version": "iOS 10.12",
|
||||
"supports_encryption": true,
|
||||
"app_data": {
|
||||
"push_notification_key": "abcdef"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Required | Type | Description |
|
||||
| --------------------- | -------- | ------ | --------------------------------------------------------------------------------------------------- |
|
||||
| `device_id` | V | string | A unique identifier for this device. New in Home Assistant 0.104 |
|
||||
| `app_id` | V | string | A unique identifier for this app. |
|
||||
| `app_name` | V | string | Name of the mobile app. |
|
||||
| `app_version` | V | string | Version of the mobile app. |
|
||||
| `device_name` | V | string | Name of the device running the app. |
|
||||
| `manufacturer` | V | string | The manufacturer of the device running the app. |
|
||||
| `model` | V | string | The model of the device running the app. |
|
||||
| `os_name` | V | string | The name of the OS running the app. |
|
||||
| `os_version` | V | string | The OS version of the device running the app. |
|
||||
| `supports_encryption` | V | bool | If the app supports encryption. See also the [encryption section](app_integration_sending_data.md#implementing-encryption). |
|
||||
| `app_data` | | Dict | App data can be used if the app has a supporting component that extends `mobile_app` functionality. |
|
||||
|
||||
When you get a 200 response, the mobile app is registered with Home Assistant. The response is a JSON document and will contain the URLs on how to interact with the Home Assistant instance. You should permanently store this information.
|
||||
|
||||
```json
|
||||
{
|
||||
"cloudhook_url": "https://hooks.nabu.casa/randomlongstring123",
|
||||
"remote_ui_url": "https://randomlongstring123.ui.nabu.casa",
|
||||
"secret": "qwerty",
|
||||
"webhook_id": "abcdefgh"
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Type | Description |
|
||||
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `cloudhook_url` | string | The cloudhook URL provided by Home Assistant Cloud. Only will be provided if user is actively subscribed to Nabu Casa. |
|
||||
| `remote_ui_url` | string | The remote UI URL provided by Home Assistant Cloud. Only will be provided if user is actively subscribed to Nabu Casa. |
|
||||
| `secret` | string | The secret to use for encrypted communication. Will only be included if encryption is supported by both the app and the Home Assistant instance. [More info](app_integration_sending_data.md#implementing-encryption). |
|
||||
| `webhook_id` | string | The webhook ID that can be used to send data back. |
|
||||
Reference in New Issue
Block a user