> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/id-fraud-shield-sdk/integration-guide/web-sdk/integration.md).

# Integration

### Sequence Diagram - ID Fraud Shield Web SDK Flow <a href="#environments-and-testing-with-the-sdk" id="environments-and-testing-with-the-sdk"></a>

<figure><img src="https://2033469942-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC2s0IISjZwzGfw8dm215%2Fuploads%2FsGnZqTcQjVFl5ejkbKgV%2Fidfs-web-sdk-flow.png?alt=media&amp;token=90f924ed-8f3f-43b7-b14e-2e0a83351a0e" alt=""><figcaption></figcaption></figure>

### Environments and Testing with the SDK <a href="#environments-and-testing-with-the-sdk" id="environments-and-testing-with-the-sdk"></a>

Two environments exist to support the Vida Web SDK integrations:

* 'sandbox' - to be used for testing and POC
* 'production' - to be used only in production apps

The Vida Web SDK offers two integration methods.

{% hint style="info" %}
**Note**: The library is Browser only, it does not support the Node Context.
{% endhint %}

### 1. Integration via Script Tag <a href="#id-1.-integration-via-script-tag" id="id-1.-integration-via-script-tag"></a>

The quickest and simplest way to integrate the Vida Web SDK is to use the package hosted via Vida as a script tag. You can include the SDK in your application by adding the script tag directly to your `index.html` file or dynamically using JavaScript.

{% tabs %}
{% tab title="Sandbox" %}
Add the following script tag for testing and POC purposes:

```java
<script src="https://web-sdk.vida.id/<VERSION>/sandbox/vida-id-fraud-shield.js"></script>
```

{% endtab %}

{% tab title="Production" %}
Use the following script tag for production applications:

```java
<script src="https://web-sdk.vida.id/<VERSION>/vida-id-fraud-shield.js"></script>
```

{% endtab %}
{% endtabs %}

Replace `<VERSION>` with the latest version provided to you (e.g., `1.0.0`).

**About Versioning**

Vida Web SDK follows **semantic versioning**, a widely used versioning convention that ensures clear communication about the compatibility and changes in the software. Semantic versioning uses a `MAJOR.MINOR.PATCH` format:

<table><thead><tr><th width="127.046875">Format</th><th>Description</th></tr></thead><tbody><tr><td><strong>MAJOR</strong></td><td>Introduces significant changes that may not be backward compatible.</td></tr><tr><td><strong>MINOR</strong></td><td>Adds new features while maintaining backward compatibility.</td></tr><tr><td><strong>PATCH</strong></td><td>Includes bug fixes and minor updates without changing existing features or compatibility.</td></tr></tbody></table>

### 2. Integration via NPM Package <a href="#id-2.-integration-via-npm-package" id="id-2.-integration-via-npm-package"></a>

You can integrate the Vida ID Fraud Shield SDK into your application as an npm package. This approach is ideal for modern web development workflows and allows better management of dependencies. TypeScript is officially supported.

To install the SDK, use either of the following commands based on your package manager:

**For Yarn**

```java
yarn add vida-id-fraud-shield
```

**For NPM**

```java
npm install vida-id-fraud-shield
```

{% hint style="info" %}
**Note:** A single package is published for all environments. Select your target environment at runtime by passing the env option to init():
{% endhint %}

This method ensures that the SDK is included in your project's `node_modules` directory, making it easy to manage and update.

### Update Content Security Policy (CSP) Whitelist & Network Whitelist <a href="#update-content-security-policy-csp-whitelist" id="update-content-security-policy-csp-whitelist"></a>

To ensure seamless functionality of the Vida Web SDK, update your Content Security Policy (CSP) and network whitelist to allow the following resource:

**script-src**

{% code expandable="true" %}

```java
Content-Security-Policy: script-src 'self' https://web-sdk.vida.id https://shield.vida.id;
```

{% endcode %}

**Additional CSP Directives** (Only required if you have these directives enforcement)

The SDK also makes API calls and loads pixel resources. Add the following to your connect-src and img-src.

{% tabs %}
{% tab title="Production" %}
{% code expandable="true" %}

```java
connect-src 'self' https://sdk-api.prod.vida.id https://shield.vida.id https://faro-collector-prod-ap-southeast-1.grafana.net;
img-src 'self' https://pixel-shield.vida.id;
```

{% endcode %}
{% endtab %}

{% tab title="Sandbox" %}
{% code expandable="true" %}

```java
script-src 'self' https://web-sdk.vida.id https://sandbox-shield.vida.id; 
connect-src 'self' https://sandbox-sdk-api.np.vida.id https://sandbox-shield.vida.id https://faro-collector-prod-ap-southeast-2.grafana.net;
img-src 'self' https://sandbox-pixel-shield.vida.id;
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Tip**: You can use `https://*.vida.id` in place of individual vida.id subdomains if your policy allows wildcards. The Grafana collector ( used for error/crash logging ) must always be added explicitly.
{% endhint %}

#### Network / Firewall Whitelist

Allow outbound HTTPS (port 443) to: (**only needed if SDK is used in an environment that enforces egress filtering or outbound firewall rules**)

{% tabs %}
{% tab title="Production" %}
{% code expandable="true" %}

```java
web-sdk.vida.id 
sdk-api.prod.vida.id 
shield.vida.id 
pixel-shield.vida.id 
faro-collector-prod-ap-southeast-1.grafana.net
```

{% endcode %}
{% endtab %}

{% tab title="Sandbox" %}
{% code expandable="true" %}

```java
web-sdk.vida.id 
sandbox-sdk-api.np.vida.id 
sandbox-shield.vida.id 
sandbox-pixel-shield.vida.id 
faro-collector-prod-ap-southeast-2.grafana.net
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Tip**: Use `*.vida.id` to cover all Vida-owned hosts with a single rule. The Grafana collector must still be whitelisted explicitly.\
\
No inbound ports are required. If TLS inspection is enabled, exclude these hosts to avoid certificate failures.
{% endhint %}