> 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-events.md).

# Web SDK Events

The Web SDK emits analytics events automatically when an Imprint is embedded on a page. Events are sent to Amondo analytics when analytics is enabled, and are also dispatched on `window` as `amondoEvent` for debugging or custom analytics pipelines.

```javascript
window.addEventListener('amondoEvent', (event) => {
  console.log(event.detail.event)
  console.log(event.detail)
})
```

Each dispatched event has an `event` field containing the event name. The remaining fields depend on the event type and the current Imprint, format, Tile and Frame context.

## Common Properties

These properties are registered for the Web SDK session and appear on most events.

| Property                 | Description                                                                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sdk_version`            | Web SDK version.                                                                                                                                    |
| `imprint_id`             | Published Imprint identifier.                                                                                                                       |
| `imprint_title`          | Imprint title.                                                                                                                                      |
| `imprint_mode`           | Imprint format, for example `GALLERY`, `CAROUSEL` or `STORY`.                                                                                       |
| `team_id`                | Team identifier for the Imprint.                                                                                                                    |
| `rendering_mode`         | `NORMAL` or `ADS`.                                                                                                                                  |
| `tiles_total`            | Total number of Tiles in the Imprint, when available.                                                                                               |
| `imprint_tag_analytics`  | Optional Imprint analytics tag.                                                                                                                     |
| `amo_user_id`            | Optional user identifier passed through `analytics.userId`.                                                                                         |
| `connection_type`        | Browser network effective connection type, when available.                                                                                          |
| `browser_language`       | Browser language.                                                                                                                                   |
| `$device_type`           | Device type inferred by PostHog.                                                                                                                    |
| `prefers_dark_mode`      | Browser colour scheme preference.                                                                                                                   |
| `prefers_reduced_motion` | Browser reduced-motion preference.                                                                                                                  |
| `viewport_w`             | Page viewport width in CSS pixels. Uses `analytics.viewport.width` when a valid host viewport is provided; otherwise SDK-measured when available.   |
| `viewport_h`             | Page viewport height in CSS pixels. Uses `analytics.viewport.height` when a valid host viewport is provided; otherwise SDK-measured when available. |
| `scroll_y`               | Page scroll offset in CSS pixels. Uses `analytics.viewport.scrollY` when supplied; otherwise SDK-measured when available.                           |
| `viewport_source`        | Viewport measurement source: `host_provided`, `sdk_measured` or `unavailable`.                                                                      |

Custom values passed in `analytics.options` are added to the session and sent with Web SDK events. Viewport properties are registered after `analytics.options`, so SDK viewport fields take precedence over custom values with the same names.

`media_url` and `outcome_media_url` contain the media URL used by the SDK for the Tile or Reveal outcome. For Cloudinary-hosted media, the SDK uses the selected delivery URL when available and falls back to `publicUrl` or `secureUrl`.

Click and tap analytics can include container-relative interaction coordinates for heat-map analysis. `imprint_click_x_px` and `imprint_click_y_px` are measured in pixels from the top-left of the SDK container, rounded and clamped to the container bounds. Keyboard-generated clicks do not include these properties.

## Timing Properties

`imprint_time_ms` is added to captured events. It measures accumulated time while the Imprint is considered in view. The timer pauses when the Imprint leaves view or the page becomes hidden. `$pageleave` also receives `imprint_time_ms` before the event is sent.

The default Imprint viewed threshold is 0%. Integrations can set `analytics.imprintViewedThresholdPercent` to require a higher visible percentage before `imprint_viewed` fires.

`tile_time_ms` is only added to `tile_left`. It measures wall-clock time from the qualified `tile_viewed` event to leave or cleanup.

`time_spent_ms` appears on Frame events that measure active Frame dwell time.

## Page and Imprint Events

| Event               | Runs when                                                                                                            | Key properties                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `$pageview`         | Web SDK analytics initialises. Emitted across supported rendering modes, including `ADS`.                            | Common properties, `imprint_time_ms`.                                       |
| `$pageleave`        | The browser page is left or hidden. Emitted once per SDK instance across supported rendering modes, including `ADS`. | Common properties, current page, slide or story context, `imprint_time_ms`. |
| `imprint_viewed`    | The Imprint reaches the configured viewed threshold.                                                                 | Common properties, `imprint_time_ms`.                                       |
| `imprint_qualified` | The Imprint stays sufficiently visible for 1 continuous second. Can fire again after leaving and re-entering view.   | Common properties, `imprint_time_ms`.                                       |
| `imprint_left`      | The Imprint leaves the viewport after being viewed.                                                                  | Common properties, `scrolled_percentage`, `imprint_time_ms`.                |
| `imprint_scrolled`  | A Gallery Imprint scroll percentage changes.                                                                         | Common properties, `scrolled_percentage`, `imprint_time_ms`.                |

## Format Events

| Event           | Format   | Runs when                                                 | Key properties                                                                                                          |
| --------------- | -------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `page_changed`  | Gallery  | User changes Gallery page.                                | `page_id`, `page_index`, `opened_from_url`, `changed_from_frame`, `imprint_time_ms`.                                    |
| `slide_viewed`  | Carousel | Carousel slide is viewed, including initial active slide. | `slide_id`, `slide_index`, `imprint_time_ms`.                                                                           |
| `slide_changed` | Carousel | User navigates to another slide by arrow or swipe.        | `slide_id`, `slide_index`, `subsequent_slide_id`, `subsequent_slide_index`, `direction`, `imprint_time_ms`.             |
| `story_viewed`  | Stories  | Story section appears in the viewport.                    | `story_id`, `story_title`, `story_index`, `story_state`, `imprint_time_ms`.                                             |
| `story_clicked` | Stories  | User clicks a story cover or highlight.                   | `story_id`, `story_title`, `story_index`, `story_state`, `imprint_click_x_px`, `imprint_click_y_px`, `imprint_time_ms`. |
| `story_opened`  | Stories  | Story opens in Frame view.                                | `story_id`, `story_title`, `story_index`, `story_state`, `imprint_time_ms`.                                             |
| `story_left`    | Stories  | Story section leaves the viewport after being viewed.     | `story_id`, `story_title`, `story_index`, `story_state`, `imprint_time_ms`.                                             |

## Tile and Frame Events

| Event                 | Runs when                                                                                      | Key properties                                                                                                                                                                                                       |
| --------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tile_viewed`         | A Tile is at least 50% visible after the scroll-stable delay. Default delay is 300ms.          | `tile_id`, `tile_type`, `tile_source`, `media_url`, `media_type`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                           |
| `tile_left`           | A previously viewed Tile leaves view or unmounts.                                              | `tile_id`, `tile_type`, `tile_source`, `media_url`, `media_type`, `tile_tag_analytics`, `tile_time_ms`, `imprint_time_ms`.                                                                                           |
| `tile_clicked`        | User clicks or taps a Tile.                                                                    | `tile_id`, `tile_type`, `tile_source`, `media_url`, `media_type`, `tile_tag_analytics`, `imprint_click_x_px`, `imprint_click_y_px`, `imprint_time_ms`.                                                               |
| `frame_viewed`        | Frame opens or Frame navigation lands on a new Tile.                                           | `tile_id`, `tile_type`, `tile_source`, `opened_from_url`, `media_url`, `media_type`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                        |
| `frame_changed`       | User or autoplay moves to another Tile in Frame view. Navigation is cooldown-limited to 200ms. | `tile_id`, `subsequent_tile_id`, `direction`, `changed_method`, `time_spent_ms`, `media_url`, `media_type`, `tile_tag_analytics`, `imprint_time_ms`.                                                                 |
| `frame_closed`        | Frame closes or is dismissed.                                                                  | `tile_id`, `tile_type`, `tile_source`, `time_spent_ms`, `media_url`, `media_type`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                          |
| `frame_story_changed` | Frame navigation crosses from one story section to another.                                    | `prev_story_id`, `new_story_id`, `direction`, `story_state`, `imprint_time_ms`.                                                                                                                                      |
| `source_clicked`      | User clicks a source or attribution link.                                                      | `tile_id`, `tile_type`, `tile_source`, `destination_url`, `tile_tag_analytics`, `imprint_click_x_px`, `imprint_click_y_px`, `imprint_time_ms`.                                                                       |
| `cta_clicked`         | User clicks a Clickthrough, Quiz, Poll or Reveal CTA.                                          | `tile_id`, `tile_type`, `tile_source`, `destination_url`, `cta_label`, `outcome_id`, `outcome_media_url`, `outcome_media_type`, `tile_tag_analytics`, `imprint_click_x_px`, `imprint_click_y_px`, `imprint_time_ms`. |

## Video Events

| Event                    | Runs when                                                                                   | Key properties                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `video_played`           | A video crosses a tracked progress point. The `duration` value is `0`, `50`, `90` or `100`. | `tile_id`, `media_url`, `duration`, `loop`, `tile_tag_analytics`, `imprint_time_ms`. |
| `video_midpoint_reached` | First play of a video reaches 50%. This fires once for loop `0`.                            | `tile_id`, `media_url`, `tile_tag_analytics`, `imprint_time_ms`.                     |

## Activation Tile Events

| Event               | Tile type | Runs when                                                                    | Key properties                                                                                                                                                          |
| ------------------- | --------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quiz_started`      | Quiz      | User starts a Quiz Tile.                                                     | `tile_id`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                                     |
| `question_answered` | Quiz      | User selects an answer.                                                      | `tile_id`, `question_index`, `answer_index`, `is_correct`, `tile_tag_analytics`, `imprint_time_ms`.                                                                     |
| `question_finished` | Quiz      | User advances from a non-final question.                                     | `tile_id`, `question_index`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                   |
| `quiz_finished`     | Quiz      | User completes all quiz questions.                                           | `tile_id`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                                     |
| `quiz_retried`      | Quiz      | User restarts a completed quiz.                                              | `tile_id`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                                     |
| `quiz_shared`       | Quiz      | User shares the quiz result.                                                 | `tile_id`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                                     |
| `poll_voted`        | Poll      | Vote submission succeeds and results are returned.                           | `tile_id`, `option_id`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                        |
| `poll_shared`       | Poll      | User shares poll results.                                                    | `tile_id`, `tile_tag_analytics`, `imprint_time_ms`.                                                                                                                     |
| `reveal_started`    | Reveal    | User first interacts with a Reveal Tile. Fires once per Tile instance.       | `tile_id`, `reveal_type`, `outcome_id`, `outcome_media_url`, `outcome_media_type`, `tile_tag_analytics`, `imprint_click_x_px`, `imprint_click_y_px`, `imprint_time_ms`. |
| `tile_scratched`    | Reveal    | Scratch Reveal progress milestone is reached. Fires once for each milestone. | `tile_id`, `reveal_type`, `outcome_id`, `outcome_media_url`, `outcome_media_type`, `scratch_milestone`, `scratch_percentage`, `tile_tag_analytics`, `imprint_time_ms`.  |
| `reveal_completed`  | Reveal    | Reveal outcome is shown.                                                     | `tile_id`, `reveal_type`, `outcome_id`, `outcome_media_url`, `outcome_media_type`, `time_to_reveal_ms`, `scratch_percentage`, `tile_tag_analytics`, `imprint_time_ms`.  |

`tile_scratched` is emitted only for Scratch Reveal Tiles. The tracked milestones are `10_percent`, `50_percent` and `done`. Broken-cover auto-reveal does not emit `tile_scratched`.

## Form Tile Events

Form Tiles emit a drop-off funnel. The same events fire on two surfaces: the Web SDK **embed** (a Form Tile rendered inside an Imprint) and the **standalone** public form page. Every form event carries `form_surface` (`embed` or `standalone`) so the two surfaces can be segmented. Form events fire client-side only.

A form moves through up to three screens — intro (optional), content (the fields) and final (confirmation) — and the events map onto those transitions plus the submit outcomes.

| Event                 | Runs when                                                                                                               | Frequency      |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------- |
| `form_intro_viewed`   | The intro screen renders. Only emitted when the form has an intro screen.                                               | Once per visit |
| `form_viewed`         | The content/fields screen renders. This is the funnel denominator and fires for both intro and intro-less forms.        | Once per visit |
| `form_started`        | The first field loses focus, regardless of whether a value was entered.                                                 | Once per visit |
| `field_filled`        | A field is completed: text, email or date on blur with a value; checkbox or choice on change; media on upload complete. | Once per field |
| `form_submit_blocked` | Submit is blocked client-side before any mutation runs. Carries `reason`.                                               | Per attempt    |
| `form_submitted`      | The submit mutation resolves successfully.                                                                              | Per success    |
| `form_submit_failed`  | The submit mutation rejects from a server or network error.                                                             | Per failure    |
| `form_completed`      | The final/confirmation screen renders. Roughly 1:1 with `form_submitted` on the happy path.                             | Once per visit |
| `form_resubmitted`    | The visitor starts a second pass via the resubmit action. The once-per-visit view events do not re-fire.                | Per resubmit   |

### Form event properties

Every form event carries:

| Property             | Type   | Notes                                                       |
| -------------------- | ------ | ----------------------------------------------------------- |
| `tile_id`            | String | The Form Tile id. Primary per-form identifier.              |
| `form_surface`       | String | `embed` or `standalone`.                                    |
| `form_tag_analytics` | String | Present only when the Tile has an author-set analytics tag. |

On the **embed** surface, form events also inherit the Web SDK session [common properties](#common-properties), including `imprint_id` and `team_id` (`team_id` is embed-only). On the **standalone** surface, form events also carry `form_slug` (the public page slug), and the page emits `$pageview` and `$pageleave`.

`field_filled` adds:

| Property         | Type    | Notes                                                                 |
| ---------------- | ------- | --------------------------------------------------------------------- |
| `field_id`       | String  | The field id.                                                         |
| `field_type`     | String  | For example `text`, `email`, `date`, `checkbox`, `choice` or `media`. |
| `field_label`    | String  | The field's author-defined label.                                     |
| `field_required` | Boolean | Whether the field is required.                                        |
| `field_position` | Numeric | The field's index in the form.                                        |

`form_submit_blocked` adds `reason`, one of `missing_required`, `invalid_email`, `media_uploading` or `empty_form`.

No user-entered values are ever sent. Form event payloads are a fixed allowlist of field metadata only — never field contents, including no answer values.

### Reading the funnel

The primary drop-off funnel is:

`form_viewed` → `form_started` → `field_filled` (per field) → `form_submitted`

Segment by `form_surface`, `tile_id` or `form_slug`, and `form_tag_analytics`. Submit failures, client-side blocks and silent abandonment are distinguishable through `form_submit_failed`, `form_submit_blocked` and the absence of `form_submitted`.

Measurement caveats:

* `form_started` and `field_filled` rely on blur, so autofill or Enter-to-submit without a blur can under-count.
* The funnel localizes drop-off to the last *completed* field, not the last *reached* field. A focused-but-empty field emits nothing.
* An embed Frame reopen (remount) re-fires the once-per-visit events. Dedupe is in-memory per mount.

## Events Not Currently Emitted

The Web SDK does not currently emit canonical events for `ugc_upload`, `competition_entry` or a generic `share`. Share behaviour is currently represented by `quiz_shared` and `poll_shared`. Form funnel events are documented under [Form Tile Events](#form-tile-events).

Do not add `tile_dwell_3s` or `tile_dwell_10s` as separate events. Derive dwell thresholds from `tile_left.tile_time_ms`.