> For the complete documentation index, see [llms.txt](https://docs.amondo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amondo.com/developer-guides/websdk.md).

# 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

The SDK renders the published Imprint layout from Amondo, including supported activation Tiles such as Clickthrough, Quiz, Poll, Reveal, QR Code and Form Tiles. QR Code Tiles and Form Tiles with multiple-choice and Yes/No inputs do not require additional integration configuration.

Form Tiles use the public form page renderer inside embedded Imprints. They support client-side cutoff handling, per-field validation and closed-state messaging when a submission deadline has passed. Standalone hosted form links are available only when a standalone form page has been published.

## 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
  analytics: {                   // optional
    userId: string,              // optional
    options: Record<string, any>, // optional
    viewport: {                  // optional
      width: number,             // optional
      height: number,            // optional
      scrollY: number            // optional
    },
    imprintViewedThresholdPercent: number // 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.

Unit-level mobile scroll direction is read from the published Imprint layout. The Web SDK applies that mobile behaviour automatically and does not expose a separate integration option for it.

### Media delivery

For Cloudinary-hosted media, the Web SDK uses server-built delivery URL templates from the published Imprint response. The SDK selects an appropriate sized image, video or poster URL for the rendered layout, uses automatic format and quality negotiation, and does not upscale images beyond their original size.

### Analytics options

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

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

`analytics.viewport.width` and `analytics.viewport.height`\
Host-provided page viewport dimensions in CSS pixels. Provide both values together. When both are valid positive numbers, the SDK sends them on events as `viewport_w` and `viewport_h`, and sets `viewport_source` to `host_provided`.

`analytics.viewport.scrollY`\
Host-provided page scroll offset in CSS pixels. When supplied as a finite number, the SDK sends it on events as `scroll_y`.

If `analytics.viewport` is omitted or incomplete, the SDK measures the viewport from `visualViewport` or `window.innerWidth`/`window.innerHeight` and sets `viewport_source` to `sdk_measured`. If a usable pair of dimensions is unavailable, dimensions may be `null` and `viewport_source` is `unavailable`.

`analytics.imprintViewedThresholdPercent`\
Percentage of the Imprint that must be visible before `imprint_viewed` fires. Default: `0`.

## Basic usage

Add a container element and initialise 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, for example `imprint_viewed`, `imprint_qualified`, `tile_clicked` or `cta_clicked`
* Additional properties depending on event type, such as `imprint_id`, `tile_id`, `destination_url`, `viewport_w`, `viewport_h`, `scroll_y`, `viewport_source` and `imprint_time_ms`
* Media URL properties, such as `media_url` and `outcome_media_url`, use the SDK-selected media URL. For Cloudinary-hosted media, this is the selected delivery URL when available, with `publicUrl` or `secureUrl` as the fallback.
* Click and tap events such as `tile_clicked`, `source_clicked`, `cta_clicked`, `reveal_started` and `story_clicked` can include container-relative heat-map coordinates: `imprint_click_x_px` and `imprint_click_y_px`.

See [Web SDK Events](/developer-guides/websdk-events.md) for the full runtime event reference.

Form Tiles emit a form funnel across embedded and standalone surfaces. Events include `form_viewed`, `form_started`, `field_filled`, `form_submitted` and `form_completed`.

## 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)
* [Web SDK Events](/developer-guides/websdk-events.md)
* [Media Delivery](/developer-guides/media-delivery.md)
* [Analytics Overview](/platform-guides/measure/analytics-overview.md)
* [API Reference](/developer-guides/api-reference.md)