Connect Webview Process

Learn how to create, display, and complete Connect Webviews to connect devices and systems to Seam.

This topic describes the basic Connect Webview process. First, you create the Connect Webview and display it for your user from within your app. Your user completes the Connect Webview flow to authorize the device or system account connection to Seam. Then, you can verify the successful account connection, retrieve the newly-connected devices or systems, and start controlling these devices or systems with Seam.

Step 1: Create a Connect Webview

The Connect Webview flow begins when your user wants to connect their device or ACS account to Seam through your app.

In your app, create a Connect Webview. The Seam API represents Connect Webviews as connect_webview objects.

The created connect_webview object includes a url property.

Code:

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
)

Output:

ConnectWebview(
  connect_webview_id='12345678-1234-1234-1234-123456789012',
  url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=z7Wu2Lc85gYUbNUhdvCWaEhmQv61FziA',
  status='pending',
  login_successful=False,
  custom_redirect_url='https://example.com/redirect',
  custom_redirect_failure_url='https://example.com/failure-redirect',
  accepted_providers=[
    ...
  ],
  wait_for_device_creation=True,
  ...
)

Code:

curl -X 'POST' \
  'https://connect.getseam.com/connect_webviews/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "custom_redirect_url": "https://example.com/redirect",
  "custom_redirect_failure_url": "https://example.com/failure-redirect",
  "provider_category": "stable",
  "wait_for_device_creation": true
}'

Output:

{
  "connect_webview": {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=CvPDERYGGMvqgo6N1gsT7XRBieBtPqtUG",
    "status": "pending",
    "login_successful": false,
    "custom_redirect_url": "https://example.com/redirect",
    "custom_redirect_failure_url": "https://example.com/failure-redirect",
    "accepted_providers": [
      ...
    ],
    "wait_for_device_creation": true,
    ...
  },
  "ok": true
}

Code:

const createdConnectWebview = await seam.connectWebviews.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
})

Output:

{
  connect_webview_id: '12345678-1234-1234-1234-123456789012',
  url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=2r2Rn8V5QUtxE79gNhTmTK58KkuqrwU8d',
  status: 'pending',
  login_successful: false,
  custom_redirect_url: 'https://example.com/redirect',
  custom_redirect_failure_url: 'https://example.com/failure-redirect',
  accepted_providers: [
    ...
  ],
  wait_for_device_creation: true,
  ...
}

Code:

created_connect_webview = client.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
)

Output:

<
  Seam::ConnectWebview:0x00438
    connect_webview_id="12345678-1234-1234-1234-123456789012"
    url="https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=6zrib4wrGZMDxvJxPQQFiB6snmx7UAU6E"
    status="pending"
    login_successful=false
    custom_redirect_url="https://example.com/redirect"
    custom_redirect_failure_url="https://example.com/failure-redirect"
    accepted_providers=[
      ...
    ]
    wait_for_device_creation=true
    ...
>

Code:

$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
);

Output:

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "url": "https:\/\/connect.getseam.com\/connect_webviews\/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=CvXRmaLfBghshH5rUNKcGivC6BVbjD6JG",
  "status": "pending",
  "login_successful": false,
  "custom_redirect_url": "https:\/\/example.com\/redirect",
  "custom_redirect_failure_url": "https:\/\/example.com\/failure-redirect",
  "accepted_providers": [
    ...
  ],
  "wait_for_device_creation": true,
  ...
}

Code:

var createdConnectWebview = seam.ConnectWebviews.Create(
  customRedirectUrl: "https://example.com/redirect",
  customRedirectFailureUrl: "https://example.com/failure-redirect",
  providerCategory: Seam.Api.ConnectWebviews.CreateRequest.ProviderCategoryEnum.Stable,
  waitForDeviceCreation: true
);

Output:

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=9eBKNtzB6ZKkSPPD33MZFshYSbmBcSMz7",
  "status": "pending",
  "login_successful": false,
  "custom_redirect_url": "https://example.com/redirect",
  "custom_redirect_failure_url": "https://example.com/failure-redirect",
  "accepted_providers": [
    ...
  ],
  "wait_for_device_creation": true,
  ...
}

Code:

ConnectWebview createdConnectWebview = seam.connectWebviews().create(ConnectWebviewsCreateRequest.builder()
  .customRedirectUrl("https://example.com/redirect")
  .customRedirectFailureUrl("https://example.com/failure-redirect")
  .providerCategory(ProviderCategory.STABLE)
  .waitForDeviceCreation(true)
  .build());

Output:

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=9eBKNtzB6ZKkSPPD33MZFshYSbmBcSMz7",
  "status": "pending",
  "login_successful": false,
  "custom_redirect_url": "https://example.com/redirect",
  "custom_redirect_failure_url": "https://example.com/failure-redirect",
  "accepted_providers": [
    ...
  ],
  "wait_for_device_creation": true,
  ...
}

Code:

createdConnectWebview, err := client.ConnectWebviews.Create(
    context.Background(),
    &api.ConnectWebviewsCreateRequest{
      CustomRedirectUrl: api.String("https://example.com/redirect"),
      CustomRedirectFailureUrl: api.String("https://example.com/failure-redirect"),
      ProviderCategory: api.ProviderCategoryStable.Ptr(),
      WaitForDeviceCreation: api.Bool(true),
    },
  )

if err != nil {
  return err
}

return nil

Output:

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=9eBKNtzB6ZKkSPPD33MZFshYSbmBcSMz7",
  "status": "pending",
  "login_successful": false,
  "custom_redirect_url": "https://example.com/redirect",
  "custom_redirect_failure_url": "https://example.com/failure-redirect",
  "accepted_providers": [
    ...
  ],
  "wait_for_device_creation": true,
  ...
}

Step 2: Display the Connect Webview

In your app, open the Connect Webview for your user, using the Connect Webview url.

You can redirect to the Connect Webview URL or embed the Connect Webview in an iframe.

For instructions, see Embedding a Connect Webview in Your App.

Step 3: Your User Completes the Connect Webview

The Connect Webview guides your app user through the following authorization steps:

In the introduction page of the Connect Webview, the user clicks Continue.

The user selects their device or ACS brand.

The user follows the displayed instructions to authorize their account. Seam handles all the necessary authorization steps.
For most brands, this authorization flow consists of a simple device account login. Some brands also require multifactor authentication or other information. For example, brands like Yale offer multiple backend services, depending on the user's global region. Seam prompts the user to identify the correct service and then proceeds with the appropriate authorization request.

The Connect Webview displays a page to indicate the successful device or ACS account connection.
If an error occurs, the Connect Webview displays the error type, for example, an incorrect password.
For more complicated errors, the Connect Webview displays a simple Contact support link that raises the issue to our support team.

Step 4: Verify Successful Account Connection

Use one of the following methods to learn when the account connection has completed successfully:

For instructions, see Verifying Successful Account Connection.

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

Step 5: Retrieve Connected Devices or ACS

Use the connected_account_id from the connected_account.connected event or the completed Connect Webview to retrieve the devices or ACS that your user has just connected to Seam.

Once you have retrieved the newly-connected set of devices or ACS, you can start controlling them with the Seam API. For example, for a set of devices, you may first want to prompt your user to group devices by property. For an ACS, you may first want your user to configure the access permissions to grant to new visitors or tenants.

For instructions, see Retrieving Devices or Access Control Systems Connected Through a Connect Webview.

If your user wants to connect additional devices or ACS from different brands to Seam, your app must create and present a new Connect Webview for each different account that your user wants to connect.

Step 6: Use the Seam API to Control Your Users' Connected Devices or ACS

Continue using the Seam API to control your users' connected devices or ACS. For example, if you app user has connected a lock that support remote unlock operations, your app can now unlock the lock.

To learn about the actions that you can perform using the Seam API, see the Seam capability guides. These guides provide helpful tutorials and code samples, categorized by capability types.

Smart locks, including locking/unlocking and managing access codes
Access control systems
Thermostats
Noise sensors
Mobile access

PreviousConnect Webviews NextEmbedding a Connect Webview in Your App

Last updated 16 days ago

Was this helpful?