# Web SDK

## Overview

The Amondo Web SDK allows you to embed Imprints directly into your website or web application.\
It provides options for configuration, analytics, and event handling so you can fully control the integration.

Use the Web SDK if you want to:

* Display a published Imprint on your website
* Configure analytics and cookie consent
* Capture and respond to Amondo events

## Installation

Include the SDK by adding the following script to your page:

```javascript
<script async defer src="https://static.amondo.com/web-sdk/4/amondo-web-sdk.js" onload="amondo_init()"></script>
```

The script will always load the latest version 4 of the SDK.\
If you need a specific version, see [Using a Specific Version](#using-a-specific-version).

## Options

When creating an Imprint, you can pass the following options:

```javascript
{
  id: "UUID",                    // required
  isCookieConsentGiven: boolean, // optional
  isAnalyticsEnabled: boolean,   // optional
  videoAdType: "clip" | "thumbnail", // optional
  clipDuration: number,          // optional
  analytics: {                   // optional
    distinctId: string,          // optional
    options: Record<string, any> // optional
  }
}
```

### General options

`id`\
The unique Imprint identifier. Required.

`isCookieConsentGiven`\
Boolean value indicating whether cookies may be set. Default: false.

`isAnalyticsEnabled`\
Boolean value enabling or disabling analytics tracking. Default: true.

`videoAdType`\
Controls how videos render in ads mode before user interaction. `"clip"` plays a low-quality muted video. `"thumbnail"` shows a static image with a play button instead. Default: `"clip"`.

`clipDuration`\
Duration in seconds for ads-mode low-quality video clips (`videoAdType: "clip"`). Rounded to one decimal by SDK. Default: `1`.

### Analytics options

`analytics.distinctId`\
Custom user identifier for analytics tracking.

`analytics.options`\
Additional properties sent alongside each analytics event.

## Basic usage

Add a container element and initialize the SDK:

```html
<div id="amondo-container"></div>

<script>
  function amondo_init() {
    var container = document.querySelector("#amondo-container");
    amo.imprint.create(container, {
      id: "00000000-0000-0000-0000-000000000000",
      isCookieConsentGiven: false,
      isAnalyticsEnabled: false
    });
  }
</script>
```

````

## Using a specific version

The default link always points to the latest SDK in version 4:

```javascript
https://static.amondo.com/web-sdk/4/amondo-web-sdk.js
````

If needed, you can lock to a specific version by editing the URL, for example:

```javascript
https://static.amondo.com/web-sdk/4.2.1/amondo-web-sdk.js
```

## Advanced configuration (optional)

* Styling with CSS variables
* Embedding multiple Imprints on one page
* Lazy loading / dynamic embedding

## Intercepting Analytics Events

The SDK dispatches all analytics events as `CustomEvent` on `window` with event name `amondoEvent`. Use this for debugging or custom analytics pipelines.

### Listening for Events

```javascript
window.addEventListener('amondoEvent', (event) => {
  console.log(event.detail.event)  // event name: "imprint_viewed", "tile_clicked", etc.
  console.log(event.detail)        // full payload with properties
})
```

### Event Structure

Each event contains:

* `event` - event name (e.g. `imprint_viewed`, `slide_viewed`, `tile_clicked`)
* Additional properties depending on event type (imprint\_id, tile\_id, imprint\_time\_ms, etc.)

## Troubleshooting

Common issues when using the Web SDK:

* **Imprint not loading** → Check the `id` value is correct and from the production environment.
* **Analytics not working** → Ensure `isAnalyticsEnabled` is set to true and cookie consent is given.

## Related pages

* [CSS Variables](/developer-guides/css-variables.md)
* [Analytics Overview](/platform-guides/measure/analytics-overview.md)
* [API Reference](/developer-guides/api-reference.md)


---

# Agent Instructions: 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:

```
GET https://docs.amondo.com/developer-guides/websdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.