> ## Documentation Index
> Fetch the complete documentation index at: https://www.seam.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ecosystem Components

> Embed Seam's directory of compatible apps and its catalog of supported devices on your own website with two lightweight Seam Components.

Ecosystem Components are two [Seam Components](/docs/ui-components/overview/index) that show data from the Seam Ecosystem on your own website: the apps that work with Seam, and the device models that Seam supports.

Use them on a manufacturer's product page to list the apps a lock works with, or on an app's integrations page to list the devices its customers can connect.

<CardGroup cols={2}>
  <Card title="Compatible Apps" href="/docs/ui-components/overview/ecosystem-components/compatible-apps">
    `<seam-compatible-apps>` lists the apps that work with a device category, manufacturer, provider, or capability through Seam.
  </Card>

  <Card title="Supported Devices" href="/docs/ui-components/overview/ecosystem-components/supported-devices">
    `<seam-supported-devices>` lists the device models that work with Seam, with capability badges, search, and filters.
  </Card>
</CardGroup>

Unlike the other Seam Components, Ecosystem Components do not need a publishable key, a client session token, or a Seam workspace. They read public data only, and they authenticate with an **embed key**.

Both components ship in [`@seamapi/react`](https://github.com/seamapi/react) 5.1.0 and later. Try them with sample data in the [interactive component library](https://react.seam.co/?path=/docs/ecosystem-compatibleapps--docs).

## Before You Begin

To embed the components, you need an embed key from Seam. Embed keys start with `eco_live_`.

Email [support@getseam.com](mailto:support@getseam.com) and include:

* Your company, and whether you are a device manufacturer or an app that integrates with Seam.
* Every origin you plan to embed the components on.

Seam creates the key for you and replies with it. This is a manual step on Seam's side, so request your key before you need it.

<Info>
  Send **full origins**, including the scheme and any non-default port, not bare hostnames. Seam matches them against the browser's `Origin` header, so `example.com` matches nothing while `https://example.com` matches. Include every environment you embed on:

  ```
  https://www.example.com
  https://staging.example.com
  https://*.preview.example.com
  ```

  Wildcards are supported, so `https://*.preview.example.com` covers your preview subdomains. Seam adds `http://localhost` and `http://127.0.0.1` on any port to every key, so the components also work on your development server.
</Info>

### How the Embed Key Works

An embed key is **not** a Seam API key and carries no account access. It identifies your embed, and it only works on the origins registered for it.

* A request from a registered origin succeeds.
* A request from any other origin fails with `403 origin_not_allowed`.
* Matching is on the whole origin, scheme included. `https://example.com` and `http://example.com` are different origins, and so are `https://example.com` and `https://www.example.com`.

Because of this, the key is safe to include in your page's HTML, where anyone can read it. Someone who copies it cannot use it on their own site.

What the key does also depends on who it belongs to:

* **Manufacturer key**: [Supported Devices](/docs/ui-components/overview/ecosystem-components/supported-devices) defaults to your brand's devices, so you can drop it on a product page without any other attributes.
* **App (partner) key**: [Supported Devices](/docs/ui-components/overview/ecosystem-components/supported-devices) hides the manufacturers, device types, and providers you have told Seam you do not support.

To add or remove origins later, email [support@getseam.com](mailto:support@getseam.com).

## Add the Components to Your Site

<Tabs>
  <Tab title="Plain HTML">
    Load `ecosystem.js` from the Seam CDN, then place the elements anywhere on the page.

    ```html theme={"dark"}
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Works with Seam</title>
        <script
          type="module"
          src="https://react.seam.co/v/5.1.0/dist/ecosystem.js"
        ></script>
      </head>
      <body>
        <seam-supported-devices
          embed-key="eco_live_your_embed_key"
          manufacturer="schlage"
        ></seam-supported-devices>

        <seam-compatible-apps
          embed-key="eco_live_your_embed_key"
          device-type="smartlock"
          manufacturer="schlage"
        ></seam-compatible-apps>
      </body>
    </html>
    ```

    `ecosystem.js` contains only the two Ecosystem Components, without the Seam API client, so it stays small (about 66 kB gzipped). If your page already loads `elements.js` for other Seam Components, it defines these elements too, so you do not need both.

    Pin an explicit version in production so a new release cannot change your page unexpectedly. To upgrade, change the version in the URL. See the [releases](https://github.com/seamapi/react/releases) for available versions.

    Boolean attributes work with or without a value: `hide-search` and `hide-search="true"` are equivalent, and `hide-search="false"` turns the option off.
  </Tab>

  <Tab title="React">
    Install `@seamapi/react`:

    ```bash theme={"dark"}
    npm install --save @seamapi/react
    ```

    Wrap the components in an `EcosystemProvider` and pass your embed key:

    ```jsx theme={"dark"}
    import {
      CompatibleApps,
      EcosystemProvider,
      SupportedDevices,
    } from '@seamapi/react'

    export function ProductPage() {
      return (
        <EcosystemProvider embedKey='eco_live_your_embed_key'>
          <SupportedDevices manufacturer='schlage' />
          <CompatibleApps deviceType='smartlock' manufacturer='schlage' />
        </EcosystemProvider>
      )
    }
    ```

    `EcosystemProvider` does not need a publishable key and does not load the Seam API client. If your app already renders a [`SeamProvider`](/docs/ui-components/overview/react-components/seam-provider) for other Seam Components, pass `embedKey` to it instead of adding an `EcosystemProvider`:

    ```jsx theme={"dark"}
    <SeamProvider publishableKey='your_publishable_key' embedKey='eco_live_your_embed_key'>
      <SupportedDevices manufacturer='schlage' />
    </SeamProvider>
    ```

    <Note>
      Seam Components are client components. In the Next.js App Router, add the `"use client"` directive to the files that render them.
    </Note>
  </Tab>

  <Tab title="Vue">
    Install `@seamapi/react` and import the Ecosystem elements in your entry file, for example `src/main.js`:

    ```bash theme={"dark"}
    npm install --save @seamapi/react
    ```

    ```javascript theme={"dark"}
    import '@seamapi/react/ecosystem.js'
    ```

    Tell the Vue compiler that `seam-` tags are custom elements, not Vue components. With Vite, set `isCustomElement` in `vite.config.js`:

    ```javascript theme={"dark"}
    import vue from '@vitejs/plugin-vue'
    import { defineConfig } from 'vite'

    export default defineConfig({
      plugins: [
        vue({
          template: {
            compilerOptions: {
              isCustomElement: (tag) => tag.startsWith('seam-'),
            },
          },
        }),
      ],
    })
    ```

    Then use the elements in your templates with kebab-case attributes:

    ```html theme={"dark"}
    <template>
      <seam-compatible-apps
        :embed-key="embedKey"
        device-type="smartlock"
        manufacturer="schlage"
      ></seam-compatible-apps>
    </template>
    ```

    See [Vue and Web Components](https://vuejs.org/guide/extras/web-components.html) for other build setups.
  </Tab>

  <Tab title="Angular">
    Install `@seamapi/react` and import the Ecosystem elements in `src/main.ts`:

    ```bash theme={"dark"}
    npm install --save @seamapi/react
    ```

    ```typescript theme={"dark"}
    import '@seamapi/react/ecosystem.js'
    ```

    Add `CUSTOM_ELEMENTS_SCHEMA` to every component (or `NgModule`) whose template uses a `seam-` element:

    ```typescript theme={"dark"}
    import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'

    @Component({
      selector: 'app-product-page',
      standalone: true,
      schemas: [CUSTOM_ELEMENTS_SCHEMA],
      template: `
        <seam-supported-devices
          [attr.embed-key]="embedKey"
          manufacturer="schlage"
        ></seam-supported-devices>
      `,
    })
    export class ProductPageComponent {
      embedKey = 'eco_live_your_embed_key'
    }
    ```

    Use `[attr.embed-key]` (with the `attr.` prefix) to bind a value from your component to an attribute.
  </Tab>
</Tabs>

## Shared Attributes

Both components accept these attributes in addition to their own. In React, use the camel-cased prop name on `EcosystemProvider` (or `SeamProvider`), except for `className`, which goes on the component itself.

| Attribute | React prop | Description |
| - | - | - |
| `embed-key` | `embedKey` | Your embed key (`eco_live_…`). |
| `theme` | `theme` | `light` (default), `dark`, or `auto`. See [Dark Mode](#dark-mode). Set on each component. |
| `class-name` | `className` | A class name added to the component's container element. |
| `disable-css-injection` | `disableCssInjection` | Do not load the component stylesheet from the Seam CDN. See [Styles and Fonts](#styles-and-fonts). |
| `disable-font-injection` | `disableFontInjection` | Do not load the Source Sans Pro font from Google Fonts. |
| `ecosystem-endpoint` | `ecosystemEndpoint` | The Seam Ecosystem API endpoint. Defaults to `https://ecosystem.seam.co/v1/`. Only change this if you proxy the API. |

## Dark Mode

Set `theme` on each component:

* `light` (default) always renders the light theme.
* `dark` always renders the dark theme.
* `auto` follows the visitor's operating system or browser color scheme (`prefers-color-scheme`).

```html theme={"dark"}
<seam-compatible-apps
  embed-key="eco_live_your_embed_key"
  device-type="smartlock"
  theme="auto"
></seam-compatible-apps>
```

If your site has its own theme toggle, set `theme` to `light` or `dark` from it instead of using `auto`. The components use a light-on-dark logo variant in the dark theme when one is available.

## Styles and Fonts

By default, each component adds two stylesheets to the page's `<head>`: the Seam Components CSS from `https://react.seam.co` and the [Source Sans Pro](https://fonts.google.com/specimen/Source+Sans+Pro) font from Google Fonts. The components fall back to your system sans-serif font if the font does not load.

To host the CSS yourself, set `disable-css-injection` and either import it with your bundler or link to it, matching the version you load:

```javascript theme={"dark"}
import '@seamapi/react/index.css'
```

```html theme={"dark"}
<link
  rel="stylesheet"
  href="https://react.seam.co/v/5.1.0/dist/index.min.css"
/>
```

The components render in your page's DOM, not in a shadow root, and their class names start with `seam-`. Use `class-name` to add your own class to a component's container. The `seam-` class names themselves are not a stable API and may change between releases.

## Content Security Policy

If your site sets a Content Security Policy (CSP), allow the following sources:

| Directive | Source | Needed for |
| - | - | - |
| `script-src` | `https://react.seam.co` | Loading `ecosystem.js` or `elements.js` from the Seam CDN. Not needed if you bundle `@seamapi/react` yourself. |
| `connect-src` | `https://ecosystem.seam.co` | Fetching apps and device models from the Seam Ecosystem API. |
| `img-src` | `https://seam-ecosystem-media.fly.storage.tigris.dev` | App logos, manufacturer logos, and device images. |
| `style-src` | `https://react.seam.co` | The injected component stylesheet. Not needed with `disable-css-injection`. |
| `style-src` | `https://fonts.googleapis.com` | The injected font stylesheet. Not needed with `disable-font-injection`. |
| `font-src` | `https://fonts.gstatic.com` | The font files. Not needed with `disable-font-injection`. |

For example, with the default settings:

```
script-src 'self' https://react.seam.co;
connect-src 'self' https://ecosystem.seam.co;
img-src 'self' https://seam-ecosystem-media.fly.storage.tigris.dev;
style-src 'self' https://react.seam.co https://fonts.googleapis.com;
font-src 'self' https://fonts.gstatic.com
```

## Troubleshooting

When a request fails, the component shows a message in place of the list. The Seam Ecosystem API returns an error `type` that you can see in your browser's network tab.

<AccordionGroup>
  <Accordion title="An embed key is required to show this list on this website">
    The API returned `401 embed_key_required`. The component has no `embed-key`, and the page is not on a Seam-owned domain. Add `embed-key` to the element, or `embedKey` to the provider in React.
  </Accordion>

  <Accordion title="The embed key is invalid or has been revoked">
    The API returned `401 invalid_embed_key`. Check for a truncated or misquoted value, and confirm you are using the `eco_live_` embed key Seam sent you rather than a Seam publishable key or API key. If the key was revoked, email [support@getseam.com](mailto:support@getseam.com) for a new one.
  </Accordion>

  <Accordion title="The embed key is not allowed on this website">
    The API returned `403 origin_not_allowed`. The origin serving the page is not registered for your key. Check the scheme, the `www.` prefix, and the port, then email [support@getseam.com](mailto:support@getseam.com) with the exact origin to have it added.
  </Accordion>

  <Accordion title="Nothing renders at all">
    Confirm that the script tag includes `type="module"` and that the CDN URL loads. Custom elements upgrade once their definition loads, so a blocked or misspelled script URL leaves the element on the page with nothing inside it. If your site sets a CSP, check the browser console for blocked requests and see [Content Security Policy](#content-security-policy).
  </Accordion>

  <Accordion title="The component renders without styles">
    The stylesheet from `https://react.seam.co` did not load. Allow it in your CSP's `style-src`, or set `disable-css-injection` and [load the CSS yourself](#styles-and-fonts).
  </Accordion>

  <Accordion title="An app or device is missing, or its details look wrong">
    The components show live data from the Seam Ecosystem. To report a missing app or device, or incorrect details, email [support@getseam.com](mailto:support@getseam.com).
  </Accordion>
</AccordionGroup>

## Next Steps

* Set up [Compatible Apps](/docs/ui-components/overview/ecosystem-components/compatible-apps) or [Supported Devices](/docs/ui-components/overview/ecosystem-components/supported-devices).
* Try both components with sample data in the [interactive component library](https://react.seam.co/?path=/docs/ecosystem-supporteddevices--docs).
* Run the [plain HTML sample app](https://github.com/seamapi/seam-components-sample-apps/tree/main/ecosystem-web-components).

If you have questions or want to report an issue, email [support@getseam.com](mailto:support@getseam.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.