> For the complete documentation index, see [llms.txt](https://legacy-docs.usesmileid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://legacy-docs.usesmileid.com/integration-options/web-mobile-web/javascript-sdk-beta/usage.md).

# Usage

## Add the component

After installation and necessary imports:

1. Add the desired images capture markup to your page/component:

{% tabs %}
{% tab title="Selfie only" %}

```html
<selfie-capture-screens></selfie-capture-screens>
```

{% endtab %}

{% tab title="ID Document only" %}

```html
<document-capture-screens></document-capture-screens>
```

{% endtab %}

{% tab title="Selfie and Document" %}

```html
<smart-camera-web capture-id></smart-camera-web>
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
For **basic color theming,** add the **`theme-color`** attribute to the component with a valid css hex value

```html
<smart-camera-web theme-color="#7AAAFA"></smart-camera-web>
```

{% endhint %}

### Selfie Capture

Initially, you'll see this instruction screen (**unless this is turned off**), guiding the user on [best practices for good selfie capture](/further-reading/faqs/what-are-good-selfie-best-practices.md), this will be followed by the selfie capture screen prompting the user to present their face and a review screen:

<div align="center"><figure><img src="/files/55OouBZWwrd1nt6ut678" alt="" width="338"><figcaption><p>Instructions screen</p></figcaption></figure> <figure><img src="/files/ET30QRGpAClmNnHkFYbY" alt="" width="338"><figcaption><p>Take selfie screen</p></figcaption></figure> <figure><img src="/files/SqCH9W9vofNjUqLIhB1E" alt="" width="338"><figcaption><p>Selfie review screen</p></figcaption></figure></div>

{% hint style="success" %}
To turn off the instruction screen, add the **`hide-instructions`** attribute to the component

```html
<smart-camera-web hide-instructions></smart-camera-web>
```

{% endhint %}

### Document Capture

If the `capture-id` attribute is used, you will be presented with additional screens for document capture (front, back (optional by adding `hide-back-of-id` attribute), review):

<div><figure><img src="/files/oRRSVfBC0nPjzB8SankR" alt="" width="338"><figcaption><p>Document instruction screen</p></figcaption></figure> <figure><img src="/files/UmTN820LRizPswvdGrll" alt="" width="338"><figcaption><p>Document capture screen</p></figcaption></figure> <figure><img src="/files/PmkJMPQiB7Z1j797ZEVg" alt="" width="338"><figcaption><p>Document review screen</p></figcaption></figure></div>

### Capture front of document only

```html
<!-- Example: Capture front of document only -->
<document-capture-screens hide-back-of-id></document-capture-screens>
```

```html
<!-- Example: Capture selfie and front of document only -->
<smart-camera-web capture-id hide-back-of-id></smart-camera-web>
```

### Document auto-capture

The new document auto-capture engine captures document images automatically, ensuring documents are captured at the highest possible quality. During a document capture session, the component continuously attempts auto-capture. If it cannot complete auto-capture within the `auto-capture-timeout` window (10 seconds by default), a manual-capture fallback button appears so the user can capture the document themselves.

In the current major version the new auto-capture is **opt-in**: enable it with the `auto-capture-enabled` attribute. **The next major version will enable it by default.** Once enabled, control the mode with the `auto-capture` attribute:

```html
<!-- Auto-capture with manual fallback -->
<document-capture-screens auto-capture-enabled="true" auto-capture="autoCapture"></document-capture-screens>

<!-- Auto-capture only, no manual fallback -->
<document-capture-screens auto-capture-enabled="true" auto-capture="autoCaptureOnly"></document-capture-screens>

<!-- Manual capture only -->
<document-capture-screens auto-capture-enabled="true" auto-capture="manualCaptureOnly"></document-capture-screens>
```

Adjust how long the component attempts auto-capture before showing the manual-capture button with `auto-capture-timeout` (in milliseconds):

```html
<document-capture-screens auto-capture-enabled="true" auto-capture="autoCapture" auto-capture-timeout="10000"></document-capture-screens>
```

These attributes work the same way on the `smart-camera-web capture-id` component.

{% hint style="info" %}
The `auto-capture` and `auto-capture-timeout` attributes only take effect when `auto-capture-enabled` is `true`. While it is unset/`false` (the current default), the legacy capture behaviour is used and these attributes are ignored.
{% endhint %}

{% hint style="warning" %}
We strongly advise leaving `auto-capture` set to `autoCapture`. Only switch to `autoCaptureOnly` or `manualCaptureOnly` if you have a specific reason to, and be aware of the performance differences between auto-capture and manual capture. See [Document auto-capture](/further-reading/faqs/document-autocapture.md) for more background.
{% endhint %}

**Migrating to the new auto-capture**

To adopt the new auto-capture engine ahead of the next major version, add `auto-capture-enabled="true"` and test your document capture flow. When the next major version ships, auto-capture is on by default, so no further action is needed.

### Handle events

Handle the **`smart-camera-web.publish`** event:

When the user approves the captured image, a `smart-camera-web.publish` event is dispatched. The event returns a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent) payload in `e.detail`.

Here's a script example to handle the event and send data to a backend endpoint:

```javascript
<script>
  const app = document.querySelector("smart-camera-web");

  const postContent = async (data) => {
    const options = {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(data),
    };

    try {
      const response = await fetch("/", options);
      const json = await response.json();

      return json;
    } catch (e) {
      throw e;
    }
  };

  app.addEventListener("smart-camera-web.publish", async (e) => {
    try {
      const response = await postContent(e.detail);

      console.log(response);
    } catch (e) {
      console.error(e);
    }
  });
</script>
```

{% hint style="warning" %}
Note: when using the `selfie-capture-screens` listen to the `selfie-capture-screens.publish` event to get the selfie and liveness images.

For `document-capture-screens` listen to the `document-capture-screens.publish` event for the document image.

More details [here](#handling-events)
{% endhint %}

### Process request on backend

The provided backend endpoint uses the NodeJS Server to Server library and ExpressJS:

```javascript
const express = require("express");
const { v4: UUID } = require("uuid");

if (process.env.NODE_ENV === "development") {
  const dotenv = require("dotenv");

  dotenv.config();
}

const SIDCore = require("smile-identity-core");
const SIDSignature = SIDCore.Signature;
const SIDWebAPI = SIDCore.WebApi;

const app = express();

app.use(express.json({ limit: "500kb" }));
app.use(express.static("public"));

app.post("/", async (req, res, next) => {
  try {
    const { PARTNER_ID, API_KEY, SID_SERVER } = process.env;
    const connection = new SIDWebAPI(
      PARTNER_ID,
      "/callback",
      API_KEY,
      SID_SERVER,
    );

    const partner_params_from_server = {
      user_id: `user-${UUID()}`,
      job_id: `job-${UUID()}`,
      job_type: 4, // job_type is the product which enrolls a user using their selfie
    };

    const {
      images,
      partner_params: { libraryVersion },
    } = req.body;

    const options = {
      return_job_status: true,
    };

    const partner_params = Object.assign({}, partner_params_from_server, {
      libraryVersion,
    });

    const result = await connection.submit_job(
      partner_params,
      images,
      {},
      options,
    );

    res.json(result);
  } catch (e) {
    console.error(e);
  }
});

// NOTE: This can be used to process responses. don't forget to add it as a callback option in the `connection` config on L22
// https://docs.usesmileid.com/further-reading/faqs/how-do-i-setup-a-callback
app.post("/callback", (req, res, next) => {});

app.listen(process.env.PORT || 4000);
```

{% hint style="success" %}
This approach can also be achieved using other [Server to Server libraries](https://docs.usesmileid.com/integration-options/server-to-server).
{% endhint %}

## Handling Events

## Selfie and liveness images

To receive the images after they have been captured, you can listen to the custom event `selfie-capture-screens.publish`. The data posted to this event has the structure:

```javascript
{
  "detail": {
    "images": [{ "image": "base64 image", "image_type_id": "" }],
    "meta": {
      "version": "version of the library in use"
    }
  }
}
```

### Handling the publish event

```javascript
document
  .querySelector("selfie-capture-screens")
  .addEventListener("selfie-capture-screens.publish", function (event) {
    console.log(event.detail);
  });
```

### Handling the cancel event

```javascript
document
  .querySelector("selfie-capture-screens")
  .addEventListener("selfie-capture-screens.cancelled", function (event) {
    console.log(event.detail);
  });
```

### Handling the back event

```javascript
document
  .querySelector("selfie-capture-screens")
  .addEventListener("selfie-capture-screens.back", function (event) {
    console.log(event.detail);
  });
```

## Document image

Capture events emit `document-capture-screens.publish`, providing captured images and metadata:

```javascript
{
  "detail": {
    "images": [{ "image": "base64-encoded image", "image_type_id": "" }],
    "meta": {
      "version": "library version"
    }
  }
}
```

### Handling the publish event

```javascript
document
  .querySelector("document-capture-screens")
  .addEventListener("document-capture-screens.publish", function (event) {
    console.log(event.detail);
  });
```

### Handling the cancel event

```javascript
document
  .querySelector("document-capture-screens")
  .addEventListener("document-capture-screens.cancelled", function (event) {
    console.log(event.detail);
  });
```

### Handling the back event

```javascript
document
  .querySelector("document-capture-screens")
  .addEventListener("document-capture-screens.back", function (event) {
    console.log(event.detail);
  });
```

## Supported Attributes

The `smart-camera-web` component supports the following attributes:

| Attribute                      | Type   | Default       | Description                                                                                                                                                                                                                                                            |
| ------------------------------ | ------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow-agent-mode`             | String | -             | Enables agent-assisted capture mode. Set to `true` to enable.                                                                                                                                                                                                          |
| `allow-legacy-selfie-fallback` | String | -             | Enables fallback to legacy selfie capture mode when the primary capture method fails or is unavailable. Set to `true` to enable.                                                                                                                                       |
| `auto-capture-enabled`         | String | `false`       | Master switch for the new document auto-capture engine. Defaults to `false` in the current major version; set to `true` to opt in early. The next major version will default it to `true`. When not enabled, `auto-capture` and `auto-capture-timeout` have no effect. |
| `auto-capture`                 | String | `autoCapture` | Controls the document capture mode. Values: `autoCapture` (auto-capture with manual fallback), `autoCaptureOnly`, or `manualCaptureOnly`. Only applies when `auto-capture-enabled` is `true`. See [Document auto-capture](#document-auto-capture).                     |
| `auto-capture-timeout`         | Number | `10000`       | Time in milliseconds before the manual-capture fallback button appears during auto-capture. Only applies when `auto-capture` is `autoCapture`.                                                                                                                         |
| `capture-id`                   | -      | -             | When present, enables ID document capture flow after selfie capture.                                                                                                                                                                                                   |
| `document-capture-modes`       | String | `camera`      | Specifies the allowed capture modes for documents. Values: `camera`, `upload`, or `camera,upload`.                                                                                                                                                                     |
| `hide-attribution`             | -      | -             | When present, hides the SmileID attribution/branding.                                                                                                                                                                                                                  |
| `hide-back-of-id`              | -      | -             | When present, skips capturing the back of the ID document.                                                                                                                                                                                                             |
| `hide-back-to-host`            | -      | -             | When present, hides the back button that returns to the host application. Alias: `hide-back`.                                                                                                                                                                          |
| `hide-instructions`            | -      | -             | When present, skips the instruction screens and goes directly to camera permission.                                                                                                                                                                                    |
| `show-navigation`              | -      | -             | When present, shows navigation controls in the UI.                                                                                                                                                                                                                     |
| `theme-color`                  | String | `#001096`     | Custom theme color for the component UI. Accepts any valid CSS color value.                                                                                                                                                                                            |
| `title`                        | String | -             | Custom title text displayed in the component header.                                                                                                                                                                                                                   |

## Compatibility <a href="#compatibility" id="compatibility"></a>

`SmartCameraWeb` is compatible with most JavaScript frameworks and libraries. For integration with [ReactJS](https://reactjs.org/), refer to this [tutorial](https://www.robinwieruch.de/react-web-components) due to React-WebComponents compatibility issues.

Please see the [trouble shooting guide here](/further-reading/troubleshooting/image-capture-issues-on-web-client.md#problem-camera-not-loading) for situations where the camera is not loading.

## Support <a href="#support" id="support"></a>

Tested on the latest versions of Chrome, Edge, Firefox, and Safari. If compatibility issues arise on certain browsers, please notify us.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://legacy-docs.usesmileid.com/integration-options/web-mobile-web/javascript-sdk-beta/usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.