Sign-Up Supported Devices

Embedding a Connect Webview in Your App

Use redirection or an iframe to embed a Connect Webview in your app.

You can use either of the following two methods to incorporate a Connect Webview in your app:

Opening a Connect Webview

To allow users to connect their devices with your app, you will need to present a button to launch a new Connect Webview. If your app has a settings section, we recommend creating a device setting page and adding an "Add Devices" or "Link Devices" button (see example below).

Upon clicking this button, you can then either redirect to the Connect Webview url or embed the Connect Webview in an iFrame and present it in a modal. Please contact us if you would like guidance on best practices.

Redirect to the Connect Webview URL

To incorporate a Connect Webview in your app using redirection, first create the Connect Webview. Redirect your app to the URL for the created Connect Webview. After your user has completed the Connect Webview, verify that your user has connected their device account successfully to Seam. Then, you can use the Seam API to control your users' connected devices.

1. Create a Connect Webview

When your user initiates an action in your app to connect their device account to Seam, create a Connect Webview (connect_webview object).

When creating the new Connect Webview, note the following suggestions:

  • Make sure to set a custom_redirect_url so that the Connect Webview redirects back to the desired page within your application after the Connect Webview flow completes.

    If you want to redirect to a different page when there is an error, you can set the custom_redirect_failure_url to the URL for the desired page.

  • We recommend setting wait_for_device_creation to true so that the Connect Webview does not complete until Seam completes the first sync of the connected account and devices.

Request:

created_connect_webview = seam.connect_webviews.create(
  custom_redirect_url = "https://example.com/redirect",
  custom_redirect_failure_url = "https://example.com/failure-redirect",
  provider_category = "stable",
  wait_for_device_creation = True
)

pprint(created_connect_webview)

Response:

ConnectWebview(
    workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be',
    connect_webview_id='2c852289-ee42-49d0-bddc-0410b518003d',
    status='pending',
    url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=2c852289-ee42-49d0-bddc-0410b518003d&auth_token=z7Wu2Lc85gYUbNUhdvCWaEhmQv61FziA',
    login_successful=False,
    device_selection_mode='none',
    any_provider_allowed=False,
    any_device_allowed=False,
    created_at='2023-11-15T23:24:36.947Z',
    custom_metadata={},
    connected_account_id=None,
    authorized_at=None,
    custom_redirect_url='https://example.com/redirect',
    custom_redirect_failure_url='https://example.com/failure-redirect',
    accepted_providers=[
        'august', 'avigilon_alta', 'brivo', 'schlage', 'smartthings', 'yale', 'nuki', 
        'salto', 'controlbyweb', 'minut', 'my_2n', 'kwikset', 'tedee', 'ttlock', 
        'nest', 'noiseaware', 'igloohome', 'ecobee', 'four_suites', 
        'dormakaba_oracode', 'lockly', 'wyze'
    ],
    accepted_devices=[],
    selected_provider=None,
    wait_for_device_creation=True,
    automatically_manage_new_devices=True
)

Store the connect_webview_id and url for the created Connect Webview.

You use the URL to redirect your app to the Connect Webview. You use the ID later to verify the success of the connection attempt.

2. Redirect Your App to the Connect Webview

Pass the Connect Webview url to the client portion of your app and redirect your app to this URL.

The resulting page displays the authorization flow through which your app user can link their device account to Seam.

Once the user has completed the authorization flow, the Connect Webview redirects back to your app (specifically to the custom_redirect_url). Note that Seam appends the following search parameters to the URL after the redirect:

  • connect_webview_id

  • If there is an error, error_code and error_message

3. Verify Successful Device Account Connection

Use one of the following methods to verify that your user successfully connected their account to Seam through your app:

  • Polling: Use the connect_webview_id to retrieve the Connect Webview. Check the status of the Connect Webview to see if it changed to success.

  • Webhook: Watch for a connected_account.connected event with a connect_webview_id that matches that of the Connect Webview that you created.

Once the connection has occurred successfully, the Connect Webview and the connected_account.connected event payload include a connected_account_id.

You do not need to delete a Connect Webview once a user completes it. Instead, you can simply ignore completed Connect Webviews.

4. Use the Seam API to Control Your Users' Connected Devices

Use the connected_account_id to make requests for your user's account and devices. Note that if you set wait_for_device_creation to false for the Connect Webview, you should wait for the connected_account.completed_first_sync event before retrieving the user's devices. This event indicates that Seam has finished the first sync of the connected account and the devices are now available.

Embed the Connect Webview in an iframe

To incorporate a Connect Webview in your app using an HTML iframe, first create the Connect Webview. Display the URL for the created Connect Webview in an iframe. After your user has completed the Connect Webview, verify that your user has connected their device account successfully to Seam. Then, you can use the Seam API to control your users' connected devices.

1. Create a Connect Webview

When your user initiates an action in your app to connect their device account to Seam, create a Connect Webview (connect_webview object).

We recommend setting wait_for_device_creation to true so that the Connect Webview does not complete until Seam completes the first sync of the connected account and devices.

Request:

created_connect_webview = seam.connect_webviews.create(
  custom_redirect_url = "https://example.com/redirect",
  custom_redirect_failure_url = "https://example.com/failure-redirect",
  provider_category = "stable",
  wait_for_device_creation = True
)

pprint(created_connect_webview)

Response:

ConnectWebview(workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be',
               connect_webview_id='2c852289-ee42-49d0-bddc-0410b518003d',
               status='pending',
               url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=2c852289-ee42-49d0-bddc-0410b518003d&auth_token=z7Wu2Lc85gYUbNUhdvCWaEhmQv61FziA',
               login_successful=False,
               device_selection_mode='none',
               any_provider_allowed=False,
               any_device_allowed=False,
               created_at='2023-11-15T23:24:36.947Z',
               custom_metadata={},
               connected_account_id=None,
               authorized_at=None,
               custom_redirect_url='https://example.com/redirect',
               custom_redirect_failure_url='https://example.com/failure-redirect',
               accepted_providers=['august',
                                   'avigilon_alta',
                                   'brivo',
                                   'schlage',
                                   'smartthings',
                                   'yale',
                                   'nuki',
                                   'salto',
                                   'controlbyweb',
                                   'minut',
                                   'my_2n',
                                   'kwikset',
                                   'tedee',
                                   'ttlock',
                                   'nest',
                                   'noiseaware',
                                   'igloohome',
                                   'ecobee',
                                   'four_suites',
                                   'dormakaba_oracode',
                                   'lockly',
                                   'wyze'],
               accepted_devices=[],
               selected_provider=None,
               wait_for_device_creation=True,
               automatically_manage_new_devices=True)

Store the connect_webview_id and url for the created Connect Webview.

You use the URL to display the Connect Webview in an iframe. You use the ID later to verify the success of the connection attempt.

2. Display the Connect Webview in an iframe

Pass the Connect Webview url to the client portion of your app and use an HTML iframe to display the Connect Webview URL.

For example:

<iframe style="border: none;min-height: 600px;height: 100%;width: 100%"
src="<your connect_webview.url>"
/>

3. Verify Successful Device Account Connection

Use one of the following methods to verify that your user successfully connected their account to Seam through your app:

  • Polling: Use the connect_webview_id to retrieve the Connect Webview. Check the status of the Connect Webview to see if it changed to success.

  • Webhook: Watch for a connected_account.connected event with a connect_webview_id that matches that of the Connect Webview that you created.

  • Event listening: When you host a Connect Webview in an iframe, the iframe uses window.parent.postMessage to send messages to the parent window that is hosting the iframe. window.parent.postMessage is a cross-origin communication mechanism available in web browsers. Register an event listener for the parent window containing the iframe to monitor for message events.

    For example:

    window.addEventListener(
  "message",
  (event) => {
    if (event.data?.event?.event_type === "webview.login_successful") {
      // Do something.
    }
  },
  false
);

    When the device account connection occurs successfully, the Connect Webview issues a webview.login_successful event. This event includes the connect_webview_id. If the device account connection fails, the Connect Webview issues a webview.login_failed event. If there is an error, this event also includes the error_code and error_message. For example:

    {
    "event": {
	"event_type": "webview.login_successful",
    	"connect_webview_id": "123e4567-e89b-12d3-a456-426614174000"
    }
}

Once the connection has occurred successfully, the Connect Webview and the connected_account.connected event payload include a connected_account_id.

You do not need to delete a Connect Webview once a user completes it. Instead, you can simply ignore completed Connect Webviews.

4. Use the Seam API to Control Your Users' Connected Devices

Use the connected_account_id to make requests for your user's account and devices. Note that if you set wait_for_device_creation to false for the Connect Webview, you should wait for the connected_account.completed_first_sync event before retrieving the user's devices. This event indicates that Seam has finished the first sync of the connected account and the devices are now available.

PreviousConnect WebviewsNextAttaching Custom Metadata to the Connect Webview

Last updated

Logo

Resources

Sign-UpBlogAboutSupported Devices

© Seam Labs, Inc. All rights reserved.