Skip to content

Commit

Permalink
GITBOOK-405: Add capability flags to list device providers
Browse files Browse the repository at this point in the history
  • Loading branch information
@DebbieAtSeam @gitbook-bot
DebbieAtSeam authored and gitbook-bot committed Aug 2, 2024
1 parent b6f3875 commit d0ab17b
Show file tree
Hide file tree
Showing 6 changed files with 166 additions and 931 deletions.
6 changes: 4 additions & 2 deletions docs/api-clients/connect-webviews/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,14 +34,16 @@ To enable a user to connect their device account to Seam through your app, you m
| **`authorized_at`** | String | Date and time at which the user authorized (through the Connect Webview) the management of their devices |
| **`workspace_id`** | String (UUID) | ID of the [workspace](../../core-concepts/workspaces/) that contains the Connect Webview |

### Accepted Provider Category Keys
### Provider Category Keys

When you [create a Connect Webview](create-a-connect-webview.md), specify the desired provider category key in the `provider_category` parameter. Alternately, to specify a list of providers explicitly, use the `accepted_providers` parameter with a list of [device provider keys](./#device-provider-keys).

| key | Description |
| --------------------- | ------------------------------------------------------------------ |
| `stable` | Only returns provider integrations marked as stable. |
| `consumer_smartlocks` | Only returns provider integrations marked as consumer smart locks. |
| `thermostats` | Only returns provider integrations marked as thermostats. |
| `noise_sensors` | Only returns provider instegrations marked as noise sensors. |
| `noise_sensors` | Only returns provider integrations marked as noise sensors. |

{% hint style="info" %}
To list all providers within a category, use the [List Device Providers](../devices/list-device-providers.md) method with the desired `provider_category` filter.
Expand Down
83 changes: 12 additions & 71 deletions docs/api-clients/connect-webviews/create-a-connect-webview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,70 +10,21 @@ To enable a user to connect their devices or systems to Seam, they must sign in

![This example shows how a Connect Webview looks when you display it to your user.](<../../.gitbook/assets/image (12).png>)

## Create a `connect_webview`

<mark style="color:green;">`POST`</mark> `https://connect.getseam.com/connect_webviews/create`

#### Request Body
## Request

| Name | Type | Description |
| ------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `accepted_providers`<mark style="color:red;">\*</mark> | String\[] | <p>Array of accepted</p><p>device provider keys. See</p><p><a href="./#device-provider-keys">Device Provider Keys</a>.</p> |
| `custom_redirect_url` | String | URL to redirect user to after provider login is complete. |
| `custom_redirect_failure_url` | <p>String<br><em>Optional</em></p> | <p>Alternative URL to redirect the user on error. If this is not set, falls back to</p><p><code>custom_redirect_url</code>.</p> |
### Request Parameters

{% tabs %}
{% tab title="201: Created connect_webview successfully created" %}
```javascript
{
"connect_webview": {
"connect_webview_id": "123e4567-e89b-12d3-a456-426614174000",
"custom_metadata": {},
"custom_redirect_url": null,
"custom_redirect_failure_url": null,
"url": "https://connect.getseam.com/v1/connect_webviews/view?connect_webview_id=02454094-1cab-4693-babc-afa9e1c55f09&auth_token=P7XLD4hYXva24WqwSKTC4pKQMP7v3zWUz",
"workspace_id": "84dda4b8-f327-4d97-a720-e0504a13a441",
"device_selection_mode": "none",
"accepted_providers": [
"smartthings"
],
"accepted_devices": [],
"any_provider_allowed": false,
"any_device_allowed": null,
"created_at": "2022-02-07T18:33:50.271Z",
"login_successful": false,
"status": "pending"
}
}
```
{% endtab %}
| Parameter | Type | Description |
| ---------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider_category` | String | <p>Specifies the category of providers to include.<br>Supported categories:</p><ul><li><code>stable</code></li><li><code>consumer_smartlocks</code></li><li><code>thermostats</code></li><li><code>noise_sensors</code></li></ul><p>See <a href="./#provider-category-keys">Provider Category Keys</a>.</p> |
| `accepted_providers` | String\[] | Array of accepted device provider keys as an alternative to `provider_category`. Use this parameter to specify accepted providers explicitly. See [Device Provider Keys](./#device-provider-keys). |
| `custom_redirect_url` | <p>String<br><em>Optional</em></p> | URL to redirect user to after provider login is complete |
| `custom_redirect_failure_url` | <p>String</p><p>Optional</p> | Alternative URL to redirect the user on error. If this is not set, falls back to `custom_redirect_url` |
| `automatically_manage_new_devices` | Boolean | <p>Indicates whether newly added devices should appear as managed devices<br>Default: <code>true</code></p> |

{% tab title="400: Bad Request " %}
```javascript
{
"error": {
"type": "invalid_input",
"message": "Invalid enum value. Expected 'akuvox' | 'august' | 'schlage' | 'smartthings' | 'yale' | 'noiseaware' | 'salto' | 'doorking' | 'salto' | 'genie' | 'linear' | 'seam_relay_admin' for provided \"accepted_providers.0\"",
"validation_errors": {
"_errors": [],
"accepted_providers": {
"0": {
"_errors": [
"Invalid enum value. Expected 'akuvox' | 'august' | 'schlage' | 'smartthings' | 'yale' | 'noiseaware' | 'salto' | 'doorking' | 'salto' | 'genie' | 'linear' | 'seam_relay_admin'"
]
},
"_errors": []
}
},
"request_id": "23bc6c4b-286f-4485-9531-a8f3300370cd"
},
"ok": false
}
```
{% endtab %}
{% endtabs %}

### Code Example
### Sample Request

{% tabs %}
{% tab title="JavaScript" %}
Expand Down Expand Up @@ -258,21 +209,11 @@ You should make a new`connect_webview`for each unique login request.
Each `connect_webview` tracks the user that signed in with it. You receive an error if you reuse a Connect Webview for the same user twice or if you use the same Connect Webview for multiple users.
{% endhint %}

### Parameters

| `provider_category` | type: string | <p>Specifies the category of providers to include.<br>Supported categories:</p><ul><li><code>stable</code></li><li><code>consumer_smartlocks</code></li><li><code>thermostats</code></li><li><code>noise_sensors</code></li></ul><p>See <a href="./#accepted-provider-category-keys">Accepted Provider Category Keys</a>.</p> |
| ---------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accepted_providers` | type: string\[] | Array of accepted **device provider keys** and an alternative to `provider_category`. This lets you explicitly specified accepted providers (e.g. "august"). See [Device Provider Keys](./#device-provider-keys). |
| `custom_redirect_url` | <p>type: string<br>Optional</p> | URL to redirect user to after provider login is complete |
| `custom_redirect_failure_url` | <p>type: string</p><p>Optional</p> | Alternative URL to redirect the user on error. If this is not set, falls back to `custom_redirect_url` |
| `device_selection_mode` | type: 'none' | 'multiple' |
| `automatically_manage_new_devices` | type: 'boolean' | <p>Indicates whether newly added devices should appear as managed devices<br>Default: <code>true</code></p> |

### Response
## Response

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here.

#### JSON format
### Sample Response

{% tabs %}
{% tab title="JSON" %}
Expand Down
22 changes: 14 additions & 8 deletions docs/api-clients/devices/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,18 +116,24 @@ On some account types, Seam provides additional information about the manufactur

Seam maintains a list of device providers that you can access using the [List Device Providers](list-device-providers.md) endpoint.

The [Device Provider](./#device-provider) object includes the following information:
The `device_provider` object includes the following information:

<table><thead><tr><th width="273">Property</th><th width="92.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>device_provider_name</code></td><td>String</td><td><p>Name of the device provider.</p><p>For example: <code>august</code></p></td></tr><tr><td><code>display_name</code></td><td>String</td><td><p>Formatted version of the <code>device_provider_name</code>.</p><p>For example: <code>August</code></p></td></tr><tr><td><code>image_url</code></td><td>String</td><td>Image URL for the provider logo.</td></tr><tr><td><code>provider_categories</code></td><td>Array</td><td><p>Array of associated categories for the provider.</p><p>Supported categories:</p><ul><li><code>stable</code></li><li><code>consumer_smartlocks</code></li><li><code>thermostats</code></li><li><code>noise_sensors</code></li></ul></td></tr></tbody></table>
<table><thead><tr><th width="273">Property</th><th width="101.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>device_provider_name</code></td><td>String</td><td><p>Name of the device provider.</p><p>For example: <code>august</code></p></td></tr><tr><td><code>display_name</code></td><td>String</td><td><p>Formatted version of the <code>device_provider_name</code>.</p><p>For example: <code>August</code></p></td></tr><tr><td><code>image_url</code></td><td>String</td><td>Image URL for the provider logo.</td></tr><tr><td><code>provider_categories</code></td><td>Array</td><td><p>Array of associated categories for the provider.</p><p>Supported categories:</p><ul><li><code>stable</code></li><li><code>consumer_smartlocks</code></li><li><code>thermostats</code></li><li><code>noise_sensors</code></li></ul></td></tr><tr><td><code>can_remotely_unlock</code></td><td>Boolean</td><td>Indicates whether at least one supported device from the provider can perform a <a href="../../products/smart-locks/lock-and-unlock.md">remote unlock operation</a>. See <a href="../../capability-guides/device-and-system-capabilities.md#capability-flags">Capability Flags</a>.</td></tr><tr><td><code>can_remotely_lock</code></td><td>Boolean</td><td>Indicates whether at least one supported device from the provider can perform a <a href="../../products/smart-locks/lock-and-unlock.md">remote lock operation</a>. See <a href="../../capability-guides/device-and-system-capabilities.md#capability-flags">Capability Flags</a>.</td></tr><tr><td><code>can_program_online_access_codes</code></td><td>Boolean</td><td>Indicates whether at least one supported device from the provider can <a href="../../products/smart-locks/access-codes/">program online access codes</a>. See <a href="../../capability-guides/device-and-system-capabilities.md#capability-flags">Capability Flags</a>.</td></tr><tr><td><code>can_program_offline_access_codes</code></td><td>Boolean</td><td>Indicates whether at least one supported device from the provider can <a href="../../products/smart-locks/access-codes/offline-access-codes.md">program offline access codes</a>. See <a href="../../capability-guides/device-and-system-capabilities.md#capability-flags">Capability Flags</a>.</td></tr></tbody></table>

The following example shows a device provider object:
The following example shows a `device_provider` object:

```javascript
```json
{
"device_provider_name": "august",
"display_name": "August",
"image_url": "https://connect.getseam.com/assets/images/logos/august_logo_square.png",
"provider_categories": ["stable"]
"device_provider_name": "august",
"display_name": "August",
"image_url": "https://connect.getseam.com/_next/image?url=https://connect.getseam.com/assets/images/logos/august_logo_square.png&q=75&w=128",
"provider_categories": [
"stable",
"consumer_smartlocks"
],
"can_remotely_lock": true,
"can_remotely_unlock": true,
"can_program_online_access_codes": true
}
```

Expand Down
Loading

0 comments on commit d0ab17b

Please sign in to comment.